Elevation API

Lookup#

import { parseAPI } from '@parseapi/sdk';

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.elevation(27.9881, 86.925);
console.log(result);

{
  "latitude": 27.9881,
  "longitude": 86.925,
  "elevation": 8719,
  "elevation_ft": 28606,
  "resolution": 30
}

A list of points#

Separate latitude,longitude pairs with a pipe. URL-encode the points value. Choose one mode: lat and lon, points, or path with samples. Combining modes returns 400. Latitude is -90 to 90 and longitude is -180 to 180.

GET /elevation?points=39.7392%2C-104.9903%7C39.75%2C-104.98

A list returns { "points": [...] }. Each item has the same five fields as a single-point response. Results stay in input order, including repeated coordinates. An unavailable sample retains its place with null elevation fields.

Local batch limits#

Each local batch is limited to 25 km between any two coordinates and 12 distinct terrain files in total across the fine grid and all possible global fallback files. A fine-grid file and a possible global-fallback file each count toward that total. Batches outside either limit return HTTP 400. Send spread-out locations or routes in shorter local sections. Every accepted section uses one pooled request; coordinates are never trimmed or silently split.

Encoded polyline#

Prefix a Google encoded polyline with enc:. Use precision 5, or five decimal places. The limit is 512 decoded points; the GET value can contain up to 12,000 characters. URL-encode the complete value, including the prefix.

GET /elevation?points=enc%3A_qpqFj%7Cx_SobAk_A

Send the list with POST#

Send a JSON body with Content-Type: application/json. Each pair is [latitude, longitude]. The same local batch limits still apply. A coordinate array avoids URL-length limits and the 12,000-character string limit. A pipe-separated string or enc: polyline can also be sent as the points value, with the same 12,000-character limit as GET. POST returns the same ordered points array and uses one pooled request.

curl https://api.parseapi.com/elevation \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Parse-Version: 2.0.0" \
  -H "Content-Type: application/json" \
  -d '{"points":[[39.7392,-104.9903],[39.75,-104.98]]}'

Sample evenly along a path#

Pass 2-512 ordered vertices in path, as a pipe-separated list or a precision-5 enc: polyline. Set samples to an integer from 2 to 512. The API returns exactly that many records in points, including both endpoints, spaced equally by cumulative distance along the path.

curl --get https://api.parseapi.com/elevation \
  --data-urlencode "path=39.7392,-104.9903|39.75,-104.98" \
  --data-urlencode "samples=65" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Parse-Version: 2.0.0"

Each segment follows the shortest great-circle arc between its vertices. Add waypoints to shape the path; intermediate vertices may fall between the returned samples. Repeated vertices are supported. An all-identical path returns repeated coordinates; a segment between antipodal points returns 400 because its arc is ambiguous. Sampling places coordinates along the path, then reads the nearest elevation grid node at each coordinate. For paths, both the supplied vertices and generated samples must fit the 25 km span; the terrain-file budget applies to the sampled coordinates. This is a span limit, not a limit on cumulative path length. Send longer or more spread-out routes in shorter sections.

For POST, send { "path": [[39.7392, -104.9903], [39.75, -104.98]], "samples": 65 }. Use either points or path with samples, and keep all selectors in the body. String paths have the same 12,000-character limit as point lists; coordinate arrays avoid that limit. samples is required with path and invalid with other modes.

const result = await parse.elevation.path(
  [[39.7392, -104.9903], [39.75, -104.98]],
  65
);
// result.points includes the start and finish.

The JavaScript client selects GET or POST automatically. MCP accepts elevation with a string path and samples. Both return the same ordered points array.

GeoJSON output#

Add format=geojson to the query string on GET or POST. A single coordinate returns a Feature. Point lists and sampled paths return a FeatureCollection of Point samples in result order, including duplicates and unavailable heights. The response uses Content-Type: application/geo+json. Omit the format or use format=json for the ordinary response.

GET /elevation?lat=39.77&lon=-104.9&format=geojson

{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [-104.9, 39.77]
  },
  "properties": {
    "elevation": 1610,
    "elevation_ft": 5282,
    "resolution": 30
  }
}

curl "https://api.parseapi.com/elevation?format=geojson" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Parse-Version: 2.0.0" \
  -H "Content-Type: application/json" \
  -d '{"points":[[39.7392,-104.9903],[39.75,-104.98]]}'

Geometry uses [longitude, latitude]. Input pairs still use [latitude, longitude]. Height stays in properties.elevation and properties.elevation_ft, with properties.resolution for horizontal grid spacing. There is no third coordinate because these sea-level heights use EGM2008. GeoJSON altitude uses the WGS84 ellipsoid. Paths return sample points. The same limits and one-request allowance apply. GeoJSON is available in API 2.0.0. Existing SDK and MCP elevation methods return the ordinary JSON shape. Use HTTP for GeoJSON.

Reading the sample#

Elevation is the nearest grid sample. Fine terrain has about 30 meters between samples, with a global fallback at about 460 meters, including ocean depth. resolution reports horizontal grid spacing in meters, not vertical accuracy. Negative elevation means below sea level; zero is a valid value. A completed lookup can return null when no terrain sample is available. A failure to retrieve elevation data returns HTTP 503 service_unavailable. Try again later. Invalid stored data or an unexpected internal failure returns HTTP 500 server_error.

Height reference#

Land elevation uses a digital surface model: buildings, infrastructure and vegetation can contribute to the height. The global fallback includes ocean depth and the surface of ice sheets.

Both grids use the EGM2008 geoid as their vertical reference. elevation and elevation_ft express height relative to that reference, rather than GPS ellipsoid height. Input latitude and longitude use WGS84. The nominal 30m and 460m spacings describe the grids; east-west ground spacing changes with latitude.

Values are returned in whole meters. Each lookup reads the nearest stored sample.

Questions? Email