This service is also available as part of the client-side Maps JavaScript API, or for server-side use with the Java Client, Python Client, Go Client and Node.js Client for Google Maps Services.
Introduction
The Elevation API provides a simple interface to query locations on the earth for elevation data. Additionally, you may request sampled elevation data along paths, allowing you to calculate elevation changes along routes. With the Elevation API, you can develop hiking and biking applications, positioning applications, or low resolution surveying applications.
Elevation data is available for all locations on the surface of the earth, including depth locations on the ocean floor (which return negative values). In those cases where Google does not possess exact elevation measurements at the precise location you request, the service interpolates and returns an averaged value using the four nearest locations. Elevation values are expressed relative to local mean sea level (LMSL).
You access the Elevation API through an HTTP interface. Users of the
Maps JavaScript API may also access this API directly by using the
ElevationService()
object. (See
Elevation Service for more information.)
Before you begin
This document is intended for website and mobile developers who want to use elevation data within maps provided by one of the Google Maps Platform APIs. It provides an introduction to using the API and reference material on the available parameters.
Before you start developing with the Elevation API, review the authentication requirements (you need an API key) and the API usage and billing information (you need to enable billing on your project).
Elevation Requests
Elevation API requests are constructed as a URL string. The API returns elevation data for locations on the earth. You specify location data in one of two ways:
- As a set of one or more
locations
. - As a series of connected points along a
path
.
Either of these approachs uses latitude/longitude coordinates to identify the locations or path vertices. This document describes the required format of Elevation API URLs and the available parameters.
The Elevation API returns data for single point queries of the highest accuracy possible. Batch queries involving multiple locations may return data with less accuracy, especially if the locations are spread apart, as some smoothing of data occurs.
A Elevation API request takes the following form:
https://maps.googleapis.com/maps/api/elevation/outputFormat?parameters
where outputFormat
may be either of the following values:
json
(recommended), indicates output in JavaScript Object Notation (JSON); orxml
, indicates output in XML, wrapped within a<ElevationResponse>
node.
Note: URLs must be properly encoded to be valid and are limited to 8192 characters for all web services. Be aware of this limit when constructing your URLs. Note that different browsers, proxies, and servers may have different URL character limits as well.
HTTPS or HTTP
Security is important and HTTPS is recommended whenever possible, especially for applications that include sensitive user data, such as a user's location, in requests. Using HTTPS encryption makes your application more secure, and more resistant to snooping or tampering.
If HTTPS is not possible, to access the Elevation API over HTTP, use:
http://maps.googleapis.com/maps/api/elevation/outputFormat?parameters
Request Parameters
Requests to the Elevation API utilize different parameters based on whether the request is for discrete locations or for an ordered path. For discrete locations, requests for elevation return data on the specific locations passed in the request; for paths, elevation requests are instead sampled along the given path.
As is standard in all URLs, parameters are separated
using the ampersand (&
) character. The list of parameters
and their possible values are denoted below.
All Requests
key
— (required) Your application's API key. This key identifies your application for purposes of quota management. Learn how to get a key.Note: Google Maps Platform Premium Plan customers may use either an API key, or a valid client ID and digital signature, in your Elevation requests. Get more information on authentication parameters for Premium Plan customers.
Positional Requests
locations
(required) defines the location(s) on the earth from which to return elevation data. This parameter takes either a single location as a comma-separated {latitude,longitude} pair (e.g. "40.714728,-73.998672") or multiple latitude/longitude pairs passed as an array or as an encoded polyline. For more information, see Specifying Locations below.
Sampled Path Requests
path
(required) defines a path on the earth for which to return elevation data. This parameter defines a set of two or more ordered {latitude,longitude} pairs defining a path along the surface of the earth. This parameter must be used in conjunction with thesamples
parameter described below. For more information, see Specifying Paths below.samples
(required) specifies the number of sample points along a path for which to return elevation data. Thesamples
parameter divides the givenpath
into an ordered set of equidistant points along the path.
Specifying Locations
Positional requests are indicated through use of the
locations
parameter, indicating elevation requests
for the specific locations passed as
latitude/longitude values.
The locations
parameter may take the following
arguments:
- A single coordinate:
locations=40.714728,-73.998672
- An array of coordinates separated using the pipe ('
|
') character:locations=40.714728,-73.998672|-34.397,150.644
- A set of encoded coordinates using the
Encoded
Polyline Algorithm:
locations=enc:gfo}EtohhU
Latitude and longitude coordinate strings are defined using numerals
within a comma-separated text string. For example, "40.714728,-73.998672"
is a valid locations
value. Latitude and
longitude values must correspond to a valid location
on the face of the earth. Latitudes can take any value between
-90
and 90
while longitude values can take
any value between -180
and 180
. If you specify
an invalid latitude or longitude value, your request will be rejected
as a bad request.
You may pass any number of multiple coordinates within an array or encoded polyline, while still constructing a valid URL. Note that when passing multiple coordinates, the accuracy of any returned data may be of lower resolution than when requesting data for a single coordinate.
Specifying Paths
Sampled path requests are indicated through use of the path
and samples
parameters, indicating a request for elevation data
along a path at specified intervals. As with positional requests using the
locations
parameter, the path
parameter specifies
a set of latitude and longitude values. Unlike a positional request, however,
the path
specifies an ordered set of vertices. Rather than return
elevation data only at the vertices, path requests are sampled along the
length of the path, based on the number of samples
specified (inclusive of the endpoints).
The path
parameter may take either of the following
arguments:
- An array of two or more comma-separated coordinate text strings
separated using the pipe ('
|
') character:path=40.714728,-73.998672|-34.397,150.644
- Encoded coordinates using the
Encoded
Polyline Algorithm:
path=enc:gfo}EtohhUxD@bAxJmGF
Latitude and longitude coordinate strings are defined using numerals
within a comma-separated text string. For example,
"40.714728,-73.998672|-34.397, 150.644" is a valid
path
value. Latitude and longitude values must correspond
to a valid location
on the face of the earth. Latitudes can take any value between
-90
and 90
while longitude values can take
any value between -180
and 180
. If you specify
an invalid latitude or longitude value, your request will be rejected
as a bad request.
You may pass any number of multiple coordinates within an array or encoded polyline, while still constructing a valid URL. Note that when passing multiple coordinates, the accuracy of any returned data may be of lower resolution than when requesting data for a single coordinate.
Elevation Responses
For each valid request, the Elevation service will return an Elevation response in the format indicated within the request URL. Each response will contain the following elements:
An Elevation status
code, which may be one of
the following:
OK
indicating the API request was successful.INVALID_REQUEST
indicating the API request was malformed.OVER_DAILY_LIMIT
indicating any of the following:- The API key is missing or invalid.
- Billing has not been enabled on your account.
- A self-imposed usage cap has been exceeded.
- The provided method of payment is no longer valid (for example, a credit card has expired).
See the Maps FAQ to learn how to fix this.
OVER_QUERY_LIMIT
indicating the requestor has exceeded quota.REQUEST_DENIED
indicating the API did not complete the request.UNKNOWN_ERROR
indicating an unknown error.
When the status code is other than OK
, there may be an additional
error_message
field within the Elevation response object. This field contains more
detailed information about the reasons behind the given status code.
Note: This field is not guaranteed to be always present, and its content is subject to change.
An array of results
containing the following elements:
- A
location
element (containinglat
andlng
elements) of the position for which elevation data is being computed. Note that for path requests, the set oflocation
elements will contain the sampled points along the path. - An
elevation
element indicating the elevation of the location in meters. - A
resolution
value, indicating the maximum distance between data points from which the elevation was interpolated, in meters. This property will be missing if the resolution is not known. Note that elevation data becomes more coarse (largerresolution
values) when multiple points are passed. To obtain the most accurate elevation value for a point, it should be queried independently.
Positional Elevation Examples
The following example requests the elevation for Denver, Colorado, the "Mile High City" in the JSON format:
https://maps.googleapis.com/maps/api/elevation/json?locations=39.7391536,-104.9847034&key=YOUR_API_KEY
{ "results" : [ { "elevation" : 1608.637939453125, "location" : { "lat" : 39.73915360, "lng" : -104.98470340 }, "resolution" : 4.771975994110107 } ], "status" : "OK" }
The following example shows multiple responses (for Denver, CO and for Death Valley, CA).
This request demonstrates using the JSON output
flag:
https://maps.googleapis.com/maps/api/elevation/json?locations=39.7391536,-104.9847034|36.455556,-116.866667&key=YOUR_API_KEY
This request demonstrates using the XML output
flag:
https://maps.googleapis.com/maps/api/elevation/xml?locations=39.7391536,-104.9847034|36.455556,-116.866667&key=YOUR_API_KEY
Click the tabs below to see the sample JSON and XML responses.
{ "results" : [ { "elevation" : 1608.637939453125, "location" : { "lat" : 39.73915360, "lng" : -104.98470340 }, "resolution" : 4.771975994110107 }, { "elevation" : -50.78903579711914, "location" : { "lat" : 36.4555560, "lng" : -116.8666670 }, "resolution" : 19.08790397644043 } ], "status" : "OK" }
<?xml version="1.0" encoding="UTF-8"?> <ElevationResponse> <status>OK</status> <result> <location> <lat>39.7391536</lat> <lng>-104.9847034</lng> </location> <elevation>1608.6379395</elevation> <resolution>4.7719760</resolution> </result> <result> <location> <lat>36.4555560</lat> <lng>-116.8666670</lng> </location> <elevation>-50.7890358</elevation> <resolution>19.0879040</resolution> </result> </ElevationResponse>
The following examples requests elevation data along a straight line
path
from Mt. Whitney, CA to Badwater, CA, the highest and
lowest points in the continental United States. We ask for three
samples
, so that will include the two endpoints and the
halfway point.
https://maps.googleapis.com/maps/api/elevation/json?path=36.578581,-118.291994|36.23998,-116.83171&samples=3&key=YOUR_API_KEY
{ "results" : [ { "elevation" : 4411.941894531250, "location" : { "lat" : 36.5785810, "lng" : -118.2919940 }, "resolution" : 19.08790397644043 }, { "elevation" : 1381.861694335938, "location" : { "lat" : 36.41150289067028, "lng" : -117.5602607523847 }, "resolution" : 19.08790397644043 }, { "elevation" : -84.61699676513672, "location" : { "lat" : 36.239980, "lng" : -116.831710 }, "resolution" : 19.08790397644043 } ], "status" : "OK" }
Creating Elevation Charts
Elevation data must be used in conjunction with a display of
data on a Google Map. The Chart API (
https://code.google.com/apis/chart/
) is well-suited to
creating elevation charts which you can display alongside
your maps.
The following Python example calculates elevation data between Mt. Whitney and Badwater, Death Valley and uses those values to create en elevation chart:
import simplejson import urllib ELEVATION_BASE_URL = 'https://maps.googleapis.com/maps/api/elevation/json' CHART_BASE_URL = 'https://chart.apis.google.com/chart' def getChart(chartData, chartDataScaling="-500,5000", chartType="lc",chartLabel="Elevation in Meters",chartSize="500x160",chartColor="orange", **chart_args): chart_args.update({ 'cht': chartType, 'chs': chartSize, 'chl': chartLabel, 'chco': chartColor, 'chds': chartDataScaling, 'chxt': 'x,y', 'chxr': '1,-500,5000' }) dataString = 't:' + ','.join(str(x) for x in chartData) chart_args['chd'] = dataString.strip(',') chartUrl = CHART_BASE_URL + '?' + urllib.urlencode(chart_args) print chartUrl def getElevation(path="36.578581,-118.291994|36.23998,-116.83171",samples="100", **elvtn_args): elvtn_args.update({ 'path': path, 'samples': samples }) url = ELEVATION_BASE_URL + '?' + urllib.urlencode(elvtn_args) response = simplejson.load(urllib.urlopen(url)) # Create a dictionary for each results[] object elevationArray = [] for resultset in response['results']: elevationArray.append(resultset['elevation']) # Create the chart passing the array of elevation data getChart(chartData=elevationArray) if __name__ == '__main__': # Mt. Whitney startStr = "36.578581,-118.291994" # Death Valley endStr = "36.23998,-116.83171" pathStr = startStr + "|" + endStr getElevation(pathStr)
The following images show how this information might be displayed on a map and/or chart:
Download the ElevationChartCreator.py code from js-v2-samples.
The sensor
Parameter
The Google Maps API previously required that you include the
sensor
parameter to indicate whether your application used a
sensor to determine the user's location. This parameter is no longer
required.