Geocode

• Mar 14, 2021
• 6 minutes to read

The Map control supports Microsoft’s Bing Geocode and the OpenStreetMap Geocode services, which provide information associated with the geographic point on a map (address, postcode, etc.) based on a point’s location (latitude and longitude coordinates).

The Bing Geocode and OpenStreetMap Geocode data providers provide the geocoding functionality and are represented by the BingGeocodeDataProvider and OsmGeocodeDataProvider classes. The sections below explain how to use the BingGeocodeDataProvider in the map control.

• Enabling Geocode
• Using a Custom UI
• Geocode Results
• Examples

Important

Due to Bing canceling the SOAP service on July 30, 2017, the Map Control’s Bing Geocode provider does not work correctly in version 16.1 and earlier.

Enabling Geocode

Do the following to enable geocoding in the Map control:

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

  The information layer provides vector elements that represent GIS data obtained from the Search service in the Map control. See Layers for more information.

• Create a BingGeocodeDataProvider or OsmGeocodeDataProvider class instance and assign it to the InformationLayer.DataProvider property.

• Specify the Bing Maps key for the Bing Geocode data provider using the BingMapDataProviderBase.BingKey property.

  Note

  Go to The Bing Maps Portal website to create a developer account.

  Refer to How to: Get a Bing Maps Key to learn more about how to register a Bing Maps account and create a key for it.

The code snippet below shows how to do this.

Note

A complete sample project is available at https://github.com/DevExpress-Examples/how-to-get-information-about-a-geographical-point-using-the-microsoft-bing-geocode-web-servi-e5061

Form1.cs

// Create a geocode data provider.
geocodeProvider = new BingGeocodeDataProvider {
    BingKey = yourBingKey,
    MaxVisibleResultCount = 1
};
geocodeProvider.LocationInformationReceived += OnLocationInformationReceived;
geocodeProvider.LayerItemsGenerating += OnLayerItemsGenerating;
informationLayer.DataProvider = geocodeProvider;

Form1.vb

' Create a geocode data provider.
geocodeProvider = New BingGeocodeDataProvider With {.BingKey = yourBingKey, .MaxVisibleResultCount = 1}
AddHandler geocodeProvider.LocationInformationReceived, AddressOf OnLocationInformationReceived
AddHandler geocodeProvider.LayerItemsGenerating, AddressOf OnLayerItemsGenerating
informationLayer.DataProvider = geocodeProvider

When the Map control is connected to the Bing Geocode service, you can use the pushpin’s tooltip to obtain information about a geographic point:

• Click the desired location on a map.

  This generates a pushpin at the mouse position (the InformationDataProviderBase.ProcessMouseEvents and InformationDataProviderBase.GenerateLayerItems properties are set to true by default).

• Hover the mouse cursor over the pushpin to see its tooltip.

The image below shows a tooltip for the pushpin at “Mecklenburgh Square”.

You can also use the InformationDataProviderBase.MaxVisibleResultCount property to specify how many tooltips can be shown on a map simultaneously.

Using a Custom UI

The map control allows you to obtain additional results (address, name, entity type, etc.) from the Bing Geocode service for a specified location.

Note

Set the InformationDataProviderBase.ProcessMouseEvents property to false if you do not want to generate pushpins when you click on the map.

To start geocoding for a location, call the BingGeocodeDataProvider.RequestLocationInformation or OsmGeocodeDataProvider.RequestLocationInformation method.

For instance, you have a UI that consists of 2 text boxes named “tbLatitude” and “tbLongitude”, and a button named “requestLocation”. To start a search, click the Request Location button. This calls the RequestLocationInformation method.

The results are stored by the RequestResultBase object’s GeocodeRequestResult descendant within the LocationInformationReceived event handler’s LocationInformationReceivedEventArgs.

The results contain the entity type, address, and coordinates associated with the geographic location.

Note

A complete sample project is available at https://github.com/DevExpress-Examples/how-to-get-information-about-a-geographical-point-using-the-microsoft-bing-geocode-web-servi-e5061

Form1.cs

private void requestLocation_Click(object sender, System.EventArgs e) {
    GeoPoint searchPoint;
    if(TryGetLocationArguments(out searchPoint)) {
        geocodeProvider.RequestLocationInformation(searchPoint, 0);
    }
}

bool TryGetLocationArguments(out GeoPoint point) {
    double latitude;
    double longitude;
    if (
        TryConvertLocationCoordinate(teLatitude.Text, minLatitude, maxLatitude, latitudeName, out latitude) && 
        TryConvertLocationCoordinate(teLongitude.Text, minLongitude, maxLongitude, longitudeName, out longitude)) {
        point = new GeoPoint(latitude, longitude);
        return true;
    }
    point = null;
    return false;
}

bool TryConvertLocationCoordinate(string str, double minValue, double maxValue, string valueName, out double value) {
    double convertedValue = String.IsNullOrEmpty(str)
        ? 0
        : Double.Parse(str);
    if((convertedValue > maxValue) || (convertedValue < minValue)) {
        MessageBox.Show(String.Format(msgMinMaxErrorFormatString, valueName, minValue, maxValue));
        value = 0;
        return false;
    }
    value = convertedValue;
    return true;

}

Form1.vb

Private Sub requestLocation_Click(ByVal sender As Object, ByVal e As System.EventArgs) Handles btnGeocode.Click
    Dim searchPoint As GeoPoint = Nothing
    If TryGetLocationArguments(searchPoint) Then
        geocodeProvider.RequestLocationInformation(searchPoint, 0)
    End If
End Sub

Private Function TryGetLocationArguments(ByRef point As GeoPoint) As Boolean
    Dim latitude As Double = Nothing
    Dim longitude As Double = Nothing
    If TryConvertLocationCoordinate(teLatitude.Text, minLatitude, maxLatitude, latitudeName, latitude) AndAlso TryConvertLocationCoordinate(teLongitude.Text, minLongitude, maxLongitude, longitudeName, longitude) Then
        point = New GeoPoint(latitude, longitude)
        Return True
    End If
    point = Nothing
    Return False
End Function

Private Function TryConvertLocationCoordinate(ByVal str As String, ByVal minValue As Double, ByVal maxValue As Double, ByVal valueName As String, ByRef value As Double) As Boolean
    Dim convertedValue As Double = If(String.IsNullOrEmpty(str), 0, Double.Parse(str))
    If (convertedValue > maxValue) OrElse (convertedValue < minValue) Then
        MessageBox.Show(String.Format(msgMinMaxErrorFormatString, valueName, minValue, maxValue))
        value = 0
        Return False
    End If
    value = convertedValue
    Return True

End Function

Geocode Results

To get the geocode results for a specified location, handle the BingGeocodeDataProvider.LocationInformationReceived or OsmGeocodeDataProvider.LocationInformationReceived event. The results are stored by the RequestResultBase object’s GeocodeRequestResult descendant within the LocationInformationReceived event handler’s LocationInformationReceivedEventArgs.

The following code snippet shows how to handle the event:

Note

A complete sample project is available at https://github.com/DevExpress-Examples/how-to-get-information-about-a-geographical-point-using-the-microsoft-bing-geocode-web-servi-e5061

Form1.cs

private void OnLocationInformationReceived(object sender, LocationInformationReceivedEventArgs e) {
    if(e.Cancelled == true) return;
    if(e.Result.ResultCode != RequestResultCode.Success) {
        meResult.Text = "The Bing Geocode service does not work for this location.";
        return;
    }
    StringBuilder resultList = new StringBuilder("");
    int resCounter = 1;
    foreach(LocationInformation locations in e.Result.Locations) {
        resultList.Append(String.Format("Request Result {0}:\r\n", resCounter));
        resultList.Append(String.Format(locations.EntityType + "\r\n"));
        resultList.Append(String.Format(locations.Address.FormattedAddress + "\r\n"));
        resultList.Append(String.Format("Coordinates: {0}\r\n", locations.Location));
        resultList.Append(String.Format("______________________________\r\n"));
        resCounter++;
    }
    meResult.Text = resultList.ToString();
}

Form1.vb

Private Sub OnLocationInformationReceived(ByVal sender As Object, ByVal e As LocationInformationReceivedEventArgs)
    If e.Cancelled = True Then
        Return
    End If
    If e.Result.ResultCode <> RequestResultCode.Success Then
        meResult.Text = "The Bing Geocode service does not work for this location."
        Return
    End If
    Dim resultList As New StringBuilder("")
    Dim resCounter As Integer = 1
    For Each locations As LocationInformation In e.Result.Locations
        resultList.Append(String.Format("Request Result {0}:" & ControlChars.CrLf, resCounter))
        resultList.Append(String.Format(locations.EntityType & ControlChars.CrLf))
        resultList.Append(String.Format(locations.Address.FormattedAddress & ControlChars.CrLf))
        resultList.Append(String.Format("Coordinates: {0}" & ControlChars.CrLf, locations.Location))
        resultList.Append(String.Format("______________________________" & ControlChars.CrLf))
        resCounter += 1
    Next locations
    meResult.Text = resultList.ToString()
End Sub

The results for Latitude - “41.27” and Longitude - “-96.05” are shown in the image below.

Examples

The following examples demonstrate how to use the geocode feature in the map control:

• How to: Connect a Map Control to the Bing Geocode Service
• How to: Manually Process Location Information Received From Bing Geocode Service