--- 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. >[!Important] >By using this feature, you agree to the preview legal terms. For more information, see [Preview Supplemental Terms](https://azure.microsoft.com/en-us/support/legal/preview-supplemental-terms/). ### 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](/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 - `Accept-Language` string ## Parameters - `../../../Common/stable/2023-06-01/common.json#/components/parameters/ClientId` — unresolved $ref ## Request body - 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. - `batchItems` ReverseGeocodingBatchRequestItem[] — The list of queries to process. - `optionalId` string — id of the request which would show in corresponding batchItem - `coordinates` number[] — The coordinates of the location that you want to reverse geocode. Example: [lon,lat] - `resultTypes` string[] — 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. - `view` string — A string that specifies an [ISO 3166-1 Alpha-2 region/country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). This will alter Geopolitical disputed borders and labels to align with the specified user region. ## Response `200` OK - GeocodingBatchResponse — This object is returned from a successful Geocoding Batch service call. - `summary` object — Summary for the batch request - `successfulRequests` integer — Number of successful requests in the batch - `totalRequests` integer — Total number of requests in the batch - `batchItems` GeocodingBatchResponseItem[] — Array containing the batch results. - `optionalId` string — id of the batchItem which would be the same as the id in the request - `type` 'FeatureCollection' — Specifies the `GeoJSON` type. The only supported object type is `FeatureCollection`. For more information, see [RFC 7946](https://www.rfc-editor.org/rfc/rfc7946). - `features` FeaturesItem[] - `type` 'Feature' — The type of a feature must be Feature. - `id` string — ID for feature returned - `properties` object - `type` string — One of: * Address * RoadBlock * RoadIntersection * Neighborhood * PopulatedPlace * Postcode1 * AdminDivision1 * AdminDivision2 * CountryRegion - `confidence` 'High' | 'Medium' | 'Low' — 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. - `matchCodes` string[] — 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. - `address` Address — The address of the result - `addressLine` string — AddressLine that includes street name and number - `locality` string — Locality property - `neighborhood` string — Neighborhood property - `adminDistricts` object[] — 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` 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 - `postalCode` string — Postal code property - `countryRegion` object — Country or region with its name and ISO code. - `ISO` string — ISO of country/region - `name` string — name of country/region - `formattedAddress` string — Formatted address property - `streetName` string — The name of the street from formattedAddress - `streetNumber` string — The number in the street, if available, from formattedAddress - `intersection` Intersection — The address of the result. - `baseStreet` string — Primary street for the location. - `secondaryStreet1` string — The first intersecting street. - `secondaryStreet2` string — If any, the second intersecting street. - `intersectionType` string — Type of intersection. - `displayName` string — Complete name of the intersection. - `geocodePoints` object[] — A collection of geocode points that differ in how they were calculated and their suggested use. - `geometry` GeoJsonPoint — unresolved $ref - `calculationMethod` 'Interpolation' | 'InterpolationOffset' | 'Parcel' | 'Rooftop' — The method that was used to compute the geocode point. - `usageTypes` UsageType[] — 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. - `geometry` GeoJsonPoint, required — unresolved $ref - `bbox` BoundingBox — unresolved $ref - `nextLink` string — The is the link to the next page of the features returned. If it's the last page, no this field. - `error` ErrorDetail — unresolved $ref - `nextLink` string — The is the link to the next page of the features returned. If it's the last page, no this field. ## Other responses - `default` — unresolved $ref ## Changes - **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/4464595409b4/schema)