Elevation APIs in this codebase: strengths and weaknesses

[turbomam]

Elevation Inference Approaches

This repository uses 4 different elevation data providers to infer elevation from latitude and longitude coordinates:

1. USGS EPQS (US Geological Survey Elevation Point Query Service)

• Coverage: US territories only (CONUS, Alaska, Hawaii, Puerto Rico, etc.)
• Accuracy: ±1-3 meters (highest precision)
• Data source: https://epqs.nationalmap.gov/v1/json
• API key: Not required
• Implementation: biosample_enricher/elevation/providers/usgs.py:14
• Pricing: FREE - Unlimited usage
• Rate limits: None specified (reasonable use expected)
• Throughput: No enforced limits; natural request pacing recommended

2. Google Maps Elevation API

• Coverage: Global
• Accuracy: ±1-10 meters (varies by region)
• Data source: https://maps.googleapis.com/maps/api/elevation/json
• API key: Required (GOOGLE_MAIN_API_KEY)
• Implementation: biosample_enricher/elevation/providers/google.py:14
• Pricing:
  • https://mapsplatform.google.com/pricing/
  • 5,000 free per month
  • $5/1k after that
  • See https://developers.google.com/maps/documentation/elevation/usage-and-billing
• Rate limits: 50 QPS (queries per second) for standard accounts
• Throttling: Test implementation includes ~8 QPS guard (tests/conftest.py:131)

3. Open Topo Data

• Coverage: Global (multiple datasets: SRTM 30m/90m, ASTER 30m, EU-DEM)
• Accuracy: ±10-30 meters depending on dataset
• Data source: https://api.opentopodata.org/v1/{dataset}
• API key: Not required
• Implementation: biosample_enricher/elevation/providers/open_topo_data.py:13
  • Smart variant: Includes SmartOpenTopoDataProvider that auto-selects datasets
• Pricing: FREE (community service)
• Rate limits:
  • 100 requests/second
  • 1,000 requests/day for anonymous use
• Throttling: Daily quota; consider for high-volume batch jobs

4. OpenElevation (OSM-based)

• Coverage: Global (SRTM 90m data)
• Accuracy: ±10-30 meters
• Data source: https://api.open-elevation.com/api/v1/lookup
• API key: Not required
• Implementation: biosample_enricher/elevation/providers/osm.py:13
• Pricing: FREE (community service)
• Rate limits: No official limits documented
• Throttling: Respectful use recommended (~1 request/second suggested)

Intelligent Routing Strategy

The system uses coordinate classification to intelligently route requests (biosample_enricher/elevation/service.py:158-210):

For US coordinates:

1. USGS (highest accuracy)
2. Google Maps (reliable fallback)
3. Open Topo Data
4. OpenElevation

For international coordinates:

1. Google Maps (best global coverage)
2. Open Topo Data (free alternative)
3. OpenElevation

For ocean coordinates:

• Prioritizes Google Maps and Open Topo Data over USGS

Key Features

• Caching: All requests go through centralized HTTP cache (biosample_enricher/http_cache.py)
• Fallback: If one provider fails, automatically tries the next in priority order
• Multi-provider observations: Returns elevation data from all available providers for comparison
• Best elevation selection: Sorts by distance to input and spatial resolution to pick the best value
• Rate limiting: Built-in respect for provider limits
  • Google: ~8 QPS guard in tests
  • OSM Nominatim: 1 request/second enforced
  • Natural pacing through sequential calls

Cost-Benefit Recommendations

For Development/Testing:

• Use free providers: USGS + Open Topo Data + OSM
• Open Topo Data's 1,000/day limit is sufficient for most development

For Production (US-focused):

• USGS as primary (free, highest accuracy)
• Add Google API key for backup/validation
• Costs minimal if staying within 40k/month free tier

For Production (Global):

• Google API key highly recommended
• Consider costs: At $5/1,000 requests, 100k requests = $500/month
• Cache aggressively to minimize API calls

For High-Volume Batch Processing:

• Prefer Open Topo Data for large datasets (watch 1k/day limit)
• Use Google strategically for critical/high-accuracy needs
• Consider Google's enterprise pricing for >1M requests/month