Elevation

• May 26, 2021
• 3 minutes to read

This document explains how to provide a Map control with the capability to obtain elevation information of a location on a map.

The document consists of the following sections.

• Overview
• Enabling Elevation Requesting
• Processing Elevation Request Result

Overview

The Map control supports the Microsoft Bing Elevation service, allowing you to embed elevation requesting functionality to your map. When this feature is enabled, you can click on the map and obtain elevation information from the service.

The search functionality in the map control is performed by the Bing Search data provider. This provider is represented by the BingElevationDataProvider object. The section below explains how to use the BingElevationDataProvider in the map control.

Enabling Elevation Requesting

To enable elevation requesting in the Map control, do the following.

• Create an information layer and add it to the map.

  The information layer is used to present GIS elements above the map. For more information, see Layers.

• Create an instance of the BingElevationDataProvider and assign it to the InformationLayer.DataProvider property.

• Specify the Bing Maps key using the BingMapDataProviderBase.BingKey property.

  Note

  To create a developer account, refer to The Bing Maps Portal website.

  To learn more about how to register a Bing Maps account and create a key for it, refer to the following tutorial: How to: Get a Bing Maps Key.

The code snippet below shows how this can be done.

Form1.cs

// Create a new elevation data provider.
BingElevationDataProvider dataProvider = new BingElevationDataProvider {
    BingKey = yourBingKey,
    ProcessMouseEvents = true
};
informationLayer.DataProvider = dataProvider;
// Process result obtaining.
dataProvider.ElevationsCalculated += OnElevationsCalculated;

Form1.vb

' Create a new elevation data provider.
Dim dataProvider As BingElevationDataProvider = New BingElevationDataProvider With {.BingKey = yourBingKey, .ProcessMouseEvents = True}
informationLayer.DataProvider = dataProvider
' Process result obtaining.
AddHandler dataProvider.ElevationsCalculated, AddressOf OnElevationsCalculated

Using a Custom UI

The Map control provides the elevation request functionality for several points. Using this approach, you can build a custom request panel to get additional results from the Microsoft Bing Elevation service.

To send an elevation request, call the BingElevationDataProvider.RequestPointElevation or BingElevationDataProvider.RequestPointsElevations method.

For instance, you have a UI that consists of 2 text boxes named “tbLatitude”, “tbLongitude”, and a button named “Request Elevation”. To send a request, click the button. This calls the RequestPointElevation method.

C#

private void OnClick(object sender, EventArgs e) {    
    elevationProvider.RequestPointsElevations(new GeoPoint { 
        Latitude = Convert.ToDouble(tbLatitude.Text), 
        Longitude = Convert.ToDouble(tbLongitude.Text)
    });
} 

VB.NET

Private Sub OnClick(sender As Object, e As EventArgs)
    elevationProvider.RequestPointsElevations(New GeoPoint() With { _
        .Latitude = Convert.ToDouble(tbLatitude.Text), _
        .Longitude = Convert.ToDouble(tbLongitude.Text) _
    })
End Sub

Processing Elevation Request Result

To get the results for the request, handle the BingElevationDataProvider.ElevationsCalculated event, as shown below.

Form1.cs

private void OnElevationsCalculated(object sender, ElevationsCalculatedEventArgs e) {
    if(e.Cancelled == true || e.Error != null) return;
    if(e.Result.ResultCode != RequestResultCode.Success) return;

    informationLayer.Data.Items.Clear();
    // foreach requested location create a new callout with elevation value.
    foreach (ElevationInformation elevationResult in e.Result.Locations) {
        informationLayer.Data.Items.Add(new MapCallout {
            Location = elevationResult.Location,
            Text = String.Format("Elevation: {0}m.", elevationResult)
        });
    }
}

Form1.vb

Private Sub OnElevationsCalculated(ByVal sender As Object, ByVal e As ElevationsCalculatedEventArgs)
    If e.Cancelled = True OrElse e.Error IsNot Nothing Then
        Return
    End If
    If e.Result.ResultCode <> RequestResultCode.Success Then
        Return
    End If

    informationLayer.Data.Items.Clear()
    ' foreach requested location create a new callout with elevation value.
    For Each elevationResult As ElevationInformation In e.Result.Locations
        informationLayer.Data.Items.Add(New MapCallout With {.Location = elevationResult.Location, .Text = String.Format("Elevation: {0}m.", elevationResult)})
    Next elevationResult
End Sub

In the code above, the ElevationsCalculatedEventArgs.Result property is used to obtain the request results. The ElevationRequestResult.Locations property stores the elevation data for the points that had be sent in the request.