Google Maps API Web Services

The Google Elevation API

  1. Introduction
  2. What Can You Do with the Elevation API?
  3. Audience
  4. API Key
  5. Usage Limits
  6. Elevation Requests
    1. Output Formats
    2. Parameter Usage
    3. Specifying Locations
    4. Specifying Paths
  7. Elevation Responses
    1. Positional Elevation Examples
    2. Sampled Path Examples
    3. CreatingElevationCharts

Looking to use this service in a JavaScript application? Check out the ElevationService class of the Google Maps API v3.

Introduction

Welcome to the developer documentation for the Google Elevation API! The Google Elevation API provides you 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.

What Can You Do With the Elevation API?

The Elevation API provides elevation data 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 will interpolate and return an averaged value using the four nearest locations.

With the Elevation API, you can develop hiking and biking applications, mobile positioning applications, or low resolution surveying applications.

You access the Elevation API through an HTTP interface. Users of the Google JavaScript API V3 may also access this API directly by using the ElevationService() object. (See Elevation Service for more information.)

Audience

This document is intended for website and mobile developers who want to use elevation data within maps provided by one of the Google Maps APIs. It provides an introduction to using the API and reference material on the available parameters.

API Key

Note: Maps for Business users must include client and signature parameters with their requests instead of a key.

All Elevation API applications should use an API key. Including a key in your request:

  • Allows you to monitor your application's API usage in the APIs Console.
  • Enables per-key instead of per-IP-address quota limits.
  • Ensures that Google can contact you about your application if necessary.

The Elevation API uses an API key to identify your application. API keys are managed through the Google APIs console. To create your key:

  1. Visit the APIs console at https://code.google.com/apis/console and log in with your Google Account.
  2. Click the Services link from the left-hand menu in the APIs Console, then activate the Elevation API service.
  3. Once the service has been activated, your API key is available from the API Access page, in the Simple API Access section. Elevation API applications use the Key for server apps.

To specify a key in your request, include it as the value of a key parameter.

Note: By default, a key can be used from any server. We strongly recommend that you restrict the use of your key by IP address to servers that you administer. You can specify which IP addresses are allowed to use your API key by clicking the Edit allowed referers... link in the API console.

Note: HTTPS is enforced for requests that include an API key.

Usage Limits

The Elevation API has the following limits in place:

Users of the free API:
  • 2,500 requests per 24 hour period.
  • 512 locations per request.
  • 25,000 total locations per 24 hour period.
Maps for Business customers:
  • 100,000 requests per 24 hour period.
  • 1,000,000 total locations per 24 hour period.

These limits are enforced to prevent abuse and/or repurposing of the Elevation API, and may be changed in the future without notice. Additionally, we enforce a request rate limit to prevent abuse of the service. If you exceed the 24-hour limit or otherwise abuse the service, the Elevation API may stop working for you temporarily. If you continue to exceed this limit, your access to the Elevation API may be blocked.

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.

Elevation API URLs are restricted to approximately 2000 characters, after URL Encoding. As some Elevation API URLs may involve many points, be aware of this limit when constructing your URLs.

The Elevation API may only be used in conjunction with displaying results on a Google map; using elevation data without displaying a map for which elevation data was requested is prohibited. For complete details on allowed usage, consult the Maps API Terms of Service License Restrictions.

Elevation Requests

The Elevation 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.

A Google Elevation API URL must be of the following form:

http://maps.googleapis.com/maps/api/elevation/outputFormat?parameters

Tip: You can also access the Google Elevation API using SSL, by substituting https for http in the request URL. HTTPS is recommended for applications that include sensitive user data, such as a user's location, in requests.

Output Formats

Outputs formats are specified using the trailing service flag in the request URL. The Elevation API currently supports the following output formats:

  • /json returns results in JavaScript Object Notation (JSON).
  • /xml returns results in XML, wrapped within a <ElevationResponse> node.

Parameter Usage

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

  • sensor (required) specifies whether the application requesting elevation data is using a sensor (such as a GPS device) to determine the user's location. Accepts true or false.
  • key — (optional) Your application's API key. This key identifies your application for purposes of quota management. Learn how to get a key from the APIs Console.

Maps API for Business users must include valid client and signature parameters with their Elevation requests. Please refer to the Maps API for Business Web Services chapter for more information.

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 the samples 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. 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 any number of multiple coordinates within an array or encoded polyline, as long as you don't exceed the service quotas, 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, as long as you don't exceed the service quotas, 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_QUERY_LIMIT indicating the requestor has exceeded quota.
  • REQUEST_DENIED indicating the API did not complete the request, likely because the requestor failed to include a valid sensor parameter.
  • 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 (containing lat and lng elements) 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.
  • 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 (larger resolution 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:

http://maps.googleapis.com/maps/api/elevation/json?locations=39.7391536,-104.9847034&sensor=true_or_false&key=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) in the JSON format:

http://maps.googleapis.com/maps/api/elevation/json?locations=39.7391536,-104.9847034|36.455556,-116.866667&sensor=true_or_false&key=API_KEY
{
   "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"
}

The following request is identical to the one above, except that the request indicates that an output format of XML is desired, through use of the /xml service flag:

http://maps.googleapis.com/maps/api/elevation/xml?locations=39.7391536,-104.9847034|36.455556,-116.866667&sensor=true_or_false&key=API_KEY
<?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>

Path Elevation Examples

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.

http://maps.googleapis.com/maps/api/elevation/json?path=36.578581,-118.291994|36.23998,-116.83171&samples=3&sensor=true_or_false&key=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 ( http://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 = 'http://maps.googleapis.com/maps/api/elevation/json'
CHART_BASE_URL = 'http://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",sensor="false", **elvtn_args):
      elvtn_args.update({
        'path': path,
        'samples': samples,
        'sensor': sensor
      })

      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 gmaps-samples.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.