This article explains how to migrate the Bing Maps Find a Location by Address 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 article covers scenarios where your geocoding input, such as street address, is in structured format - similar to what Bing Maps Find a Location by Address API supports. For information on how to migrate Bing Maps scenarios where the geocoding input is not structured to get longitude and latitude coordinates of a street address, a place or landmark, see Migrate Bing Maps Find a Location by Query API.
Bing Maps Find a Location by Address API only supports geocoding input in structured 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 Address 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 Address API supports XML and JSON response format. Azure Maps Get Geocoding API supports GeoJSON.
Unlike Bing Maps Find a Location by Address 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 Address 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.
The following table lists the Bing Maps Find a Location by Address request parameters and the Azure Maps equivalent:
Bing Maps request parameter
Bing Maps request parameter alias
Azure Maps request parameter
Required in Azure Maps
Azure Maps data type
Description
Bing Maps request parameter
Bing Maps request parameter alias
Azure Maps request parameter
Required in Azure Maps
Azure Maps data type
Note
addressLine
addressLine
False
string
In Azure Maps Get Geocoding API, a street address, or street address with locality and adminDistrict, is supported input for addressLine.
adminDistrict
adminDistrict
False
string
countryRegion
countryRegion
False
string
locality
locality
False
string
postalCode
postalCode
False
string
culture
c
Request Header: Accept-Language
False
string
As specified in the Azure Maps request header, culture defines the language used in search results when using the Azure Maps Get Geocoding API. For more information, see Supported Languages.
include
incl
Not needed
Not needed
Not needed
In Bing Maps Find a Location by Address API, the ‘include’ input parameter is required in order to get a two-letter ISO country code for the location result in the response (include=ciso2). In Azure Maps Get Geocoding API, the two-letter ISO country code is returned by default.
includeNeighborhood
inclnb
Not needed
Not needed
Not needed
In Azure Maps Get Geocoding API, neighborhood info is returned in the response by default, when available.
maxResults
maxRes
top
False
Integer (int32)
In Azure Maps Get Geocoding API, the default number of responses returned is 5. The minimum is 1 and the maximum is 20.
strictMatch
sm
Not supported
Not supported
Not supported
userIp
uip
Not supported
Not supported
Not supported
userLocation
ul
coordinates
False
number[]
In Azure Maps Get Geocoding API, coordinates on the earth specified as in longitude and latitude format (longitude,latitude). When you specify this parameter, the user’s location is considered, and the results returned are more relevant to the user.
userMapView
umv
bbox
False
number[]
A rectangular area on the earth defined as a bounding box object. The sides of the rectangles are defined by longitude and latitude values (longitude1,latitude1,longitude2,latitude2). Use the following syntax to specify a bounding box:
West Longitude, South Latitude, East Longitude, North Latitude
When you specify this parameter, the geographical area is taken into account when computing the results of a location query.
userRegion
ur
view
False
string
A string that represents an ISO 3166-1 Alpha-2 region/country code that alters geopolitical disputed borders and labels to align with the specified user region. By default, the View parameter is set to Auto even if not defined in the request. For more information on available views, see Supported Views.
For more information about the Azure Maps Get Geocoding API request parameters, see URI Parameters.
Request examples
Bing Maps Find a Location by Address API POST request:
HTTP
http://dev.virtualearth.net/REST/v1/Locations/US/WA/Redmond/15127 NE 24th Street?&key={BingMapsKey}
Azure Maps Get Geocoding API POST request:
HTTP
https://atlas.microsoft.com/geocode?api-version=2023-06-01&adminDistrict=WA&locality=Redmond&addressLine=15127 NE 24th Street&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 Address request and the Azure Maps equivalent:
Bing Maps Field
Azure Maps Field
Description
address: addressLine (JSON)
Address: AddressLine (XML)
address: addressLine
address: adminDistrict (JSON)
Address: AdminDistrict (XML)
address: adminDistricts
address: adminDistrict2 (JSON)
Address: AdminDistrict2 (XML)
address: adminDistricts
address: countryRegion (JSON)
Address: CountryRegion (XML)
address: countryRegion
address: countryRegionIso2 (JSON)
Address: CountryRegionIso2 (XML)
address: countryRegion - iso
address: neighborhood (JSON)
Address: Neighborhood (XML)
address: neighborhood
address: formattedAddress (JSON)
Address: FormattedAddress (XML)
address: formattedAddress
address: locality (JSON)
Address: Locality (XML)
address: locality
address: postalCode (JSON)
Address: PostalCode (XML)
address: postalCode
address: Intersection – baseStreet (JSON)
Address: Intersection – BaseStreet (XML)
address: intersection -baseStreet
address: Intersection – secondaryStreet1 (JSON)
address: intersection - secondaryStreet1
address: Intersection – secondaryStreet2 (JSON)
Address: Intersection – SecondaryStreet2 (XML)
address: intersection - secondaryStreet2
address: Intersection – intersectionType (JSON)
Address: Intersection – IntersectionType (XML)
address: intersection - intersectionType
address: Intersection – displayName (JSON)
Address: Intersection – DisplayName (XML)
address: intersection - displayName
bbox (JSON)
BoundingBox (XML)
features: bbox
In Bing Maps Find a Location by Address API, the coordinates in the response are in latitude/longitude format. The coordinates in the response of the Azure Maps Get Geocoding API are in the longitude/latitude format (since GeoJSON format is used).
calculationMethod (JSON)
CalculationMethod (XML)
properties: geocodePoints - calculationMethod
confidence (JSON)
Confidence (XML)
properties: confidence
entityType (JSON)
EntityType (XML)
properties: type
geocodePoints (JSON)
GeocodePoint (XML)
properties: geocodePoints - coordinates
matchCodes (JSON)
MatchCode (XML)
properties: matchCodes
name (JSON)
Name (XML)
Not supported
formattedAddress is the Azure Maps equivalent.
point (JSON)
Point (XML)
features: coordinates
In Bing Maps Find a Location by Address API, the coordinates in the response are in latitude/longitude format. The coordinates in the response of the Azure Maps Get Geocoding API are in the longitude/latitude format (since GeoJSON format is used).
queryParse (JSON)
QueryParse (XML)
Not supported
usageTypes (JSON)
usageType (XML)
properties: geocodePoints: usageTypes
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 Address request:
Like Bing Maps Find a Location by Address 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.