---
title: "Use to send a batch of queries to the [Reverse Geocoding](/rest/api/maps/search/get-reverse-geocoding) API in a single request."
method: POST
path: "/reverseGeocode:batch"
---

# Use to send a batch of queries to the [Reverse Geocoding](/rest/api/maps/search/get-reverse-geocoding) API in a single request.

`POST /reverseGeocode:batch`

The `Get Reverse Geocoding Batch` API is an HTTP `POST` request that sends batches of up to **100** queries to [Reverse Geocoding](/rest/api/maps/search/get-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](/rest/api/maps/search/get-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`](/rest/api/maps/search/get-reverse-geocoding#geocodingresponse) - If the query completed successfully.

- `Error` - If the query failed. The response will contain a `code` and a `message` in this case.

## Query parameters

- `api-version` string, required

## Headers

- `x-ms-client-id` string
- `Accept-Language` string

## Request body

- 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`.
  - `batchItems` ReverseGeocodingBatchRequestItem[] — The reverse-geocoding queries to process in this batch. Each entry is one independent reverse-geocoding request; the service returns one corresponding entry in `GeocodingBatchResponse.batchItems` per query, in the same order.
    - `optionalId` string — An optional caller-supplied identifier echoed back on the matching response entry as `GeocodingBatchResponseItem.optionalId`. Useful for correlating responses to requests by a stable application-side identifier rather than relying on array position alone.
    - `coordinates` number[] — The location to reverse-geocode, encoded as `[longitude, latitude]` in WGS 84 order. For example, `[-122.138681, 47.630358]` for a point in Redmond, Washington.
    - `resultTypes` ResultTypeEnum[] — Restricts the response to specific kinds of locations. When omitted, all entity types are eligible. See `ResultTypeEnum` for the value list and the most-specific-wins selection behavior when entities of multiple types match.
    - `view` string — An [ISO 3166-1 Alpha-2 region/country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) identifying the region whose geopolitical view should be applied to disputed borders and labels in the response. See [Supported Views](https://aka.ms/AzureMapsLocalizationViews) for the available values.

## Response `200`

The request has succeeded.

- 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.
  - `summary` 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`.
    - `successfulRequests` integer — The number of queries in the batch that were processed successfully — those whose response entry in `GeocodingBatchResponse.batchItems` carries `features` rather than `error`.
    - `totalRequests` integer — The total number of queries submitted in the batch. Subtract `successfulRequests` to derive the number of queries that failed.
  - `batchItems` GeocodingBatchResponseItem[] — The per-query results of the batch. Each entry corresponds positionally to the request entry at the same array index in `GeocodingBatchRequestBody.batchItems`. Entries with `error` populated represent queries that failed; entries with `features` populated represent queries that succeeded.
    - `optionalId` string — The caller-supplied identifier echoed back from the corresponding `GeocodingBatchRequestItem.optionalId`. Populated only when the request entry supplied one. Useful for application-side correlation when array position is not sufficient.
    - `type` 'FeatureCollection' — 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](https://www.rfc-editor.org/rfc/rfc7946). `Get Polygon` is the one exception: its response root is a `GeoJSON Feature`, see `FeatureTypeEnum`.
    - `features` FeaturesItem[] — The array of `GeoJSON Feature` objects geocoded for this batch entry's query. Each `Feature` represents a single geocoded location with details exposed via `properties` and its primary coordinate via `geometry`. Populated only when the entry succeeded.
      - `type` 'Feature' — 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](https://www.rfc-editor.org/rfc/rfc7946).
      - `id` string — An optional service-assigned identifier for the feature, when one is available.
      - `properties` 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.
        - `type` string — The entity type that the geocoded location resolved to. One of: `Address`, `RoadBlock`, `RoadIntersection`, `Neighborhood`, `PopulatedPlace`, `Postcode1`, `AdminDivision1`, `AdminDivision2`, or `CountryRegion`.
        - `confidence` 'High' | 'Medium' | 'Low' — 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.
        - `matchCodes` MatchCodesEnum[] — How the geocoding service produced this result relative to the query: a direct match at the requested specificity (`Good`), one of several candidates (`Ambiguous`), or a fallback to a less precise level of the geographic hierarchy (`UpHierarchy`). Multiple values may be present. For example, an `Ambiguous` plus `UpHierarchy` pairing indicates that the service could not match the requested specificity and found multiple matches at a coarser level. See `MatchCodesEnum` for per-value descriptions; combine with `confidence` for a complete picture of match quality.
        - `address` 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.
          - `addressLine` string — The first line of the address, typically the street name and number. For example, `"15127 NE 24th St"`.
          - `locality` string — The locality the address falls within: usually a city, town, or village. For example: `"Redmond"`.
          - `neighborhood` string — The named neighborhood within the locality, when one is identified.
          - `adminDistricts` AddressAdminDistrictsItem[] — The administrative subdivisions that contain the address, ordered from coarsest to finest. The first entry is typically the first-order subdivision (such as a U.S. state or a Canadian province); subsequent entries cover finer divisions where the country, dependency, or region defines them (such as a county at index 1).
            - `name` string — The full name of the subdivision. For example, `"Washington"` for a U.S. state, or `"King County"` for a county.
            - `shortName` string — The short or abbreviated form of the subdivision name, when one is defined. For example, `"WA"` for a U.S. state. Finer subdivisions often have no distinct short form, in which case `shortName` repeats `name` (such as `"King County"`).
          - `postalCode` string — The postal code for the address, when one is defined. Example: `"98052"`.
          - `countryRegion` 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.
            - `ISO` string — The ISO 3166-1 Alpha-2 country code for the country or region. For example, `"US"` for the United States, or `"GB"` for the United Kingdom.
            - `name` string — The display name of the country or region. For example, `"United States"`.
          - `formattedAddress` string — The full address rendered as a single human-readable string, with the components joined according to the conventions of the address's country or region. Example: `"15127 NE 24th St, Redmond, WA 98052"`.
          - `streetName` string — The street name component of the address, when the resolved entity is a street-level address. Example: `"NE 24th St"`.
          - `streetNumber` string — The house or building number on the street, when the resolved entity is a street-level address. Example: `"15127"`.
          - `intersection` 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.
            - `baseStreet` string — The primary street of the intersection — typically the street the address number references.
            - `secondaryStreet1` string — The first cross street that meets `baseStreet` at the intersection.
            - `secondaryStreet2` string — The second cross street at the intersection, when one is present. Populated only for intersections of three or more streets.
            - `intersectionType` string — A short label describing the form of the intersection. For example, distinguishing an at-grade crossroads from a grade-separated crossing such as a bridge or overpass.
            - `displayName` string — A human-readable name for the intersection that combines the cross streets, such as `"5th Avenue & Main Street"`.
        - `geocodePoints` GeocodePointsItem[] — One or more geocode points for the location, each marked with how it was derived (`calculationMethod`) and what it is best suited for (`usageTypes`). For example, `Display` for visual placement on a map, or `Route` for use as a navigation destination.
          - `geometry` GeoJsonPoint — A valid `GeoJSON` geometry object. The type must be one of the seven valid GeoJSON geometry types - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon and GeometryCollection. Please refer to [RFC 7946](https://tools.ietf.org/html/rfc7946#section-3.1) for details.
            - `type` 'Point' | 'MultiPoint' | 'LineString' | 'MultiLineString' | 'Polygon' | 'MultiPolygon' | 'GeometryCollection' | 'Feature' | 'FeatureCollection', required — Specifies the `GeoJSON` type. Must be one of the nine valid GeoJSON object types - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature and FeatureCollection.
            - `bbox` number[] — Bounding box. Projection used - EPSG:3857. Please refer to [RFC 7946](https://datatracker.ietf.org/doc/html/rfc7946#section-5) for details.
          - `calculationMethod` 'Interpolation' | 'InterpolationOffset' | 'Parcel' | 'Rooftop' — The method that was used to compute the geocode point.
          - `usageTypes` UsageTypeEnum[] — What the geocode point is best suited for — `Display` for visual placement on a map, or `Route` as a routing destination. A point may carry both. See `UsageTypeEnum` for the per-value details, including how each is positioned for features with non-trivial extent.
      - `geometry` GeoJsonPoint, required — A valid `GeoJSON` geometry object. The type must be one of the seven valid GeoJSON geometry types - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon and GeometryCollection. Please refer to [RFC 7946](https://tools.ietf.org/html/rfc7946#section-3.1) for details.
        - `type` 'Point' | 'MultiPoint' | 'LineString' | 'MultiLineString' | 'Polygon' | 'MultiPolygon' | 'GeometryCollection' | 'Feature' | 'FeatureCollection', required — Specifies the `GeoJSON` type. Must be one of the nine valid GeoJSON object types - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature and FeatureCollection.
        - `bbox` number[] — Bounding box. Projection used - EPSG:3857. Please refer to [RFC 7946](https://datatracker.ietf.org/doc/html/rfc7946#section-5) for details.
      - `bbox` number[] — The smallest axis-aligned rectangle that contains the feature's geometry, in WGS 84 longitude/latitude order. Encoded as `[westLon, southLat, eastLon, northLat]` per [RFC 7946, Section 5](https://datatracker.ietf.org/doc/html/rfc7946#section-5).
    - `nextLink` string — Contains the URL to fetch the next page of results if the response is paginated. This is useful when the response is too large to be returned in a single call, allowing users to navigate through multiple pages of results.
    - `error` ErrorDetail — The error detail.
      - `code` string — The error code.
      - `message` string — The error message.
      - `target` string — The error target.
      - `details` ErrorDetail[] — The error details.
      - `additionalInfo` ErrorAdditionalInfo[] — The error additional info.
        - `type` string — The additional info type.
        - `info` object — The additional info.
  - `nextLink` string — Contains the URL to fetch the next page of results if the response is paginated. This is useful when the response is too large to be returned in a single call, allowing users to navigate through multiple pages of results.

## Other responses

- `default` — An unexpected error response.

## Changes

- **2026-07-13** (1.0) `adc95bd8c78a` — 1 info
  - added the new optional `header` request parameter `x-ms-client-id`
- **2026-07-13** (1.0) `0e0c2063abbc` — 1 breaking
  - api path removed without deprecation
- **2026-07-13** (1.0) `4989537e51e6` — 1 info
  - endpoint added
- **2025-10-15** (1.0) `69718fe8c37a` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/azure/apis/maps-search/changes/reverseGeocode:batch/post.md)

---

[API](https://skmtc.dev/azure/apis/maps-search.md) · [All operations](https://skmtc.dev/azure/apis/maps-search/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/azure/maps-search/revisions/adc95bd8c78a/schema)