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%7C40.71%2C-74.01

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.

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_p~iF~ps%7CU_ulLnnqC_mqNvxq%60%40

Send the list with POST#

Send a JSON body with Content-Type: application/json. Each pair is [latitude, longitude]. The 512-point limit still applies. 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],[40.71,-74.01]]}'

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.74,-104.99|39.74,-105.63" \
  --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 POST, send { "path": [[39.74, -104.99], [39.74, -105.63]], "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.74, -104.99], [39.74, -105.63]],
  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.

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.

Sources and height reference#

Land samples use Copernicus DEM GLO-30. It is a digital surface model: buildings, infrastructure and vegetation can contribute to the height. The global fallback uses the ETOPO 2022 ice-surface model at 15 arc-seconds, including 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.

ParseAPI serves whole-meter samples from prepared grids. Grid preparation uses bilinear resampling where source alignment requires it; lookups read the nearest stored node. Required data attribution.

Questions? Email