Migrate Bing Maps Find a Location by Query API

This article explains how to migrate the Bing Maps Find a Location by Query API to the Azure Maps Get Geocoding API. The Azure Maps Get Geocoding API is used to get longitude and latitude coordinates of a street address, a place or landmark. Azure Maps Get Geocoding API supports geocoding input in an unstructured or structured format. This migration documentation is for scenarios where your geocoding input, such as street address, locality, postal code, or landmark name, is in an unstructured format (query=) - similar to what Bing Maps Find a Location by Query API supports. For information on how to migrate Bing Maps scenarios where the geocoding input is structured to find a location by address, see Migrate Bing Maps Find a Location by Address API.

Prerequisites

• An Azure Account
• An Azure Maps account
• A subscription key or other form of Authentication with Azure Maps

Notable differences

• Bing Maps Find a Location by Query API only supports geocoding input in unstructured format, whereas Azure Maps Get Geocoding API supports geocoding input in an unstructured (query=) or structured (addressLine=) format. For geocoding landmark names, use Azure Maps Get Geocoding API using unstructured input format.
• Bing Maps Find a Location by Query API returns coordinates in latitude/longitude format, while Azure Maps Get Geocoding API returns coordinates in longitude/latitude format, as defined by the GeoJSON format.
• Bing Maps Find a Location by Query API supports XML and JSON response format. Azure Maps Get Geocoding API supports GeoJSON.
• Unlike Bing Maps Find a Location by Query API, Azure Maps Get Geocoding API has a view input parameter, which is a string that represents an ISO 3166-1 Alpha-2 region/country code. The view input parameter alters geopolitical disputed borders and labels to align with the specified user region. For more information, see URI Parameters.
• Unlike Bing Maps Find a Location by Query API, Azure Maps Get Geocoding API doesn’t currently support address geocoding for China, Japan, or South Korea.
• Unlike Bing Maps for Enterprise, Azure Maps is a global service that supports specifying a geographic scope, allowing limits to data residency to the European (EU) or United States (US) geographic areas (geos). All requests (including input data) are processed exclusively in the specified geographic area. For more information, see geographic scope.

Security and authentication

Bing Maps for Enterprise only supports API key authentication. Azure Maps supports multiple ways to authenticate your API calls, such as a subscription key, Microsoft Entra ID, and Shared Access Signature (SAS) Token. For more information on security and authentication in Azure Maps, See Authentication with Azure Maps and the Security section in the Azure Maps Get Geocoding documentation.

Request parameters

The following table lists the Bing Maps Find a Location by Query request parameters and the Azure Maps equivalent:

For more information about the Azure Maps Get Geocoding API request parameters, see URI Parameters.

Request examples

Bing Maps Find a Location by Query API POST request:

http://dev.virtualearth.net/REST/v1/Locations/15127 NE 24th Street Redmond WA&key={BingMapsKey}

Azure Maps Get Geocoding API POST request:

https://atlas.microsoft.com/geocode?api-version=2023-06-01&query=15127 NE 24th Street Redmond WA&subscription-key={Your-Azure-Maps-Subscription-key}

Response fields

The following table lists the fields that can appear in the HTTP response when running the Bing Maps Find a Location by Query request and the Azure Maps equivalent:

For more information about the Azure Maps Get Geocoding API response fields, see Definitions.

Response examples

The following JSON sample shows what is returned in the body of the HTTP response when executing the Bing Maps Find a Location by Query request:

{ 
    "authenticationResultCode": "ValidCredentials", 
    "brandLogoUri": "https://dev.virtualearth.net/Branding/logo_powered_by.png", 
    "copyright": "Copyright © 2024 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": "Location:http://schemas.microsoft.com/search/local/ws/rest/v1", 
                    "bbox": [ 
                        47.62649628242932, 
                        -122.14631082421619, 
                        47.634221717570675, 
                        -122.1310271757838 
                    ], 
                    "name": "15127 NE 24th St, Redmond, WA 98052", 
                    "point": { 
                        "type": "Point", 
                        "coordinates": [ 
                            47.630359, 
                            -122.138669 
                        ] 
                    }, 
                    "address": { 
                        "addressLine": "15127 NE 24th St", 
                        "adminDistrict": "WA", 
                        "adminDistrict2": "King County", 
                        "countryRegion": "United States", 
                        "formattedAddress": "15127 NE 24th St, Redmond, WA 98052", 
                        "locality": "Redmond", 
                        "postalCode": "98052" 
                    }, 
                    "confidence": "High", 
                    "entityType": "Address", 
                    "geocodePoints": [ 
                        { 
                            "type": "Point", 
                            "coordinates": [ 
                                47.630359, 
                                -122.138669 
                            ], 
                            "calculationMethod": "Rooftop", 
                            "usageTypes": [ 
                                "Display" 
                            ] 
                        }, 
                        { 
                            "type": "Point", 
                            "coordinates": [ 
                                47.630563, 
                                -122.1387383 
                            ], 
                            "calculationMethod": "Rooftop", 
                            "usageTypes": [ 
                                "Route" 
                            ] 
                        } 
                    ], 
                    "matchCodes": [ 
                        "Good" 
                    ] 
                } 
            ] 
        } 
    ], 
    "statusCode": 200, 
    "statusDescription": "OK", 
    "traceId": "7896468b37528ac145ef77cc62484fd6|MWH0032BE2|0.0.0.1|Ref A: 7D01B283F7644D2891600E265FB30B24 Ref B: CO1EDGE2318 Ref C: 2024-04-23T18:29:55Z" 

The following JSON sample shows what is returned in the body of the HTTP response when executing an Azure Maps Get Geocoding request:

{
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "geometry": {
                "type": "Point",
                "coordinates": [
                    -122.138679,
                    47.630356
                ]
            },
            "bbox": [
                -122.14632082377759,
                47.62649328242932,
                -122.1310371762224,
                47.634218717570675
            ],
            "properties": {
                "type": "Address",
                "confidence": "High",
                "matchCodes": [
                    "Good"
                ],
                "geocodePoints": [
                    {
                        "calculationMethod": "Rooftop",
                        "usageTypes": [
                            "Display"
                        ],
                        "geometry": {
                            "type": "Point",
                            "coordinates": [
                                -122.138679,
                                47.630356
                            ]
                        }
                    },
                    {
                        "calculationMethod": "Rooftop",
                        "usageTypes": [
                            "Route"
                        ],
                        "geometry": {
                            "type": "Point",
                            "coordinates": [
                                -122.138685,
                                47.6305637
                            ]
                        }
                    }
                ],
                "address": {
                    "addressLine": "15127 NE 24th St",
                    "postalCode": "98052",
                    "locality": "Redmond",
                    "formattedAddress": "15127 NE 24th St, Redmond, WA 98052",
                    "countryRegion": {
                        "name": "United States",
                        "ISO": "US"
                    },
                    "adminDistricts": [
                        {
                            "shortName": "WA"
                        },
                        {
                            "shortName": "King County"
                        }
                    ]
                }
            }
        }
    ]
}

Transactions usage

Like Bing Maps Find a Location by Query API, Azure Maps Get Geocoding API logs one billable transaction per request. For more information on Azure Maps transactions, see Understanding Azure Maps Transactions.

Additional information

• Get Geocoding Batch: Use to send a batch of queries to the Get Geocoding API in a single synchronous request.

Support

• Microsoft Q&A Forum