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); or
xml
, indicates output in XML, wrapped within a
<ElevationResponse>
node.
Note
: URLs must be
properly encoded
to be valid and are limited to 16384 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 is required for requests that use an API key.
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
.
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. There is a 512 point limit
for this specific parameter. 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 the
samples
parameter described below. There is a 512 point limit for this
specific parameter. For more information,
see
Specifying Paths
below.
samples
(
required
) specifies the number of sample
points along a path for which to return elevation data. The
samples
parameter divides the given
path
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 up to 512 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.
Exceeding 512 points or coordinates in the 'locations' or 'path' parameters returns an
INVALID_REQUEST
response.
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 up to 512 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. Exceeding 512 points or coordinates
in the 'locations' or 'path' parameters returns an
INVALID_REQUEST
response.
Elevation responses
For each valid request, the Elevation service will return an Elevation
response in the format indicated within the request URL.
ElevationResponse
Field
| Required
| Type
| Description
|
---|
results
| required
|
Array<
ElevationResult
>
|
See
ElevationResult
for more information.
|
status
| required
| ElevationStatus
|
See
ElevationStatus
for more information.
|
error_message
| optional
| string
|
When the service returns a status code other than
OK
,
there may be an additional
error_message
field within
the response object. This field contains more detailed information
about thereasons behind the given status code. This field is not
always returned, and its content is subject to change.
|
ElevationStatus
Status codes returned by service.
OK
indicating the API request was successful.
DATA_NOT_AVAILABLE
indicating that there's no available data
for the input locations.
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).
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.
The response contains a
results
array with the following elements:
ElevationResult
Field
| Required
| Type
| Description
|
---|
elevation
| required
| number
| The elevation of the location in meters.
|
location
| required
| LatLngLiteral
|
A location element of the position for which elevation data is being
computed. Note that for path requests, the set of location elements
will contain the sampled points along the path.
See
LatLngLiteral
for more information.
|
resolution
| optional
| number
|
The 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 (larger resolution values) when multiple points
are passed. To obtain the most accurate elevation value for a point,
it should be queried independently.
|
The
location
object has the following elements:
LatLngLiteral
An object describing a specific location with Latitude and Longitude in
decimal degrees.
Field
| Required
| Type
| Description
|
---|
lat
| required
| number
| Latitude in decimal degrees
|
lng
| required
| number
| Longitude in decimal degrees
|
Positional elevation examples
The following example requests the elevation for Denver,
Colorado, the "Mile High City" in the JSON format:
URL
https://maps.googleapis.com/maps/api/elevation/json
?locations=39.7391536%2C-104.9847034
&key=YOUR_API_KEY
cURL
curl -L -X GET 'https://maps.googleapis.com/maps/api/elevation/json?locations=39.7391536%2C-104.9847034&key=YOUR_API_KEY'
JSON
{
"results":
[
{
"elevation": 1608.637939453125,
"location": { "lat": 39.7391536, "lng": -104.9847034 },
"resolution": 4.771975994110107,
},
],
"status": "OK",
}
XML
<ElevationResponse>
<status>OK</status>
<result>
<location>
<lat>39.7391536</lat>
<lng>-104.9847034</lng>
</location>
<elevation>1608.6379395</elevation>
<resolution>4.7719760</resolution>
</result>
</ElevationResponse>
The following example shows multiple responses (for Denver, CO and for
Death Valley, CA).
This request demonstrates using the JSON
output
flag:
URL
https://maps.googleapis.com/maps/api/elevation/json
?locations=39.7391536%2C-104.9847034%7C36.455556%2C-116.866667
&key=YOUR_API_KEY
cURL
curl -L -X GET 'https://maps.googleapis.com/maps/api/elevation/json?locations=39.7391536%2C-104.9847034%7C36.455556%2C-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
Select the tabs below to see the sample JSON and XML responses.
JSON
{
"results":
[
{
"elevation": 1608.637939453125,
"location": { "lat": 39.7391536, "lng": -104.9847034 },
"resolution": 4.771975994110107,
},
{
"elevation": -52.79492568969727,
"location": { "lat": 36.455556, "lng": -116.866667 },
"resolution": 19.08790397644043,
},
],
"status": "OK",
}
XML
<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>-52.7949257</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.
URL
https://maps.googleapis.com/maps/api/elevation/json
?path=36.578581%2C-118.291994%7C36.23998%2C-116.83171
&samples=3
&key=YOUR_API_KEY
cURL
curl -L -X GET 'https://maps.googleapis.com/maps/api/elevation/json?path=36.578581%2C-118.291994%7C36.23998%2C-116.83171&samples=3&key=YOUR_API_KEY'
JSON
{
"results":
[
{
"elevation": 4411.94189453125,
"location": { "lat": 36.578581, "lng": -118.291994 },
"resolution": 19.08790397644043,
},
{
"elevation": 1372.8359375,
"location": { "lat": 36.41150289067028, "lng": -117.5602607523847 },
"resolution": 9.543951988220215,
},
{
"elevation": -84.51690673828125,
"location": { "lat": 36.23998, "lng": -116.83171 },
"resolution": 9.543951988220215,
},
],
"status": "OK",
}
XML
<ElevationResponse>
<status>OK</status>
<result>
<location>
<lat>36.5785810</lat>
<lng>-118.2919940</lng>
</location>
<elevation>4411.9418945</elevation>
<resolution>19.0879040</resolution>
</result>
<result>
<location>
<lat>36.4115029</lat>
<lng>-117.5602608</lng>
</location>
<elevation>1372.8359375</elevation>
<resolution>9.5439520</resolution>
</result>
<result>
<location>
<lat>36.2399800</lat>
<lng>-116.8317100</lng>
</location>
<elevation>-84.5169067</elevation>
<resolution>9.5439520</resolution>
</result>
</ElevationResponse>