Search - Get Geocoding Batch
Use to send a batch of queries to the Geocoding API in a single request.
The Get Geocoding Batch API is an HTTP POST request that sends batches of up to 100 queries to the Geocoding API in 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/geocode:batch?api-version={api-version}
POST Body for Batch Request
To send the 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 geocoding queries:
{
"batchItems": [
{
"addressLine": "One, Microsoft Way, Redmond, WA 98052",
"top": 2
},
{
"addressLine": "Pike Pl",
"adminDistrict": "WA",
"locality": "Seattle",
"top": 3
}
]
}
A geocoding batchItem object can accept any of the supported 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 acodeand amessagein this case.
POST {endpoint}/geocode:batch?api-version=2026-01-01
URI Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
|
endpoint
|
path | True |
string |
|
|
api-version
|
query | True |
string minLength: 1 |
The API version to use for this operation. |
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. For more information on using Microsoft Entra ID security in Azure Maps, see Manage authentication in Azure Maps. |
|
| 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 |
The request has succeeded. |
|
| Other Status Codes |
An unexpected error response. Headers x-ms-error-code: string |
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.\n\nTo 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.\n\n#### Notes\n* 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.\n* \nThe Authorization URL is specific to the Azure public cloud instance. Sovereign clouds have unique Authorization URLs and Microsoft Entra ID configurations. \n* \nThe Azure role-based access control is configured from the Azure management plane via Azure portal, PowerShell, CLI, Azure SDKs, or REST APIs.\n* \nUsage of the Azure Maps Web SDK allows for configuration based setup of an application for multiple use cases.\n* 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 |
subscription-key
This is a shared key that is provisioned when you Create an Azure Maps account in the Azure portal or using PowerShell, CLI, Azure SDKs, or REST API.\n\n With this key, any application can access all REST API. In other words, this key can be used as a master key in the account that they are issued in.\n\n For publicly exposed applications, our recommendation is to use the confidential client applications approach to access Azure Maps REST APIs so your 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.\n\n 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.\n\n 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 Geocoding Batch API call containing 2 Geocoding queries
Sample request
POST {endpoint}/geocode:batch?api-version=2026-01-01
{
"batchItems": [
{
"addressLine": "15127 NE 24th Street, Redmond, WA 98052",
"top": 2,
"optionalId": "4C3681A6C8AA4AC3441412763A2A25C81444DC8B"
},
{
"query": "Pike Pl",
"locality": "Seattle",
"top": 3
}
]
}
Sample response
{
"summary": {
"successfulRequests": 1,
"totalRequests": 2
},
"batchItems": [
{
"optionalId": "4C3681A6C8AA4AC3441412763A2A25C81444DC8B",
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {
"type": "Address",
"confidence": "High",
"matchCodes": [
"Good"
],
"address": {
"locality": "Redmond",
"adminDistricts": [
{
"shortName": "WA"
},
{
"shortName": "King County"
}
],
"countryRegion": {
"ISO": "US",
"name": "United States"
},
"postalCode": "98052",
"formattedAddress": "15127 NE 24th St, Redmond, WA 98052",
"streetName": "NE 24th St",
"streetNumber": "15127",
"addressLine": "15127 NE 24th St"
},
"geocodePoints": [
{
"geometry": {
"type": "Point",
"coordinates": [
-122.138669,
47.630359
]
},
"calculationMethod": "Rooftop",
"usageTypes": [
"Display",
"Route"
]
},
{
"geometry": {
"type": "Point",
"coordinates": [
-122.1387383,
47.630563
]
},
"calculationMethod": "Rooftop",
"usageTypes": [
"Route"
]
}
]
},
"geometry": {
"type": "Point",
"coordinates": [
-122.138669,
47.630359
]
},
"bbox": [
-122.14631082421619,
47.62649628242932,
-122.1310271757838,
47.634221717570675
]
}
]
},
{
"error": {
"code": "Conflicting Parameters",
"message": "When 'query' is present, only the following parameters are valid: 'bbox, location, view, top'. 'locality' was passed"
}
}
]
}
Definitions
| Name | Description |
|---|---|
| Address |
The address of the result |
|
Address |
The subdivision name in the country or region for an address. |
|
Address |
Country or region with its name and ISO code. |
|
Azure. |
The error object. |
|
Azure. |
A response containing error details. |
|
Azure. |
An object containing more specific information about the error. As per Azure REST API guidelines - https://aka.ms/AzureRestApiGuidelines#handling-errors. |
|
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. |
|
Error |
The resource management error additional info. |
|
Error |
The error detail. |
|
Feature |
Specifies the |
|
Features |
A feature object. |
|
Features |
Properties of the feature. |
|
Feature |
The type of a feature must be Feature. |
|
Geocode |
A geocode point. |
|
Geocoding |
The list of address geocoding queries/requests to process. The list can contain a max of 100 queries and must contain at least 1 query. |
|
Geocoding |
Batch Query object |
|
Geocoding |
This object is returned from a successful Geocoding Batch service call. |
|
Geocoding |
A batch response item. |
|
Geocoding |
Summary for the batch request |
|
Geo |
Specifies the |
|
Geo |
A valid |
| Intersection |
The address of the result. |
|
Match |
An enum representing the match code. |
|
Usage |
An enum representing the usage type. |
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 |
Country or region with its name and ISO code. |
|
| formattedAddress |
string |
Formatted address property |
| intersection |
The address of the result. |
|
| locality |
string |
Locality property |
| neighborhood |
string |
Neighborhood property |
| postalCode |
string |
Postal code property |
| streetName |
string |
The name of the street from formattedAddress |
| streetNumber |
string |
The number in the street, if available, from formattedAddress |
AddressAdminDistrictsItem
The subdivision name in the country or region for an address.
| 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 |
AddressCountryRegion
Country or region with its name and ISO code.
| Name | Type | Description |
|---|---|---|
| ISO |
string |
ISO of country/region |
| name |
string |
name of country/region |
Azure.Core.Foundations.Error
The error object.
| Name | Type | Description |
|---|---|---|
| code |
string |
One of a server-defined set of error codes. |
| details |
An array of details about specific errors that led to this reported error. |
|
| innererror |
An object containing more specific information than the current object about the error. |
|
| message |
string |
A human-readable representation of the error. |
| target |
string |
The target of the error. |
Azure.Core.Foundations.ErrorResponse
A response containing error details.
| Name | Type | Description |
|---|---|---|
| error |
The error object. |
Azure.Core.Foundations.InnerError
An object containing more specific information about the error. As per Azure REST API guidelines - https://aka.ms/AzureRestApiGuidelines#handling-errors.
| Name | Type | Description |
|---|---|---|
| code |
string |
One of a server-defined set of error codes. |
| innererror |
Inner error. |
CalculationMethodEnum
The method that was used to compute the geocode point.
| Value | Description |
|---|---|
| Interpolation |
The geocode point was matched to a point on a road using interpolation. |
| InterpolationOffset |
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 |
The geocode point was matched to the center of a parcel. |
| Rooftop |
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.
| Value | Description |
|---|---|
| High |
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 |
| Medium |
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 |
| Low |
Low |
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. |
FeatureCollectionEnum
Specifies the GeoJSON type. The only supported object type is FeatureCollection. For more information, see RFC 7946.
| Value | Description |
|---|---|
| FeatureCollection |
Specifies the |
FeaturesItem
A feature object.
| Name | Type | Description |
|---|---|---|
| bbox |
number[] (double) |
Bounding box. Projection used - EPSG:3857. Please refer to RFC 7946 for details. |
| geometry |
A valid |
|
| id |
string |
ID for feature returned |
| properties |
Properties of the feature. |
|
| type |
The type of a feature must be Feature. |
FeaturesItemProperties
Properties of the feature.
| 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: * Address * RoadBlock * RoadIntersection * Neighborhood * PopulatedPlace * Postcode1 * AdminDivision1 * AdminDivision2 * CountryRegion |
FeatureTypeEnum
The type of a feature must be Feature.
| Value | Description |
|---|---|
| Feature |
Specifies the |
GeocodePointsItem
A geocode point.
| 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 |
GeocodingBatchRequestBody
The list of address 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. |
GeocodingBatchRequestItem
Batch Query object
| Name | Type | Default value | Description |
|---|---|---|---|
| addressLine |
string |
The official street line of an address relative to the area, as specified by the locality, or postalCode, properties. Typical use of this element would be to provide a street address or any official address. This parameter should not be used when the |
|
| adminDistrict |
string |
The country subdivision portion of an address, such as WA. This parameter should not be used when the |
|
| adminDistrict2 |
string |
The county for the structured address, such as King. This parameter should not be used when the |
|
| adminDistrict3 |
string |
The named area for the structured address. This parameter should not be used when the |
|
| bbox |
number[] (double) |
A rectangular area on the earth defined as a bounding box object. The sides of the rectangles are defined by longitude and latitude values. For more information, see Location and Area Types. When you specify this parameter, the geographical area is taken into account when computing the results of a location query. Example: [lon1, lat1, lon2, lat2] |
|
| coordinates |
number[] (double) |
A point on the earth specified as a longitude and latitude. When you specify this parameter, the user’s location is taken into account and the results returned may be more relevant to the user. Example: [lon, lat] |
|
| countryRegion |
string |
Signal for the geocoding result to an ISO 3166-1 Alpha-2 region/country code that is specified e.g. FR. This parameter should not be used when the |
|
| locality |
string |
The locality portion of an address, such as Seattle. This parameter should not be used when the |
|
| optionalId |
string |
id of the request which would show in corresponding batchItem |
|
| postalCode |
string |
The postal code portion of an address. This parameter should not be used when the |
|
| query |
string |
A string that contains information about a location, such as an address or landmark name. |
|
| top |
integer (int32) minimum: 1maximum: 20 |
5 |
Maximum number of responses that will be returned. Default: 5, minimum: 1 and maximum: 20. |
| view |
string |
auto |
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. |
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
A batch response item.
| Name | Type | Description |
|---|---|---|
| error |
The error detail. |
|
| features |
An array of features returned from the query. |
|
| 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 |
Specifies the |
GeocodingBatchResponseSummary
Summary for the batch request
| Name | Type | Description |
|---|---|---|
| successfulRequests |
integer (int32) |
Number of successful requests in the batch |
| totalRequests |
integer (int32) |
Total number of requests in the batch |
GeoJsonObjectType
Specifies the GeoJSON type. Must be one of the nine valid GeoJSON object
types - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon,
GeometryCollection, Feature and FeatureCollection.
| Value | Description |
|---|---|
| Point |
|
| MultiPoint |
|
| LineString |
|
| MultiLineString |
|
| Polygon |
|
| MultiPolygon |
|
| GeometryCollection |
|
| Feature |
|
| FeatureCollection |
|
GeoJsonPoint
A valid GeoJSON Point geometry type. Please refer to RFC
7946 for details.
| Name | Type | Description |
|---|---|---|
| bbox |
number[] (double) |
Bounding box. Projection used - EPSG:3857. Please refer to RFC 7946 for details. |
| coordinates |
number[] (double) |
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
An enum representing the match code.
| Value | Description |
|---|---|
| Good |
Good |
| Ambiguous |
Ambiguous |
| UpHierarchy |
UpHierarchy |
UsageTypeEnum
An enum representing the usage type.
| Value | Description |
|---|---|
| Display |
Display |
| Route |
Route |