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.

The coverage area of the Elevation Service is limited to latitudes between 56°S and 60°N.

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
  • Parameters
    • Elevation Profile URL Parameters
      • Elevation Profile Response
    • Elevation Chart URL Parameters

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 route session which contains the lat/lng collection along the given path. We use that session id 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 from the route session 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?
sessionId A unique identifier used to refer to a route session. The Route Session Id can be used in place of a latLngCollection to get the lat/lng positions for an elevation profile request. The session will expire after 30 minutes. Please also see the Advanced Routing and Options Parameters No - May be used in place of a latLngCollection
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. A route session Id may be used in place of this parameter. 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 		No
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 No
roadGradeStrategy See the Advanced Routing and Options Parameters No

Elevation profile response

Sample JSON Response Sample XML Response 
{elevationProfile: [
   { .72873
     distance: 0     
   },
   {
      .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>...</imageUrl> 
          <imageAltText>...</imageAltText> 
          <text>...</text> 
       </copyright>
    </info>    
</elevationResponse>

Additional Response Info:

Note: If there are cases where no height data exists, the resulting height value is -32768. In the cases of no height data, a statuscode of 601 ("No Data Error: No Valid Height Data Exists.") or 602 ("Partial Success: Some elevations were found but others were not within the SRTM coverage.") will be returned. This will occur if outside the coverage area as specified above.


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?
sessionId A unique identifier used to refer to a route session. The Route Session Id can be used in place of a latLngCollection to get the lat/lng positions for an elevation chart request. The session will expire after 30 minutes. Please also see the Advanced Routing and Options Parameters No - May be used in place of a latLngCollection
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

OpenStreetMap data is licensed under the Open Data Commons Open Database License (ODbL).

spacer   © MapQuest, Inc. All rights reserved.    Privacy Policy | Terms of Use
Related searches:
elevation request format service supplied
gipoco.com is neither affiliated with the authors of this page nor responsible for its contents. This is a safe-cache copy of the original web site.