## 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: ```console 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](https://en.wikipedia.org/wiki/JSON) (JSON); or - `xml`, indicates output in XML, wrapped within a `` node. **Note** : URLs must be [properly encoded](https://developers.google.com/maps/documentation/elevation/web-service-best-practices.md.txt#BuildingURLs) 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](https://developers.google.com/maps/documentation/elevation/get-api-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 [Specify Locations](https://developers.google.com/maps/documentation/elevation/requests-elevation.md.txt#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 [Specify Paths](https://developers.google.com/maps/documentation/elevation/requests-elevation.md.txt#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. ### Specify 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](https://developers.google.com/maps/documentation/utilities/polylinealgorithm): `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. ### Specify 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](https://developers.google.com/maps/documentation/utilities/polylinealgorithm): `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 - 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](https://developers.google.com/maps/documentation/utilities/polylinealgorithm): `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 returns an Elevation response in the format indicated within the request URL. ### ElevationResponse | Field | Required | Type | Description | |:---|---|---|---| | #### `results` | **required** | Array\<[ElevationResult](https://developers.google.com/maps/documentation/elevation/requests-elevation.md.txt#ElevationResult "ElevationResult")\> | See [ElevationResult](https://developers.google.com/maps/documentation/elevation/requests-elevation.md.txt#ElevationResult "ElevationResult") for more information. | | #### `status` | **required** | [ElevationStatus](https://developers.google.com/maps/documentation/elevation/requests-elevation.md.txt#ElevationStatus "ElevationStatus") | See [ElevationStatus](https://developers.google.com/maps/documentation/elevation/requests-elevation.md.txt#ElevationStatus "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 the reasons 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. > [!NOTE] > **Note:** This field is not guaranteed to be always present, and its content is subject to change. 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](https://developers.google.com/maps/documentation/elevation/requests-elevation.md.txt#LatLngLiteral "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](https://developers.google.com/maps/documentation/elevation/requests-elevation.md.txt#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. | ### 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": ### URL ```html https://maps.googleapis.com/maps/api/elevation/json ?locations=39.7391536%2C-104.9847034 &key=YOUR_API_KEY ``` ### cURL ```bash curl -L -X GET 'https://maps.googleapis.com/maps/api/elevation/json?locations=39.7391536%2C-104.9847034&key=YOUR_API_KEY' ``` ### JSON ```json { "results": [ { "elevation": 1608.637939453125, "location": { "lat": 39.7391536, "lng": -104.9847034 }, "resolution": 4.771975994110107, }, ], "status": "OK", } ``` ### XML ```json OK 39.7391536 -104.9847034 1608.6379395 4.7719760 ``` The following example shows multiple responses (for Denver, CO and for Death Valley, CA). This request demonstrates using the JSON `output` flag: ### URL ```html https://maps.googleapis.com/maps/api/elevation/json ?locations=39.7391536%2C-104.9847034%7C36.455556%2C-116.866667 &key=YOUR_API_KEY ``` ### cURL ```bash 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 ```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 ```json OK 39.7391536 -104.9847034 1608.6379395 4.7719760 36.4555560 -116.8666670 -52.7949257 19.0879040 ``` 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 ```html 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 ```bash 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 ```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 ```json OK 36.5785810 -118.2919940 4411.9418945 19.0879040 36.4115029 -117.5602608 1372.8359375 9.5439520 36.2399800 -116.8317100 -84.5169067 9.5439520 ```