Get Elevations

Article
05/21/2024

Note

Bing Maps Elevations API retirement

Bing Maps Elevations API is deprecated and will be retired. Free (Basic) account customers can continue to use Bing Maps Elevations API until June 30th, 2025. Enterprise account customers can continue to use Bing Maps Elevations API until June 30th, 2028. To avoid service disruptions, all implementations using Bing Maps Elevations API will need to be updated to use an alternative solution, such as Create elevation data & services, by the retirement date that applies to your Bing Maps for Enterprise account type.

Use the following URLs to get elevation values (in meters) for a set of locations, a polyline path, or area on the Earth.

Unit of elevation: Meters.

URL Templates

Note

These templates support both HTTP and HTTPS protocols. To use this API, you must have a Bing Maps Key.

Get elevations for latitude and longitude coordinates

Elevations are returned for each set of coordinates. Both the parameters points and key are required.

http://dev.virtualearth.net/REST/v1/Elevation/List?points={lat1,long1,lat2,long2,latN,longnN}&heights={heights}&key={BingMapsKey}

Get elevations at equally-spaced locations along a polyline path

A polyline path is computed from the coordinates, and then elevation values at both endpoints and equally-spaced locations along the polyline are returned. The samples parameter specifies the number of elevations to return. The parameters points, samples, and key are all required.

http://dev.virtualearth.net/REST/v1/Elevation/Polyline?points={lat1,long1,lat2,long2,latN,longN}&heights={heights}&samples={samples}&key={BingMapsKey}

Get elevations at equally-spaced locations within a bounding box

The rectangular area defined by the four (4) bounding box coordinates (south latitude, west longitude, north latitude, east longitude) is divided into rows and columns. The edges of the bounding box account for two (2) of the rows and two (2) of the columns. Elevations are returned for the vertices of the grid created by the rows and columns. For example, if you had specified rows=4 and columns=4, then 16 elevations are returned. The elevation values are ordered starting with the southwest corner, and then proceed west to east and south to north. This is illustrated in the following diagram. The elevation points are numbered in the order that they are returned.

Bounding box grid showing order of elevations

The parameters bounds, rows, cols, and key are required.

http://dev.virtualearth.net/REST/v1/Elevation/Bounds?bounds={boundingBox}&rows={rows}&cols={cols}&heights={heights}&key={BingMapsKey}

Get the offset of the geoid sea level Earth model from the ellipsoid Earth model

This request returns the offset in meters of the geoid model (heights=sealevel) from the ellipsoid model (heights=ellipsoid) at each location (difference=geoid_sealevel - ellipsoid_sealevel).

The parameters points and key are required.

http://dev.virtualearth.net/REST/v1/Elevation/SeaLevel?points={lat1,long1,lat2,long2,latN,longN}&key={BingMapsKey}

About Elevations and Coordinate Values

Elevation values can be calculated using to two different Earth models – the ellipsoid model and the geoid sea level model. The ellipsoid model uses the World Geodetic System (WGS84) which is an ellipsoidal approximation of the Earth. The geoid sea level model uses the Earth Gravitational Model 2008 (EGM2008 2.5’) and computes a sea level based on the local value of gravity. The ellipsoid model is equivalent to GPS and the geoid sea level model is equivalent what is commonly known as the height above sea level. For a more detailed description of the two models, see the Earth Models and Zoom Level section below. Set the heights parameter to ellipsoid or sealevel to specify the model to use. If the heights parameter is not specified, the sea level model is used
Latitudes and longitudes in the URL are expected to be in WGS84 decimal degrees. (Example: 34.2412,-119.3829)
The maximum number of elevations returned in a request is 1024.

Caution

There is a limitation in that latitude coordinates outside of the range of -85 and 85 are not supported.

If you are submitting a large number of locations, you can use the HTTP POST protocol or the Point Compression Algorithm.

Template Parameters

Note

Parameters and parameter values are not case-sensitive.
Additional parameters, such output and JSON callback parameters, are found in Output Parameters.

Parameters	Alias	Description	Values
`points`	`pts`	Required. `points=lat1,long1,lat2,long2,latn,longn`. A set of coordinates on the Earth to use in elevation calculations. The exact use of these points depends on the type of elevation request.	A set of latitude and longitude values in WGS84 decimal degrees. If you are requesting elevations or elevation offsets for a set of points, the maximum number of points is 1024. If you have a large number of values, you can use the HTTP POST protocol or the Point Compression Algorithm. Example: `points=35.89431,-110.72522,35.89393,-110.72578,35.89374`
`bounds`		Required. Specifies the rectangular area over which to provide elevation values.	A bounding box defined as a set of WGS84 latitudes and longitudes in the following order: south latitude, west longitude, north latitude, east longitude Example: bounds=45.219,-122.234,47.61,-122.07
`rows`, `cols`		Required. Two separate parameters which specify the number of rows and columns, respectively, to use to divide the bounding box area into a grid. The rows and columns that define the bounding box each count as two (2) of the rows and columns. Elevation values are returned for all vertices of the grid.	Integers with a value of two (2) or greater. The number of rows and columns can define a maximum of 1024 locations (rows * cols <= 1024). Examples: `rows=30` `cols=15`
`samples`	`samp`	Required. Specifies the number of equally-spaced elevation values to provide along a polyline path.	A positive integer. The maximum number of samples is 1024. Example: samples=30
`heights`	`hts`	Optional. Specifies which sea level model to use to calculate elevation.	One of the following values. - `sealevel` [default]: Use the geoid Earth model (EGM2008 2.5’). - `ellipsoid`: Use the ellipsoid Earth model (WGS84). For more information about these models, see the Earth Models and Zoom Level section below. Example: `heights=ellipsoid`

Earth Models and Zoom Level

Elevation calculations can vary based on the model of the Earth used and the zoom level.

Earth model: The Elevations API uses two Earth models – an ellipsoid model that is equivalent to a GPS calculation, and geoid sea level model that is what is commonly referred to as altitude above sea level.

The ellipsoid model approximates the Earth as an ellipsoid and uses the World Geodetic System (WGS84). With the ellipsoid model, the elevation is calculated as a height above the ellipsoid.

The geoid sea level model is an approximation of Mean Sea Level that uses an equipotential surface of the Earth’s gravitational field. The geoid model uses the Earth Gravitational Model 2008 (EGM2008 2.5’). Because gravity varies by location, the geoid sea level model is not a smooth shape like the ellipsoid model.

You can specify the Earth model by setting the heights parameter to ellipsoid or sealevel (geoid).

The following diagram shows how the ellipsoid and geoid sea level models can vary and how elevation is measured for both models.

Ellipsoid and Geoid Sea Level elevation values

Zoom level : A zoom level is returned in the response, and reflects the resolution of the data used to compute the elevation. A higher zoom level indicates higher resolution data and more accurate elevation values. At lower zoom levels, the data is further apart and interpolated points are less accurate. For information about the data resolution at different zoom levels, see Understanding Scale and Resolution.

Typically, lower zoom levels are used for areas that have limited data or when you request elevations for points or a polyline that covers a large distance. For example if you request a polyline that covers a large distance across the Earth, such as the distance between Paris and Beijing, the points used to compute elevation are associated with a higher zoom level and are further apart.

Elevation Coverage and Resolution

The following table shows the minimum elevation resolution by area. Actual elevation resolution may be may be higher.

Coverage Area	Resolution (in meters)
Global (including poles)	900 m
Global 56° S - 60° N	90 m
United States	10 m

Response

A set of elevations and the associated zoom level is returned in the responses that request elevation values. For descriptions of the data returned in the response, see Elevation Data. For more information about the common values that are also returned in the response, see Common Response Description.

You can choose JSON (application/json) or XML (application/xml) format for the response. JSON is returned by default. To specify the format, set the output (o) parameter to json or xml. For more information, see Output Parameters.

Examples

Get elevations for a set of latitude and longitude coordinates

The geoid Earth model is used to compute elevations for the coordinates provided.

http://dev.virtualearth.net/REST/v1/Elevation/List?points=35.89431,-110.72522,35.89393,-110.72578,35.89374,-110.72606,35.89337,-110.72662&key={BingMapsKey}

JSON Response

This example returns the following response where values are the elevation values and zoomLevel is the zoom level used.

{
   "authenticationResultCode":"ValidCredentials",
   "brandLogoUri":"http:\/\/dev.virtualearth.net\/Branding\/logo_powered_by.png",
   "copyright":"Copyright © 2012 Microsoft and its suppliers. All rights reserved. This API cannot be accessed and the content and any results may not be used, reproduced or transmitted in any manner without express written permission from Microsoft Corporation.",
   "resourceSets":[
      {  
         "estimatedTotal":1,
         "resources":[
            {  
               "__type":"ElevationData:http:\/\/schemas.microsoft.com\/search\/local\/ws\/rest\/v1",
               "elevations":[1776,1775,1777,1776],
               "zoomLevel":14
            }
         ]
      }
   ],
   "statusCode":200,
   "statusDescription":"OK",
   "traceId":"8d57dbeb0bb94e7ca67fd25b4114f5c3"
}

XML Response

This XML response is returned when output=xml is added to the URL.

<Response xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://schemas.microsoft.com/search/local/ws/rest/v1">
  <Copyright>
    Copyright © 2012 Microsoft and its suppliers. All rights reserved. This API cannot be accessed and the content and any results may not be used, reproduced or transmitted in any manner without express written permission from Microsoft Corporation.
  </Copyright>
  <BrandLogoUri>http://dev.virtualearth.net/Branding/logo_powered_by.png</BrandLogoUri>
  <StatusCode>200</StatusCode>
  <StatusDescription>OK</StatusDescription>
  <AuthenticationResultCode>ValidCredentials</AuthenticationResultCode>
  <TraceId>
    3e6771dbe66045a18f72a787dc8c8deb
  </TraceId>
  <ResourceSets>
    <ResourceSet>
      <EstimatedTotal>1</EstimatedTotal>
      <Resources>
        <ElevationData>
          <ZoomLevel>14</ZoomLevel>
          <Elevations>
            <int>1776</int>
            <int>1775</int>
            <int>1777</int>
            <int>1776</int>
          </Elevations>
        </ElevationData>
      </Resources>
    </ResourceSet>
  </ResourceSets>
</Response>

Get the elevations for a rectangular area on the Earth

The geoid model is used to compute the elevations at the vertices of a rectangular grid. The bounds (bounding box) values specify an area that is further divided by the number of rows and columns specified. Two (2) rows and two (2) columns represent the bounding box.

http://dev.virtualearth.net/REST/v1/Elevation/Bounds?bounds=50.995391,-1.320763,51.000577,-1.311836&rows=4&cols=4&key={BingMapsKey}

JSON Response

This example returns the following response where values are the elevation values and zoomLevel is the zoom level used.

{
   "authenticationResultCode":"ValidCredentials",
   "brandLogoUri":"http:\/\/dev.virtualearth.net\/Branding\/logo_powered_by.png",
   "copyright":"Copyright © 2012 Microsoft and its suppliers. All rights reserved. This API cannot be accessed and the content and any results may not be used, reproduced or transmitted in any manner without express written permission from Microsoft Corporation.",
   "resourceSets":[
      {
         "estimatedTotal":1,
         "resources":[
            {
               "__type":"ElevationData:http:\/\/schemas.microsoft.com\/search\/local\/ws\/rest\/v1",
               "elevations":[35,39,42,41,35,37,39,43,38,37,41,40,37,41,48,49],
               "zoomLevel":11
            }
         ]
      }
   ],
   "statusCode":200,
   "statusDescription":"OK",
   "traceId":"55ae05364e3d4ca3a6b6ed864b9e652a"
}

XML Response

This XML response is returned when output=xml is added to the URL.

<Response xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://schemas.microsoft.com/search/local/ws/rest/v1">
  <Copyright>
    Copyright © 2012 Microsoft and its suppliers. All rights reserved. This API cannot be accessed and the content and any results may not be used, reproduced or transmitted in any manner without express written permission from Microsoft Corporation.
  </Copyright>
  <BrandLogoUri>
    http://dev.virtualearth.net/Branding/logo_powered_by.png
  </BrandLogoUri>
  <StatusCode>200</StatusCode>
  <StatusDescription>OK</StatusDescription>
  <AuthenticationResultCode>ValidCredentials</AuthenticationResultCode>
  <TraceId>
    e039402824834526bd60c8db99c3e837
  </TraceId>
  <ResourceSets>
    <ResourceSet>
      <EstimatedTotal>1</EstimatedTotal>
      <Resources>
        <ElevationData>
          <ZoomLevel>11</ZoomLevel>
          <Elevations>
            <int>35</int>
            <int>39</int>
            <int>42</int>
            <int>41</int>
            <int>35</int>
            <int>37</int>
            <int>39</int>
            <int>43</int>
            <int>38</int>
            <int>37</int>
            <int>41</int>
            <int>40</int>
            <int>37</int>
            <int>41</int>
            <int>48</int>
            <int>49</int>
          </Elevations>
        </ElevationData>
      </Resources>
    </ResourceSet>
  </ResourceSets>
</Response>

Get the elevations at equally-spaced locations along a polyline

A polyline path is computed from the latitude and longitude values. Elevations are computed for the endpoints and eight (8) equally-spaced points in between. The ellipsoid Earth model is used to compute the elevations because heights=ellipsoid is specified.

http://dev.virtualearth.net/REST/v1/Elevation/Polyline?points=35.89431,-110.72522,35.89393,-110.72578,35.89374,-110.72606,35.89337,-110.72662&heights=ellipsoid&samples=10&key={BingMapsKey}

JSON Response

This example returns the following response where values are the elevation values and zoomLevel is the zoom level used.

{
   "authenticationResultCode":"ValidCredentials",
   "brandLogoUri":"http:\/\/dev.virtualearth.net\/Branding\/logo_powered_by.png",
   "copyright":"Copyright © 2012 Microsoft and its suppliers. All rights reserved. This API cannot be accessed and the content and any results may not be used, reproduced or transmitted in any manner without express written permission from Microsoft Corporation.",
   "resourceSets":[
      {
         "estimatedTotal":1,
         "resources":[
            {
               "__type":"ElevationData:http:\/\/schemas.microsoft.com\/search\/local\/ws\/rest\/v1",
               "elevations":[1753,1752,1752,1752,1752,1754,1754,1754,1754,1753],
               "zoomLevel":14
            }
         ]
      }
   ],
   "statusCode":200,
   "statusDescription":"OK",
   "traceId":"3080e93328564e91abb68493ae826e2d"
}

XML Response

This XML response is returned when output=xml is added to the URL.

<Response xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://schemas.microsoft.com/search/local/ws/rest/v1">
  <Copyright>
    Copyright © 2012 Microsoft and its suppliers. All rights reserved. This API cannot be accessed and the content and any results may not be used, reproduced or transmitted in any manner without express written permission from Microsoft Corporation.
  </Copyright>
  <BrandLogoUri>
    http://veintplat2.live-int.com/Branding/logo_powered_by.png
  </BrandLogoUri>
  <StatusCode>200</StatusCode>
  <StatusDescription>OK</StatusDescription>
  <AuthenticationResultCode>ValidCredentials</AuthenticationResultCode>
  <TraceId>
    38ef4ca6e6da45508a3ea5225e730fca
  </TraceId>
  <ResourceSets>
    <ResourceSet>
      <EstimatedTotal>1</EstimatedTotal>
      <Resources>
        <ElevationData>
          <ZoomLevel>14</ZoomLevel>
          <Elevations>
            <int>1753</int>
            <int>1752</int>
            <int>1752</int>
            <int>1752</int>
            <int>1752</int>
            <int>1754</int>
            <int>1754</int>
            <int>1754</int>
            <int>1754</int>
            <int>1753</int>
          </Elevations>
        </ElevationData>
      </Resources>
    </ResourceSet>
  </ResourceSets>
</Response>

Get the offset of the geoid sea level model from the ellipsoid model at the specified locations

http://dev.virtualearth.net/REST/v1/Elevation/SeaLevel?points=35.89431,-110.72522,35.89393,-110.72578,35.89374,-110.72606,35.89337,-110.72662&key={BingMapsKey}

JSON Response

This example returns the following response where values show that the geoid sea level approximation is 23 meters below the ellipsoid at each location.

{
   "authenticationResultCode":"ValidCredentials",
   "brandLogoUri":"http:\/\/dev.virtualearth.net\/Branding\/logo_powered_by.png",
   "copyright":"Copyright © 2012 Microsoft and its suppliers. All rights reserved. This API cannot be accessed and the content and any results may not be used, reproduced or transmitted in any manner without express written permission from Microsoft Corporation.",
   "resourceSets":[
      {
         "estimatedTotal":1,
         "resources":[
            {
               "__type":"SeaLevelData:http:\/\/schemas.microsoft.com\/search\/local\/ws\/rest\/v1",
               "offsets":[-23, -23, -23, -23],
               "zoomLevel":14
            }
         ]
      }
   ],
   "statusCode":200,
   "statusDescription":"OK",
   "traceId":"ec8ceb0a09754aa3b9e981cb13a4282a"
}

XML Response

This XML response is returned when output=xml is added to the URL.

<Response xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://schemas.microsoft.com/search/local/ws/rest/v1">
  <Copyright>
    Copyright © 2012 Microsoft and its suppliers. All rights reserved. This API cannot be accessed and the content and any results may not be used, reproduced or transmitted in any manner without express written permission from Microsoft Corporation.
  </Copyright>
  <BrandLogoUri>http://dev.virtualearth.net/Branding/logo_powered_by.png</BrandLogoUri>
  <StatusCode>200</StatusCode>
  <StatusDescription>OK</StatusDescription>
  <AuthenticationResultCode>ValidCredentials</AuthenticationResultCode>
  <TraceId>
    e55037868ba34371a859462f7a0c59f3
  </TraceId>
  <ResourceSets>
    <ResourceSet>
      <EstimatedTotal>1</EstimatedTotal>
      <Resources>
        <SeaLevelData>
          <ZoomLevel>14</ZoomLevel>
          <Offsets>
            <int>-23</int>
            <int>-23</int>
            <int>-23</int>
            <int>-23</int>
          </Offsets>
        </SeaLevelData>
      </Resources>
    </ResourceSet>
  </ResourceSets>
</Response>

Use HTTP POST to get elevations

You can use HTTP POST protocol to make any request that takes the points parameter. You may want to do this if you have a large number of locations in your request. If you are typically requesting elevations for 400 points or less, you may want to implement the Point Compression Algorithm.

HTTP POST URL

http://dev.virtualearth.net/REST/v1/Elevation/List?key={BingMapsKey}

HTTP POST Header

Content-Length: insertLengthOfHTTPBody
Content-Type: text/plain; charset=utf-8

HTTP POST Body

points=38.8895,77.0501,38.8877,-77.0472,38.8904,-77.0474,38.8896,77.0351

HTTP Status Codes

Note

For more details about these HTTP status codes, see Status Codes and Error Handling.

When the request is successful, the following HTTP status code is returned.

When the request is not successful, the response returns one of the following errors.

Share via

Get Elevations

URL Templates

Get elevations for latitude and longitude coordinates

Get elevations at equally-spaced locations along a polyline path

Get elevations at equally-spaced locations within a bounding box

Get the offset of the geoid sea level Earth model from the ellipsoid Earth model

About Elevations and Coordinate Values

Template Parameters

Earth Models and Zoom Level

Elevation Coverage and Resolution

Response

Examples

Get elevations for a set of latitude and longitude coordinates

Get the elevations for a rectangular area on the Earth

Get the elevations at equally-spaced locations along a polyline

Get the offset of the geoid sea level model from the ellipsoid model at the specified locations

Use HTTP POST to get elevations

HTTP Status Codes

See Also

Additional resources