Elevation API
The Elevation API returns the height above sea level for one or more coordinates. You can query a single point, a list of points, or request a full elevation profile for a route.
If you want to enhance a route with elevation data use the Route Enhancing API.
Base URL
https://elevation.maptoolkit.netAuthentication
Add your API key as ?api_key=YOUR_API_KEY to every request. See Authentication for details.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
loc | lat,lng | Yes (or points) | A single coordinate. Repeat this parameter for multiple locations. |
points | JSON array | Yes (or loc) | A list of coordinates: [[lat, lng], ...] |
simplify | 0 or 1 | No | Returns a simplified version of the route, useful for static map generation. Default: 0. |
callback | string | No | Wraps the response in a JSONP callback function. |
Response
Example - two locations using loc:
GET https://elevation.maptoolkit.net?loc=50,10&loc=46,16&api_key=YOUR_API_KEYExample - two locations using points:
GET https://elevation.maptoolkit.net?points=[[50,10],[46,16]]&api_key=YOUR_API_KEY[289, 128]The response is an array of elevation values in meters, in the same order as the input coordinates.
Request size
points travels in the query string, so the number of coordinates one request can carry is
limited by URL length rather than by a coordinate count. Roughly 5,000 characters of
points, about 250 coordinates at six decimal places, is the practical ceiling.
Above it the service answers 431 Request Header Fields Too Large, and further above that
403. Neither response mentions length, so a request that works for a short route starts
failing on a long one with an error that points somewhere else.
Split longer inputs into batches and concatenate the responses. Because the response order matches the input order, batches reassemble by simple concatenation:
const BATCH_SIZE = 150;
async function elevations(points) {
const out = [];
for (let i = 0; i < points.length; i += BATCH_SIZE) {
const url = new URL('https://elevation.maptoolkit.net');
url.searchParams.set('points', JSON.stringify(points.slice(i, i + BATCH_SIZE)));
url.searchParams.set('api_key', API_KEY);
const response = await fetch(url);
if (!response.ok) throw new Error(`Elevation API returned ${response.status}`);
out.push(...(await response.json()));
}
return out;
}Do not use POST to send a larger payload. The endpoint accepts a JSON body and answers
200 with an array of the correct length filled with zeros. Nothing in the response
indicates a problem, so a route that climbs 1,500 m reports 0 m. This is a GET API.
For elevation along a whole track in one call, use the Route Enhancement API instead, which takes the geometry in a request body.
Examples
Working examples for this API, each with copyable source:
Errors
Errors return the HTTP status code with a plain-text message in the body.
| Status | Meaning |
|---|---|
403 | The API key is missing (Access denied!) or not recognized (Api-key not found!). See First Steps. |
400 | The request is malformed. Check that every coordinate parses and is inside the covered area. |
500 | Internal server error. |
Rate limits
Limits are monthly request quotas tied to your plan rather than a per-second rate: the
service returns no RateLimit-* or Retry-After headers. Current allowances are on the
pricing page.
The free Basic plan has a hard limit, so requests are refused once it is reached. On Pro and Ultra, requests past the allowance are billed rather than refused. Enterprise plans use a flexible limit.
Calls to this API count toward your plan’s API request allowance, which is the smaller of the two allowances.
Pricing
Self-service plans (Basic, Pro, and Ultra) are billed through RapidAPI; see RapidAPI for how to subscribe and authenticate. Plan limits and prices are listed on the Maptoolkit pricing page. Enterprise customers call the native hosts directly with a Maptoolkit API key.