Open Elevation Service Developer's Guide

The Open Elevation Service provides elevation profile information such as elevation and distance given a lat/lng pair in JSON or XML formats. Here Distance refers to the accumulated distance along the path specified by the lat/lng collection. Each elevation/distance pair in response is then mapped to the corresponding lat/lng in the request.

Hello, World!

Below is a simple example of an elevation request using lat/lng pairs. It demonstrates how to build an elevation service URL request that can be used to retrieve raw data in JSON or XML format, and to also generate a chart.

The following parameters are being used in this request.

  • callback - This is not a parameter for the service, but for the Javascript to display the results below.
  • shapeFormat - Represents the input and output format for the shape points.
  • inFormat - Specifies the format of the request.
  • latLngCollection - Collection of lat/lng pairs which may be in raw or compressed format.
  • width - Width of the elevation chart measured in pixels.
  • height - Height of the elevation chart measured in pixels.

The request to grab the elevation profile can be found below. Feel free to change the lat/lng requests by modifying the table.

And the request to generate the elevation chart:

The JavaScript code which sends the request and displays the result can be viewed here.

Key Value Pairs Latitude Longitude
Pair No. 1:
Pair No. 2:
Pair No. 3:
 


Contents

Example

Elevation Profile Using the Open Directions Service

We first run a route using the advanced routing options example in our Open Directions Service as shown below and get the lat/lng collection along the given path and then use it to build the elevation URL request with the appropriate elevation URL parameters.

Note: Below example has nothing to do with the Open Elevation Service, it is only being used to get the input lat/lng collection needed for building the elevation URL request (elevation profile/ elevation chart). The JavaScript code which sends the request and displays the result can be viewed here.

Please limit the route to 250 miles / 400 Km only

From:
To:
Route Type:
Unit:
Shape Format:
Road Grade Strategy:
Cycling Road Factor:
Input Format:
 

Parameters

Elevation Profile URL Parameters

The following table describes the request parameters that may be included to make an elevation profile request.

Request Parameter Description Required?
inFormat Specifies the format of the request. If this parameter is not supplied, the input format is assumed to be JSON-formatted text. The JSON-formatted input text must be supplied as either the "json" parameter of an HTTP GET, or as the BODY of an HTTP POST. If this parameter is "xml", the XML-formatted input text must be supplied as either the "xml" parameter of an HTTP GET, or as the BODY of an HTTP POST.

Must be one of the following, if supplied:
  • kvp
  • json
  • xml
Defaults to "json" if not supplied 		No
latLngCollection
String/JsonArray		 Collection of latitude, longitude pairs for a given route which may be in raw or compressed format Yes
shapeFormat
String		 Shape format options.
This value represents the input and output format for the shape points.
Default behaviour of the service is to return all the input shape points in the response
  • raw - shape is represented as float pairs. (default)
  • cmp - shape is represented as a compressed path string with 5 digits of precision.
  • cmp6 - Same as for cmp, but uses 6 digits of precision.

See the Compressed Lat/Lng description page for more detail, including sample source code and an interactive encoder/decoder. 		No
inShapeFormat
String		 Input Shape format options.
Overrides the given "shapeFormat" value for input shape points
  • raw - shape is represented as float pairs.
  • cmp - shape is represented as a compressed path string with 5 digits of precision.
  • cmp6 - Same as for cmp, but uses 6 digits of precision.

See the Compressed Lat/Lng description page for more detail, including sample source code and an interactive encoder/decoder. 		No
outShapeFormat
String		 Output Shape format options.
Overrides the given "shapeFormat" value for output shape points in the response
  • raw - shape is represented as float pairs. (default)
  • cmp - shape is represented as a compressed path string with 5 digits of precision.
  • cmp6 - Same as for cmp, but uses 6 digits of precision.
  • none - Use this option if input shape points are not needed in the response

See the Compressed Lat/Lng description page for more detail, including sample source code and an interactive encoder/decoder. 		No
unit
String		 Specifies the type of units to use when calculating elevation profile. Acceptable values are:
  • m - Metric
  • f - Imperial
Default value is 'm' 		No
useFilter
Boolean		 Use Filter Option. This is a bi-linear filter that is used when sampling height data. This option will use the lat/lng and look at it's 4 closest neighbors and weigh them inversly.
  • false - No bi-linear filter will be used.
  • true - The bi-linear filter will be used.
Default = false
outFormat Specifies the format of the response. Must be one of the following, if supplied:
  • json
  • xml
Defaults to "json" if not supplied 		No
cyclingRoadFactor See the Advanced Routing and Options Parameters
roadGradeStrategy See the Advanced Routing and Options Parameters

Elevation profile response

Sample JSON Response Sample XML Response 
{elevationProfile: [
   { height: 388.72873
     distance: 0     
   },
   {
      height: 397.56055
      distance: 4.37751
   }
   ...
   ],
   shapePoints: [
       40.037956,
      -76.305816,
      .......
      .......
   ],
   info: {
     statuscode: 0,
     copyright: {
     },
     messages: []
  }   
}

<elevationResponse>
   <distanceHeightCollection>
      <distanceHeight>
         <height>388.72873</height>
         <distance>0</distance>
      </distanceHeight> 
      <distanceHeight>
         <height>388.72873</height>
         <distance>0</distance>
      </distanceHeight>
      .......
   </distanceHeightCollection>
   <shapePoints>
     <latLng>
       <lat>40.037956</lat>
       <lng>-76.305816</lng>
     </latLng>
     ........
   </shapePoints>
    <info>
       <statusCode>0</statusCode> 
       <messages />
       <copyright>
          <imageUrl>http://...</imageUrl> 
          <imageAltText>...</imageAltText> 
          <text>...</text> 
       </copyright>
    </info>    
</elevationResponse>

Elevation Chart URL Parameters

The following table describes the request parameters that may be included to make an elevation chart request.

Request Parameter Description Required?
inFormat Specifies the format of the request. If this parameter is not supplied, the input format is assumed to be JSON-formatted text. The JSON-formatted input text must be supplied as either the "json" parameter of an HTTP GET, or as the BODY of an HTTP POST. If this parameter is "xml", the XML-formatted input text must be supplied as either the "xml" parameter of an HTTP GET, or as the BODY of an HTTP POST.

Must be one of the following, if supplied:
  • kvp
  • json
  • xml
Defaults to "json" if not supplied 		No
latLngCollection
String/JsonArray		 Collection of latitude, longitude pairs for a given route which may be in raw or compressed format Yes
shapeFormat
String		 Shape format options.
This value represents the input format for the shape points.
  • raw - shape is represented as float pairs. (default)
  • cmp - shape is represented as a compressed path string with 5 digits of precision.
  • cmp6 - Same as for cmp, but uses 6 digits of precision.

See the Compressed Lat/Lng description page for more detail, including sample source code and an interactive encoder/decoder. 		No
unit
String		 Specifies the type of units to use when calculating elevation profile. Acceptable values are:
  • m - Metric
  • f - Imperial
Default value is 'm' 		No
width Specifies the width of the elevation chart. Must be > 0 and <= 1024, if supplied: Defaults to "500" if not supplied No
height Specifies the height of the elevation chart. Must be > 0 and <= 1024, if supplied: Defaults to "350" if not supplied No



  © MapQuest, Inc. All rights reserved.    Privacy Policy | Terms of Use