API Documentation

REST API for elevation and terrain analysis. All responses are JSON.

Quickstart

Get your API key by emailing [email protected]

# Example request
curl "https://api.topo.sh/v1/elevation?lat=40.689&lon=-74.044" \
  -H "X-API-Key: YOUR_API_KEY"

# Response
{
  "latitude": 40.689,
  "longitude": -74.044,
  "elevation": 10.5,
  "units": "meters",
  "source": "usgs_3dep",
  "resolution": "10m"
}

Authentication

Include your API key in the X-API-Key header with every request:

X-API-Key: YOUR_API_KEY

Endpoints

GET /v1/elevation

Get elevation for a single point.

Parameters

Name	Type	Description
lat required	float	Latitude (-90 to 90)
lon required	float	Longitude (-180 to 180)
units optional	string	Response units: "meters" (default) or "feet"

Example

GET /v1/elevation?lat=39.7392&lon=-104.9903&units=feet

GET /v1/elevation/path

Get elevation profile along a path.

Parameters

Name	Type	Description
coordinates required	string	Comma-separated lat,lon pairs
sample_distance optional	int	Sample points every N meters (10-1000)
units optional	string	"meters" or "feet"

Example

GET /v1/elevation/path?coordinates=39.7,-104.9,39.75,-104.95,39.8,-105.0

GET /v1/terrain-analysis

Get slope and aspect for a point.

Parameters

Name	Type	Description
lat required	float	Latitude
lon required	float	Longitude

Response

{
  "slope": 15.2,      // degrees
  "aspect": 180.5,    // degrees from north
  "units": "degrees"
}

GET /v1/point

Get comprehensive terrain data for a point.

Parameters

Name	Type	Description
lat required	float	Latitude
lon required	float	Longitude

Response

{
  "latitude": 40.689,
  "longitude": -74.044,
  "elevation": 10.5,
  "slope": 2.1,
  "aspect": 45.2,
  "curvature": 0.003,
  "units": {
    "elevation": "meters",
    "slope": "degrees",
    "aspect": "degrees"
  }
}

POST /v1/points/batch

Process multiple points in a single request.

Request Body

{
  "points": [
    {"lat": 40.689, "lon": -74.044},
    {"lat": 40.690, "lon": -74.045},
    {"lat": 40.691, "lon": -74.046}
  ],
  "include": ["elevation", "slope", "aspect"],
  "units": "meters"
}

Response

{
  "results": [
    {
      "latitude": 40.689,
      "longitude": -74.044,
      "elevation": 10.5,
      "slope": 2.1,
      "aspect": 45.2
    },
    // ... more points
  ]
}

Error Handling

The API uses standard HTTP status codes:

200 OK          - Success
400 Bad Request - Invalid parameters
401 Unauthorized - Invalid or missing API key
404 Not Found   - No data available for location
429 Too Many Requests - Rate limit exceeded
500 Server Error - Something went wrong

Error responses include a message:

{
  "error": "Invalid coordinates",
  "detail": "Latitude must be between -90 and 90"
}

Rate Limits

Beta tier: 100,000 requests/month, 100 requests/second

Rate limit info is included in response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Data Sources

Elevation data from USGS 3DEP (10m resolution in US), SRTM (30m global).