Documentation / Point elevation API

Point elevation API

Retrieve terrain elevation at a coordinate from Mapzen Terrain Tiles on AWS Open Data.

On this page

Sample terrain height at a coordinate

Send latitude and longitude with the same Bearer key used for other Mapsource data endpoints. The response includes the coordinate, elevationMeters, belowSeaLevel, sampledMeters, source, resolutionZoom, bathymetryTile, and attribution.

elevationMeters is clamped to a minimum of zero. sampledMeters preserves the raw model elevation, including negative values. belowSeaLevel identifies negative samples, including below-sea-level land. bathymetryTile links to the source raster for direct access to model depths.

curl --fail-with-body \
  'https://api.mapsource.io/elevation?lat=45.3735&lon=-121.6959' \
  -H "Authorization: Bearer $MAPSOURCE_API_KEY"

# A point at sea reads 0, and names the raster holding its depth
curl --fail-with-body \
  'https://api.mapsource.io/elevation?lat=0&lon=-140' \
  -H "Authorization: Bearer $MAPSOURCE_API_KEY"

Coordinates and response fields

Send exactly one coordinate per request: lat from −85.05112878 to 85.05112878 and lon from −180 to 180. Both values are required and must be finite decimal numbers. Input outside this range returns BAD_REQUEST.

Field	Description
`latitude`, `longitude`	The sampled coordinate.
`elevationMeters`	Surface elevation in meters, with a minimum value of zero.
`sampledMeters`	Raw model elevation in meters; may be negative.
`belowSeaLevel`	Whether the raw elevation is below zero.
`bathymetryTile`	Source raster reference for direct access to depth data.
`resolutionZoom`	Source sampling zoom, currently 12.
`source`	Source dataset identifier.
`attribution`	Source credits to retain with derived output.

The service samples the source pixel containing the requested coordinate. Reporting decimal meters does not imply that level of measurement accuracy. Ground resolution and source quality vary by latitude and contributing dataset.

Sampling from an application

const coordinate = { lat: 45.3735, lon: -121.6959 };
const url = new URL("https://api.mapsource.io/elevation");
url.search = new URLSearchParams({
  lat: String(coordinate.lat), lon: String(coordinate.lon)
});
const response = await fetch(url, {
  headers: { Authorization: "Bearer " + process.env.MAPSOURCE_API_KEY },
  signal: AbortSignal.timeout(25_000)
});
if (!response.ok) throw new Error("Elevation request failed: " + response.status);
const sample = await response.json();
if (!Number.isFinite(sample.elevationMeters)) throw new Error("No usable height");
console.log(sample.elevationMeters);

For a route elevation profile, set elevation: true on a routing request. For independent point samples, stay within the plan’s rate and concurrency limits. Point elevation does not return building height.

If source tiles are unavailable, handle an upstream error rather than substituting zero elevation. This source is not suitable for surveying, construction, or safety-critical navigation.

Access and limits

One coordinate per request. Latitude: −85.05112878 to 85.05112878. Longitude: −180 to 180. Source sampling uses zoom 12; ground resolution and vertical accuracy vary by source and location.

Values describe terrain, not building height. This dataset is not survey-grade and is not intended for construction or safety-critical navigation.

See plan limits for request allowances and error handling for quota and retry behavior.

Responses and examples

Successful responses contain numeric surface and raw elevation values with source attribution. Handle no-data responses, invalid coordinates, and upstream errors before using a sample.

Example responses and timing measurements · Current service status

Attribution

Elevation comes from Mapzen Terrain Tiles on AWS Open Data and its underlying source datasets. Preserve the source attribution returned with each response.

Source and reference · Mapsource attribution guide

Questions about this guide? Contact support.