Elevation API

The Elevation API is designed to retrieve elevation data for any location on Earth. It provides elevation values for a set of coordinates, enabling applications to understand terrain characteristics.

This API provides elevation data that can be used for:

• Terrain analysis - understand the topography of an area
• Route planning - calculate elevation changes along a path
• Outdoor activities - plan hiking, cycling, or running routes with elevation profiles
• Environmental studies - analyze elevation patterns for research

To make it easy for you to get started with the Elevation API, we have created an API Playground where you can add points on a map and visualize their elevation data.

• Authentication and API key
• API reference
• Code samples
• Pricing

Authentication and API key

To use the Elevation API, you'll need an API key. You can register and get an Elevation API Key for free without a credit card.

We offer a free plan, so there's no need to stress about cost. Start for free and upgrade to a paid plan when the needs of your project increase. For more information on our plans, visit the Pricing page.

How to get the Geoapify API key

1. Register on the Geoapify MyProjects page.
2. Create a new project.
3. Go to the API Keys section. One API key is generated automatically. You can generate multiple API keys per project if required.
4. Optionally, you can protect the API key by listing allowed IP addresses, HTTP referrers, origins, and CORS.
5. Choose "Elevation API" and an API key to generate a URL and programming code.
6. Press the "Try" button to execute the API call and get the result object example.

API reference

The Elevation API operates through HTTP POST requests that receives input data within the request body.

Request URL

You can access the Geoapify Elevation API via a POST request to the endpoint located at https://api.geoapify.com/v1/geodata/elevation.

HTTP POST https://api.geoapify.com/v1/geodata/elevation
HEADERS 'Content-Type: application/json'

Request URL parameters

To request the Geoapify Elevation API, you only need to provide one URL parameter - your API key.

Request body parameters

The request body is a JSON object with the following parameters:

Request body example

{
  "format": "json",
  "units": "metric",
  "includeDistance": true,
  "locations": [
    {
      "latlon": [52.52, 13.405]
    },
    {
      "lat": 48.137,
      "lon": 11.575
    },
    [-122.4194, 37.7749]
  ]
}

Here is a request example using cURL:

curl -X POST "https://api.geoapify.com/v1/geodata/elevation?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "json",
    "units": "metric",
    "includeDistance": true,
    "locations": [
      {"latlon": [52.52, 13.405]},
      {"lat": 48.137, "lon": 11.575},
      [-122.4194, 37.7749]
    ]
  }'

Response Object

Depending on the format parameter, the API returns a JSON object or GeoJSON FeatureCollection.

JSON response (default):

Here is a JSON response example:

{
  "results": [
    {
      "location": { "lon": 52.52, "lat": 13.405 },
      "elevation": -2189,
      "units": "m",
      "distance": 0,
      "distance_units": "m"
    },
    {
      "location": { "lon": 11.575, "lat": 48.137 },
      "elevation": 523,
      "units": "m",
      "distance": 5395784,
      "distance_units": "m"
    },
    {
      "location": { "lon": -122.4194, "lat": 37.7749 },
      "elevation": 17,
      "units": "m",
      "distance": 14840969,
      "distance_units": "m"
    }
  ]
}

Response HTTP status codes

Limits

• Maximum 1000 locations per request

Code samples

The Elevation API returns data in JSON or GeoJSON format, which can be easily visualized using most map client libraries. The examples below demonstrate how to add elevation data to a map:

Visualize elevation with Leaflet

If you want to display elevation data on an interactive map, one of the most popular and versatile client libraries to use is Leaflet. Here is how to visualize elevation points on a map:

// After fetching elevation data
data.results.forEach(result => {
  L.circleMarker([result.location.lat, result.location.lon], {
    radius: 10,
    fillColor: getColorForElevation(result.elevation),
    color: '#fff',
    weight: 2,
    fillOpacity: 0.8
  }).bindPopup(`Elevation: ${result.elevation}${result.units}`).addTo(map);
});

function getColorForElevation(elevation) {
  if (elevation < 100) return '#2e86ab';
  if (elevation < 500) return '#28b463';
  if (elevation < 1000) return '#f9e79f';
  if (elevation < 2000) return '#f5b041';
  return '#e74c3c';
}

This code creates circle markers at each elevation point location. The getColorForElevation function returns a color based on the elevation value, creating a visual scale from blue (low) to red (high).

Visualize elevation with MapLibre GL / Mapbox GL library

If you're looking to create interactive maps with elevation data, another popular option is to use MapLibre GL (a community-driven fork of Mapbox GL) library. This code sample demonstrates how to add elevation points to a MapLibre GL map:

// Add elevation data as a source (using GeoJSON format response)
map.addSource('elevation-points', {
  type: 'geojson',
  data: elevationGeoJSON
});

// Add a circle layer with elevation-based colors
map.addLayer({
  id: 'elevation-circles',
  type: 'circle',
  source: 'elevation-points',
  paint: {
    'circle-radius': 10,
    'circle-color': [
      'interpolate', ['linear'],
      ['get', 'elevation'],
      0, '#2e86ab',
      500, '#28b463',
      1000, '#f9e79f',
      2000, '#f5b041',
      4000, '#e74c3c'
    ],
    'circle-stroke-width': 2,
    'circle-stroke-color': '#ffffff'
  }
});

First, we create a new source called 'elevation-points' of type "geojson". The data parameter contains the GeoJSON object returned by the Geoapify Elevation API.

Then, a circle layer is added to the map. The circle-color paint property uses an interpolate expression to color points based on their elevation value, creating a smooth gradient from blue (low elevation) to red (high elevation).

Visualize elevation with OpenLayers library

OpenLayers is one more powerful open-source JavaScript library used for creating web-based mapping applications. Here is how to visualize elevation data using the OpenLayers library:

var vectorSource = new ol.source.Vector({
  features: (new ol.format.GeoJSON({
    featureProjection: "EPSG:3857"
  })).readFeatures(elevationGeoJSON)
});

var style = new ol.style.Style({
  image: new ol.style.Circle({
    radius: 10,
    fill: new ol.style.Fill({ color: 'rgba(46, 134, 171, 0.8)' }),
    stroke: new ol.style.Stroke({ color: '#fff', width: 2 })
  })
});

var vectorLayer = new ol.layer.Vector({
  source: vectorSource,
  style: style
});

map.addLayer(vectorLayer);

The elevation data is converted to a vector source using the GeoJSON format, which is then used to create a vector layer.

The style for the vector layer is defined using the ol.style.Style object with a circle image, which lets you set the fill and stroke properties for the elevation points.

Finally, the vector layer is added to the map using the addLayer method.

Pricing

We use credits to calculate the cost of each Geoapify request, which simplifies our pricing and standardizes API calls.

The following rules determine the cost of Elevation API requests:

Our free pricing plan includes 3000 credits per day. You can start with the free plan and upgrade later if needed.