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={api-version}

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 a code and a message in this case.

POST {endpoint}/reverseGeocode:batch?api-version=2026-01-01

URI Parameters

Request Header

Request Body

Responses

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.

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

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.

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.

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.

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

POST https://atlas.microsoft.com/reverseGeocode:batch?api-version=2026-01-01

{
  "batchItems": [
    {
      "coordinates": [
        -122.138681,
        47.630358
      ],
      "resultTypes": [
        "Address",
        "PopulatedPlace"
      ],
      "optionalId": "4C3681A6C8AA4AC3441412763A2A25C81444DC8B"
    },
    {
      "coordinates": [
        47.630358,
        -122.138681
      ],
      "optionalId": "6M9W39P12SNHGAIZ4JQ7F57NWJLV2BRYEQRD7OH7"
    }
  ]
}

{
  "summary": {
    "successfulRequests": 1,
    "totalRequests": 2
  },
  "batchItems": [
    {
      "type": "FeatureCollection",
      "features": [
        {
          "type": "Feature",
          "properties": {
            "type": "Address",
            "confidence": "Medium",
            "matchCodes": [
              "Good"
            ],
            "address": {
              "locality": "Redmond",
              "adminDistricts": [
                {
                  "name": "Washington",
                  "shortName": "WA"
                },
                {
                  "name": "King County",
                  "shortName": "King Co."
                }
              ],
              "countryRegion": {
                "ISO": "US",
                "name": "United States"
              },
              "postalCode": "98052",
              "formattedAddress": "2267 152nd Ave NE, Redmond, Washington 98052, United States",
              "streetName": "152nd Ave NE",
              "streetNumber": "2267",
              "addressLine": "2267 152nd Ave NE"
            },
            "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": "4C3681A6C8AA4AC3441412763A2A25C81444DC8B"
    },
    {
      "error": {
        "code": "Bad Request",
        "message": "The provided coordinates (-122.138681,47.630358) in coordinates field are invalid or out of range"
      },
      "optionalId": "6M9W39P12SNHGAIZ4JQ7F57NWJLV2BRYEQRD7OH7"
    }
  ]
}

Definitions

Address

The address of a geocoded or autocomplete-suggested location, parsed into structured fields. Sparseness is normal: only the fields that the resolved entity supplies are populated. For example, streetName and streetNumber appear only for street-level addresses, and intersection appears only for road-intersection results.

AddressAdminDistrictsItem

An administrative subdivision that contains an address. For example, a state, province, or county. Returned as one entry in the parent Address.adminDistricts array, where entries are ordered from coarsest to finest.

AddressCountryRegion

The country or region that contains the address, identified by its display name and ISO 3166-1 Alpha-2 country code. Either field may be omitted in a given response.

Azure.Core.Foundations.Error

The error object.

Azure.Core.Foundations.ErrorResponse

A response containing error details.

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.

CalculationMethodEnum

The method that was used to compute the geocode point.

ConfidenceEnum

The level of confidence that the geocoded location result is a match. Use this value together with the match codes to obtain 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.

ErrorAdditionalInfo

The resource management error additional info.

ErrorDetail

The error detail.

FeatureCollectionEnum

The GeoJSON object type used at the root of successful responses from the forward geocoding, reverse geocoding, and autocomplete operations (including their batch variants). The only value is FeatureCollection, as defined in RFC 7946. Get Polygon is the one exception: its response root is a GeoJSON Feature, see FeatureTypeEnum.

FeaturesItem

A single entry in the features array of a GeocodingResponse, conforming to the GeoJSON Feature object shape. Represents one geocoded location: structured data on properties, a representative coordinate on geometry, and an optional bounding box on bbox.

FeaturesItemProperties

The properties payload of a feature in a GeocodingResponse. Carries the entity type and match-quality indicators for the geocoded location, its parsed address components, and one or more geocode points that pin the location to specific coordinates.

FeatureTypeEnum

The GeoJSON object type for Feature objects. Tags each entry inside the features array of a FeatureCollection response (geocoding, reverse geocoding, autocomplete) and appears at the root of the Get Polygon response. The only value is Feature, as defined in RFC 7946.

GeocodePointsItem

One geocode point for a location: a coordinate plus metadata describing how the point was computed (calculationMethod) and what it is best suited for (usageTypes). A single feature typically returns separate Display and Route points so callers can pick the one that fits the task.

GeocodingBatchResponse

The successful response body returned by Get Geocoding Batch. Carries a summary of how many of the submitted queries succeeded plus a batchItems array containing one response entry per query in the request, in the same order as the request batchItems array.

GeocodingBatchResponseItem

A single entry inside GeocodingBatchResponse.batchItems, carrying the result of one of the queries from the corresponding GeocodingBatchRequestBody.batchItems entry. Successful queries surface their geocoded features here in the same shape as GeocodingResponse; failed queries surface diagnostic information via error instead. Exactly one of features or error is populated per entry.

GeocodingBatchResponseSummary

Carries aggregate counts for a Get Geocoding Batch response: the size of the submitted batch and how many of its queries were processed successfully. Used as the type of GeocodingBatchResponse.summary.

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.

GeoJsonPoint

A valid GeoJSON Point geometry type. Please refer to RFC 7946 for details.

Intersection

Intersection details for an address resolved as a road intersection — the corner where two or more named streets meet. Populated only when the resolved entity is a RoadIntersection; the parent Address.intersection is otherwise omitted.

MatchCodesEnum

A match-code value indicating how the geocoding service produced a particular location result. The matchCodes field on a feature is an array of these values; combine them with confidence and type to evaluate match quality.

ResultTypeEnum

An entity type returned by the Get Reverse Geocoding Batch operation. Supplied as one or more values in the per-batch-item resultTypes field to restrict the response for that item to specific kinds of locations; when the field is omitted, all entity types are eligible. When entities of more than one type match a coordinate, only the most specific is returned. Listed from most specific to least specific: Address, Neighborhood, PopulatedPlace, Postcode1, AdminDivision1, AdminDivision2, CountryRegion.

ReverseGeocodingBatchRequestBody

The request body for the Get Reverse Geocoding Batch operation. Carries one or more individual reverse-geocoding queries — between 1 and 100, inclusive — that the service processes as a single call and returns as a parallel batchItems array on GeocodingBatchResponse.

ReverseGeocodingBatchRequestItem

One reverse-geocoding query inside a ReverseGeocodingBatchRequestBody.batchItems array. Each item is an independent reverse-geocoding request equivalent to a single call to Get Reverse Geocoding, expressed as fields rather than as URL query parameters. Specify the location to reverse-geocode via coordinates; optionally narrow the entity types via resultTypes and the geopolitical view via view.

UsageTypeEnum

The intended use for a geocode point. A geocode point returned by the service carries one or more usage types that indicate how a client application should consume the point: for example, displaying the location on a map versus routing a vehicle to it.