Elevation API¶
Free
Starter
Standard
Professional
The Stadia Maps elevation API allows you to get the elevation of any point on earth. You can query either a single point or get an elevation profile along a shape (such as a route recorded via GPS). The elevation API pairs well with our routing APIs, enabling you to visualize the elevation profile of your next bike or run.
Endpoint: https://api.stadiamaps.com/elevation/v1
Example Code¶
Tip
Get started quickly with code samples using our official SDKs or cURL. Official SDKs include documentation of all request and response models, either as separate pages, or through docstrings and autocomplete in most IDEs. If you are building for another language or want to try out requests in a browser, refer to our interactive API reference.
import { GeospatialApi, Configuration } from '@stadiamaps/api';
// If you are writing for a backend application or can't use domain-based auth,
// then you'll need to add your API key like so:
//
// const config = new Configuration({ apiKey: "YOUR-API-KEY" });
// You can also use our EU endpoint to keep traffic within the EU using the basePath option:
// const config = new Configuration({ basePath: "https://api-eu.stadiamaps.com" });
// const api = new GeospatialApi(config);
const api = new GeospatialApi();
// Example of a point request. You can also pass multiple geographic coordinates in a list or a Google
// encoded Polyline via the encodedPolyline parameter.
const req = {id: "Seoul", shape: [{lat: 37.56, lon: 126.99}]};
const res = await api.elevation({ heightRequest: req });
import os
import stadiamaps
from stadiamaps.rest import ApiException
# You can also use our EU endpoint to keep traffic within the EU like so:
# configuration = stadiamaps.Configuration(host="https://api-eu.stadiamaps.com")
configuration = stadiamaps.Configuration()
# Configure API key authentication (ex: via environment variable).
configuration.api_key['ApiKeyAuth'] = os.environ["API_KEY"]
with stadiamaps.ApiClient(configuration) as api_client:
# Create an instance of the API class
api_instance = stadiamaps.GeospatialApi(api_client)
try:
# Example of a point request. You can also pass multiple geographic coordinates in a list or a Google
# encoded Polyline via the encoded_polyline parameter.
req = stadiamaps.HeightRequest(id="Seoul", shape=[stadiamaps.Coordinate(lat=37.56, lon=126.99)])
res = api_instance.elevation(req)
except ApiException as e:
# Add your error handling here
print("Exception when calling the Stadia Maps API: %s\n" % e)
// Imports (at the top of your source file; we've used some wildcard imports for simplicity)
import com.stadiamaps.api.apis.*
import com.stadiamaps.api.auth.ApiKeyAuth
import com.stadiamaps.api.infrastructure.*
import com.stadiamaps.api.models.*
// Set your API key (from an environment variable in this case)
val apiKey = System.getenv("STADIA_API_KEY") ?: throw RuntimeException("API Key not set")
// Defining the host is optional and defaults to https://api.stadiamaps.com
// You can also use our EU endpoint to keep traffic within the EU like so:
// val client = ApiClient(baseUrl = "https://api-eu.stadiamaps.com")
val client = ApiClient()
client.addAuthorization("ApiKeyAuth", ApiKeyAuth("query", "api_key", apiKey))
// Configure a service for the group of APIs we want to talk to
val service = client.createService(GeospatialApi::class.java)
// Set up the request. Note: if you're using Kotlin with coroutines, you can also await
// rather than executing synchronously when using suspend functions.
val req = HeightRequest(id = "Seoul", shape = listOf(Coordinate(37.56, 126.99)))
val res = service.elevation(req).execute()
if (res.isSuccessful) {
println("Found result: ${res.body()}")
} else {
println("Request failed with error code ${res.code()}")
}
import StadiaMaps
// This setup code can go anywhere before you actually make an API call (typically in your app init)
func setupStadiaMapsAPI() {
// Set your API key
StadiaMapsAPI.customHeaders = ["Authorization": "Stadia-Auth YOUR-API-KEY"]
// Optionally use our EU endpoint to keep traffic within the EU
// StadiaMapsAPI.basePath = "https://api-eu.stadiamaps.com"
}
// This function demonstrates how to call the Stadia Maps API.
// If you have not yet adopted async/await in your Swift codebase, you can use the Task API
// to call async functions in a non-async context: https://developer.apple.com/documentation/swift/task.
func myFunction() async throws {
let req = HeightRequest(id: "Seoul", shape: [Coordinate(lat: 37.56, lon: 126.99)])
let res = try await GeospatialAPI.elevation(heightRequest: req)
// Do something with the response...
print(res)
}
curl -X POST -H "Content-Type: application/json" -d '{
"id": "Seoul",
"shape": [
{
"lat": 37.56,
"lon": 126.99
}
]
}' "https://api.stadiamaps.com/elevation/v1?api_key=YOUR-API-KEY"
Common Request Body Parameters¶
This endpoint accepts request parameters via a JSON encoded POST body. Either shape
or encoded_polyline
is required.
Parameter | Type | Required | Description | Default | Example |
---|---|---|---|---|---|
id |
string | no | An identifier to disambiguate requests (echoed by the server). | none | Seoul |
shape |
array of objects | no* | An array of geographic coordinates. | none | [{lat: 37.56, lon: 126.99}] |
encoded_polyline |
string | no* | An encoded polyline. | none | Manhattan |
shape_format |
string | no | Specifies whether the polyline is encoded with 5 (polyline5 ) or 6 (polyline6 ) digits of precision. |
polyline6 |
polyline6 |
Example Response¶
{
"id": "Seoul",
"shape": [
{
"lat": 37.56,
"lon": 126.99
}
],
"height": [
52
]
}