Search - Get Reverse Geocoding Batch
Use to send a batch of queries to the Reverse Geocoding API in a single request.
The Get Reverse Geocoding Batch
API is an HTTP POST
request that sends batches of up to 100 queries to Reverse Geocoding API using a single request.
Submit Synchronous Batch Request
The Synchronous API is recommended for lightweight batch requests. When the service receives a request, it will respond as soon as the batch items are calculated and there will be no possibility to retrieve the results later. The Synchronous API will return a timeout error (a 408 response) if the request takes longer than 60 seconds. The number of batch items is limited to 100 for this API.
POST https://atlas.microsoft.com/reverseGeocode:batch?api-version=2023-06-01
POST Body for Batch Request
To send the reverse geocoding queries you will use a POST
request where the request body will contain the batchItems
array in json
format and the Content-Type
header will be set to application/json
. Here's a sample request body containing 2 reverse geocoding queries:
{
"batchItems": [
{
"coordinates": [-122.128275, 47.639429],
"resultTypes": ["Address", "PopulatedPlace"]
},
{
"coordinates": [-122.341979399674, 47.6095253501216]
}
]
}
A reverse geocoding batchItem object can accept any of the supported reverse geocoding URI parameters.
The batch should contain at least 1 query.
Batch Response Model
The batch response contains a summary
component that indicates the totalRequests
that were part of the original batch request and successfulRequests
i.e. queries which were executed successfully. The batch response also includes a batchItems
array which contains a response for each and every query in the batch request. The batchItems
will contain the results in the exact same order the original queries were sent in the batch request. Each item is of one of the following types:
GeocodingResponse
- If the query completed successfully.Error
- If the query failed. The response will contain acode
and amessage
in this case.
POST https://atlas.microsoft.com/reverseGeocode:batch?api-version=2023-06-01
URI Parameters
Name | In | Required | Type | Description |
---|---|---|---|---|
api-version
|
query | True |
string |
Version number of Azure Maps API. |
Request Header
Name | Required | Type | Description |
---|---|---|---|
x-ms-client-id |
string |
Specifies which account is intended for usage in conjunction with the Azure AD security model. It represents a unique ID for the Azure Maps account and can be retrieved from the Azure Maps management plane Account API. To use Azure AD security in Azure Maps see the following articles for guidance. |
|
Accept-Language |
string |
Language in which search results should be returned. Please refer to Supported Languages for details. |
Request Body
Name | Type | Description |
---|---|---|
batchItems |
The list of queries to process. |
Responses
Name | Type | Description |
---|---|---|
200 OK |
OK |
|
Other Status Codes |
An unexpected error occurred. |
Security
AADToken
These are the Microsoft Entra OAuth 2.0 Flows. When paired with Azure role-based access control it can be used to control access to Azure Maps REST APIs. Azure role-based access controls are used to designate access to one or more Azure Maps resource account or sub-resources. Any user, group, or service principal can be granted access via a built-in role or a custom role composed of one or more permissions to Azure Maps REST APIs.
To implement scenarios, we recommend viewing authentication concepts. In summary, this security definition provides a solution for modeling application(s) via objects capable of access control on specific APIs and scopes.
Note
- This security definition requires the use of the
x-ms-client-id
header to indicate which Azure Maps resource the application is requesting access to. This can be acquired from the Maps management API. - The
Authorization URL
is specific to the Azure public cloud instance. Sovereign clouds have unique Authorization URLs and Microsoft Entra ID configurations. - The Azure role-based access control is configured from the Azure management plane via Azure portal, PowerShell, CLI, Azure SDKs, or REST APIs.
- Usage of the Azure Maps Web SDK allows for configuration based setup of an application for multiple use cases.
- For more information on Microsoft identity platform, see Microsoft identity platform overview.
Type:
oauth2
Flow:
implicit
Authorization URL:
https://login.microsoftonline.com/common/oauth2/authorize
Scopes
Name | Description |
---|---|
https://atlas.microsoft.com/.default | https://atlas.microsoft.com/.default |
subscription-key
This is a shared key that is provisioned when creating an Azure Maps resource through the Azure management plane via Azure portal, PowerShell, CLI, Azure SDKs, or REST APIs.
With this key, any application is authorized to access all REST APIs. In other words, these can currently be treated as master keys to the account which they are issued for.
For publicly exposed applications, our recommendation is to use server-to-server access of Azure Maps REST APIs where this key can be securely stored.
Type:
apiKey
In:
header
SAS Token
This is a shared access signature token is created from the List SAS operation on the Azure Maps resource through the Azure management plane via Azure portal, PowerShell, CLI, Azure SDKs, or REST APIs.
With this token, any application is authorized to access with Azure role-based access controls and fine-grain control to the expiration, rate, and region(s) of use for the particular token. In other words, the SAS Token can be used to allow applications to control access in a more secured way than the shared key.
For publicly exposed applications, our recommendation is to configure a specific list of allowed origins on the Map account resource to limit rendering abuse and regularly renew the SAS Token.
Type:
apiKey
In:
header
Examples
A Reverse Geocoding Batch API call containing 2 Reverse Geocoding queries
Sample request
POST https://atlas.microsoft.com/reverseGeocode:batch?api-version=2023-06-01
{
"batchItems": [
{
"coordinates": [
-122.128275,
47.639429
],
"resultTypes": [
"Address",
"PopulatedPlace"
],
"optionalId": "4C3681A6C8AA4AC3441412763A2A25C81444DC8B"
},
{
"coordinates": [
-122.341979399674,
47.6095253501216
],
"optionalId": "6M9W39P12SNHGAIZ4JQ7F57NWJLV2BRYEQRD7OH7"
}
]
}
Sample response
{
"summary": {
"successfulRequests": 1,
"totalRequests": 2
},
"batchItems": [
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {
"type": "Address",
"confidence": "High",
"matchCodes": [
"Good"
],
"address": {
"locality": "Redmond",
"adminDistricts": [
{
"shortName": "WA"
},
{
"shortName": "King"
}
],
"countryRegion": {
"ISO": "US",
"name": "United States"
},
"postalCode": "98052",
"formattedAddress": "1 Microsoft Way, Redmond, WA 98052",
"addressLine": "1 Microsoft Way"
},
"geocodePoints": [
{
"geometry": {
"type": "Point",
"coordinates": [
-122.128275,
47.639429
]
},
"calculationMethod": "Rooftop",
"usageTypes": [
"Display",
"Route"
]
},
{
"geometry": {
"type": "Point",
"coordinates": [
-122.127028,
47.638545
]
},
"calculationMethod": "Rooftop",
"usageTypes": [
"Route"
]
}
]
},
"geometry": {
"type": "Point",
"coordinates": [
-122.128275,
47.639429
]
},
"bbox": [
-122.1359181505759,
47.63556628242932,
-122.1206318494241,
47.643291717570676
]
}
]
},
{
"optionalId": "3K5O3Y832J2YV6D7XNGUSM4ECCUGDEFN172CJQNN",
"error": {
"code": "400 Bad Request",
"message": "The provided coordinates in query are invalid, out of range, or not in the expected format"
}
}
]
}
Definitions
Name | Description |
---|---|
Address |
The address of the result |
Admin |
The subdivision name in the country or region for an address. This element is typically treated as the first order administrative subdivision, but in some cases it also contains the second, third, or fourth order subdivision in a country, dependency, or region. |
Calculation |
The method that was used to compute the geocode point. |
Confidence |
The level of confidence that the geocoded location result is a match. Use this value with the match code to determine for more complete information about the match. The confidence of a geocoded location is based on many factors including the relative importance of the geocoded location and the user’s location, if specified. |
Country |
|
Error |
The resource management error additional info. |
Error |
The error detail. |
Error |
Error response |
Feature |
The type of a FeatureCollection object must be FeatureCollection. |
Features |
|
Feature |
The type of a feature must be Feature. |
Geocode |
A collection of geocode points that differ in how they were calculated and their suggested use. |
Geocoding |
This object is returned from a successful Geocoding Batch service call. |
Geocoding |
|
Geo |
A valid |
Intersection |
The address of the result. |
Match |
One or more match code values that represent the geocoding level for each location in the response. For example, a geocoded location with match codes of Similarly, a geocoded location with match codes of The possible values are:
|
Properties | |
Result |
Specify entity types that you want in the response. Only the types you specify will be returned. If the point cannot be mapped to the entity types you specify, no location information is returned in the response. Default value is all possible entities. A comma separated list of entity types selected from the following options.
These entity types are ordered from the most specific entity to the least specific entity. When entities of more than one entity type are found, only the most specific entity is returned. For example, if you specify Address and AdminDistrict1 as entity types and entities were found for both types, only the Address entity information is returned in the response. |
Reverse |
The list of reverse geocoding queries/requests to process. The list can contain a max of 100 queries and must contain at least 1 query. |
Reverse |
Batch Query object |
Summary |
Summary for the batch request |
Usage |
The best use for the geocode point.
Each geocode point is defined as a |
Address
The address of the result
Name | Type | Description |
---|---|---|
addressLine |
string |
AddressLine that includes Street Name and Number |
adminDistricts |
The subdivision name in the country or region for an address. This element is typically treated as the first order administrative subdivision, but in some cases it also contains the second, third, or fourth order subdivision in a country, dependency, or region. |
|
countryRegion | ||
formattedAddress |
string |
Formatted Address property |
intersection |
The address of the result. |
|
locality |
string |
locality property |
neighborhood |
string |
neighborhood property |
postalCode |
string |
Postal Code property |
AdminDistricts
The subdivision name in the country or region for an address. This element is typically treated as the first order administrative subdivision, but in some cases it also contains the second, third, or fourth order subdivision in a country, dependency, or region.
Name | Type | Description |
---|---|---|
name |
string |
The name for the corresponding adminDistrict field, For adminDistrict[0], this could be full name of state such as Washington, For adminDistrict[1], this could be the full name of the county |
shortName |
string |
The short name for the corresponding adminDistrict field, For adminDistrict[0], this could be short name of state such as WA, For adminDistrict[1], this could be the short name of the county |
CalculationMethodEnum
The method that was used to compute the geocode point.
Name | Type | Description |
---|---|---|
Interpolation |
string |
The geocode point was matched to a point on a road using interpolation. |
InterpolationOffset |
string |
The geocode point was matched to a point on a road using interpolation with an additional offset to shift the point to the side of the street. |
Parcel |
string |
The geocode point was matched to the center of a parcel. |
Rooftop |
string |
The geocode point was matched to the rooftop of a building. |
ConfidenceEnum
The level of confidence that the geocoded location result is a match. Use this value with the match code to determine for more complete information about the match.
The confidence of a geocoded location is based on many factors including the relative importance of the geocoded location and the user’s location, if specified.
Name | Type | Description |
---|---|---|
High |
string |
If the confidence is set to If a request includes a location or a view, then the ranking may change appropriately. For example, a location query for "Paris" returns "Paris, France" and "Paris, TX" both with |
Low |
string |
|
Medium |
string |
In some situations, the returned match may not be at the same level as the information provided in the request. For example, a request may specify address information and the geocode service may only be able to match a postal code. In this case, if the geocode service has a confidence that the postal code matches the data, the confidence is set to If the location information in the query is ambiguous, and there is no additional information to rank the locations (such as user location or the relative importance of the location), the confidence is set to If the location information in the query does not provide enough information to geocode a specific location, a less precise location value may be returned and the confidence is set to |
CountryRegion
Name | Type | Description |
---|---|---|
ISO |
string |
ISO of country/region |
name |
string |
name of country/region |
ErrorAdditionalInfo
The resource management error additional info.
Name | Type | Description |
---|---|---|
info |
object |
The additional info. |
type |
string |
The additional info type. |
ErrorDetail
The error detail.
Name | Type | Description |
---|---|---|
additionalInfo |
The error additional info. |
|
code |
string |
The error code. |
details |
The error details. |
|
message |
string |
The error message. |
target |
string |
The error target. |
ErrorResponse
Error response
Name | Type | Description |
---|---|---|
error |
The error object. |
FeatureCollectionEnum
The type of a FeatureCollection object must be FeatureCollection.
Name | Type | Description |
---|---|---|
FeatureCollection |
string |
FeaturesItem
Name | Type | Description |
---|---|---|
bbox |
number[] |
Bounding box. Projection used - EPSG:3857. Please refer to RFC 7946 for details. |
geometry |
A valid |
|
id |
string |
ID for feature returned |
properties | ||
type |
The type of a feature must be Feature. |
FeatureTypeEnum
The type of a feature must be Feature.
Name | Type | Description |
---|---|---|
Feature |
string |
GeocodePoints
A collection of geocode points that differ in how they were calculated and their suggested use.
Name | Type | Description |
---|---|---|
calculationMethod |
The method that was used to compute the geocode point. |
|
geometry |
A valid |
|
usageTypes |
The best use for the geocode point.
Each geocode point is defined as a |
GeocodingBatchResponse
This object is returned from a successful Geocoding Batch service call.
Name | Type | Description |
---|---|---|
batchItems |
Array containing the batch results. |
|
nextLink |
string |
The is the link to the next page of the features returned. If it's the last page, no this field. |
summary |
Summary for the batch request |
GeocodingBatchResponseItem
Name | Type | Description |
---|---|---|
error |
The error detail. |
|
features | ||
nextLink |
string |
The is the link to the next page of the features returned. If it's the last page, no this field. |
optionalId |
string |
id of the batchItem which would be the same as the id in the request |
type |
The type of a FeatureCollection object must be FeatureCollection. |
GeoJsonPoint
A valid GeoJSON Point
geometry type. Please refer to RFC 7946 for details.
Name | Type | Description |
---|---|---|
bbox |
number[] |
Bounding box. Projection used - EPSG:3857. Please refer to RFC 7946 for details. |
coordinates |
number[] |
A |
type |
string:
Point |
Specifies the |
Intersection
The address of the result.
Name | Type | Description |
---|---|---|
baseStreet |
string |
Primary street for the location. |
displayName |
string |
Complete name of the intersection. |
intersectionType |
string |
Type of intersection. |
secondaryStreet1 |
string |
The first intersecting street. |
secondaryStreet2 |
string |
If any, the second intersecting street. |
MatchCodesEnum
One or more match code values that represent the geocoding level for each location in the response.
For example, a geocoded location with match codes of Good
and Ambiguous
means that more than one geocode location was found for the location information and that the geocode service did not have search up-hierarchy to find a match.
Similarly, a geocoded location with match codes of Ambiguous
and UpHierarchy
implies that a geocode location could not be found that matched all the provided location information, so the geocode service had to search up-hierarchy and found multiple matches at that level. An example of up an Ambiguous
and UpHierarchy
result is when you provide complete address information, but the geocode service cannot locate a match for the street address and instead returns information for more than one RoadBlock value.
The possible values are:
Good
: The location has only one match or all returned matches are considered strong matches. For example, a query for New York returns several Good matches.
Ambiguous
: The location is one of a set of possible matches. For example, when you query for the street address 128 Main St., the response may return two locations for 128 North Main St. and 128 South Main St. because there is not enough information to determine which option to choose.
UpHierarchy
: The location represents a move up the geographic hierarchy. This occurs when a match for the location request was not found, so a less precise result is returned. For example, if a match for the requested address cannot be found, then a match code of UpHierarchy
with a RoadBlock entity type may be returned.
Name | Type | Description |
---|---|---|
Ambiguous |
string |
|
Good |
string |
|
UpHierarchy |
string |
Properties
Name | Type | Description |
---|---|---|
address |
The address of the result |
|
confidence |
The level of confidence that the geocoded location result is a match. Use this value with the match code to determine for more complete information about the match. The confidence of a geocoded location is based on many factors including the relative importance of the geocoded location and the user’s location, if specified. |
|
geocodePoints |
A collection of geocode points that differ in how they were calculated and their suggested use. |
|
matchCodes |
One or more match code values that represent the geocoding level for each location in the response. For example, a geocoded location with match codes of Similarly, a geocoded location with match codes of The possible values are:
|
|
type |
string |
One of:
|
ResultTypeEnum
Specify entity types that you want in the response. Only the types you specify will be returned. If the point cannot be mapped to the entity types you specify, no location information is returned in the response. Default value is all possible entities. A comma separated list of entity types selected from the following options.
- Address
- Neighborhood
- PopulatedPlace
- Postcode1
- AdminDivision1
- AdminDivision2
- CountryRegion
These entity types are ordered from the most specific entity to the least specific entity. When entities of more than one entity type are found, only the most specific entity is returned. For example, if you specify Address and AdminDistrict1 as entity types and entities were found for both types, only the Address entity information is returned in the response.
Name | Type | Description |
---|---|---|
Address |
string |
|
AdminDivision1 |
string |
|
AdminDivision2 |
string |
|
CountryRegion |
string |
|
Neighborhood |
string |
|
PopulatedPlace |
string |
|
Postcode1 |
string |
ReverseGeocodingBatchRequestBody
The list of reverse geocoding queries/requests to process. The list can contain a max of 100 queries and must contain at least 1 query.
Name | Type | Description |
---|---|---|
batchItems |
The list of queries to process. |
ReverseGeocodingBatchRequestItem
Batch Query object
Name | Type | Description |
---|---|---|
coordinates |
number[] |
The coordinates of the location that you want to reverse geocode. Example: [lon,lat] |
optionalId |
string |
id of the request which would show in corresponding batchItem |
resultTypes |
Specify entity types that you want in the response. Only the types you specify will be returned. If the point cannot be mapped to the entity types you specify, no location information is returned in the response. Default value is all possible entities. A comma separated list of entity types selected from the following options.
These entity types are ordered from the most specific entity to the least specific entity. When entities of more than one entity type are found, only the most specific entity is returned. For example, if you specify Address and AdminDistrict1 as entity types and entities were found for both types, only the Address entity information is returned in the response. |
|
view |
string |
A string that specifies an ISO 3166-1 Alpha-2 region/country code. This will alter Geopolitical disputed borders and labels to align with the specified user region. |
Summary
Summary for the batch request
Name | Type | Description |
---|---|---|
successfulRequests |
integer |
Number of successful requests in the batch |
totalRequests |
integer |
Total number of requests in the batch |
UsageTypeEnum
The best use for the geocode point.
Each geocode point is defined as a Route
point, a Display
point or both.
Use Route
points if you are creating a route to the location. Use Display
points if you are showing the location on a map. For example, if the location is a park, a Route
point may specify an entrance to the park where you can enter with a car, and a Display
point may be a point that specifies the center of the park.
Name | Type | Description |
---|---|---|
Display |
string |
|
Route |
string |