Search - Get Geocoding Batch

Service:: Maps

API Version:: 2026-01-01

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

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

URI Parameters

Name	In	Required	Type	Description
endpoint	path	True	string (uri)	The Azure Maps service hostname. Use `https://atlas.microsoft.com` for the Azure public cloud. To target a specific Azure Maps geography or a sovereign cloud, see Azure Maps geographic scope.
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.

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	GeocodingBatchRequestItem[]	The geocoding queries to process in this batch. Each entry is one independent forward-geocoding request; the service returns one corresponding entry in `GeocodingBatchResponse.batchItems` per query, in the same order.

Responses

Name	Type	Description
200 OK	GeocodingBatchResponse	The request has succeeded.
Other Status Codes	Azure.Core.Foundations.ErrorResponse	An unexpected error response. Headers x-ms-error-code: string

Name

Type

Description

200 OK

GeocodingBatchResponse

The request has succeeded.

Other Status Codes

Azure.Core.Foundations.ErrorResponse

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.

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

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 Geocoding Batch API call containing 2 Geocoding queries

Sample request

HTTP

POST https://atlas.microsoft.com/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

Status code:: 200

{
  "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 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.
GeocodingBatchRequestBody	The request body for the `Get Geocoding Batch` operation. Carries one or more individual geocoding queries — between 1 and 100, inclusive — that the service processes as a single call and returns as a parallel `batchItems` array on `GeocodingBatchResponse`.
GeocodingBatchRequestItem	One geocoding query inside a `GeocodingBatchRequestBody.batchItems` array. Each item is an independent forward-geocoding request equivalent to a single call to `Get Geocoding`, expressed as fields rather than as URL query parameters. The location can be supplied either as a free-form `query` string or as the structured fields below (`addressLine`, `locality`, `countryRegion`, the `adminDistrict` levels, `postalCode`); these two input modes are mutually exclusive — when `query` is set, the structured fields are ignored.
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.
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.

Address

Object

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.

Name	Type	Description
addressLine	string	The first line of the address, typically the street name and number. For example, `"15127 NE 24th St"`.
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).
countryRegion	AddressCountryRegion	The country or region that contains the address, with its display name and ISO 3166-1 Alpha-2 country code.
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"`.
intersection	Intersection	The intersecting-street details for the address, populated when the resolved entity is a `RoadIntersection` (such as the corner of two named streets).
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.
postalCode	string	The postal code for the address, when one is defined. Example: `"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"`.

AddressAdminDistrictsItem

Object

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.

Name	Type	Description
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"`).

AddressCountryRegion

Object

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.

Name	Type	Description
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"`.

Azure.Core.Foundations.Error

Object

The error object.

Name	Type	Description
code	string	One of a server-defined set of error codes.
details	Azure.Core.Foundations.Error[]	An array of details about specific errors that led to this reported error.
innererror	Azure.Core.Foundations.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

Object

A response containing error details.

Name	Type	Description
error	Azure.Core.Foundations.Error	The error object.

Azure.Core.Foundations.InnerError

Object

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	Azure.Core.Foundations.InnerError	Inner error.

CalculationMethodEnum

Enumeration

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

Enumeration

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.

Value Description

High

Value	Description
High	If the confidence is set to `High`, one or more strong matches were found. Multiple `High` confidence matches are sorted in ranked order by importance when applicable. For example, landmarks have importance but addresses do not. If a request includes a location or a view, then the ranking may change accordingly. For example, a location query for "Paris" returns both "Paris, France" and "Paris, TX" with `High` confidence. "Paris, France" is always ranked first due to importance, unless a user location indicates that the user is in or very close to Paris, TX, or the map view indicates that the user is searching in that area.
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 confidence that the postal code matches the data, the confidence is set to `Medium` and the match code is set to `UpHierarchy` to indicate that the service could not match all of the information and had to search up-hierarchy. 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 `Medium`. For example, a location query for "148th Ave, Bellevue" may return both "148th Ave SE" and "148th Ave NE" with `Medium` confidence. 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 `Medium`. For example, if an address is provided but a match is not found for the house number, the geocode result with a `RoadBlock` entity type may be returned.
Low	Low confidence in the match.

If the confidence is set to High, one or more strong matches were found. Multiple High confidence matches are sorted in ranked order by importance when applicable. For example, landmarks have importance but addresses do not.

If a request includes a location or a view, then the ranking may change accordingly. For example, a location query for "Paris" returns both "Paris, France" and "Paris, TX" with High confidence. "Paris, France" is always ranked first due to importance, unless a user location indicates that the user is in or very close to Paris, TX, or the map view indicates that the user is searching in that area.

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 confidence that the postal code matches the data, the confidence is set to Medium and the match code is set to UpHierarchy to indicate that the service could not match all of the information and had to search up-hierarchy.

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 Medium. For example, a location query for "148th Ave, Bellevue" may return both "148th Ave SE" and "148th Ave NE" with Medium confidence.

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 Medium. For example, if an address is provided but a match is not found for the house number, the geocode result with a RoadBlock entity type may be returned.

Low

Low confidence in the match.

ErrorAdditionalInfo

Object

The resource management error additional info.

Name	Type	Description
info	object	The additional info.
type	string	The additional info type.

ErrorDetail

Object

The error detail.

Name	Type	Description
additionalInfo	ErrorAdditionalInfo[]	The error additional info.
code	string	The error code.
details	ErrorDetail[]	The error details.
message	string	The error message.
target	string	The error target.

FeatureCollectionEnum

Enumeration

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.

Value	Description
FeatureCollection	The `GeoJSON FeatureCollection` object type. Appears as the root of every successful geocoding, reverse geocoding, and autocomplete response body. `Get Polygon` uses a `Feature` root instead.

FeaturesItem

Object

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.

Name	Type	Description
bbox	number[] (double)	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.
geometry	GeoJsonPoint	The primary `GeoJSON Point` representing the geocoded location, with coordinates in WGS 84 longitude/latitude order.
id	string	An optional service-assigned identifier for the feature, when one is available.
properties	FeaturesItemProperties	Structured data about the geocoded location, including its entity type, match-quality indicators, address components, and one or more geocode points.
type	FeatureTypeEnum	The `GeoJSON` object type. Always `Feature`, as defined in RFC 7946.

FeaturesItemProperties

Object

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.

Name	Type	Description
address	Address	The address of the geocoded location, parsed into structured fields such as locality, postal code, country/region, and (when available) street name and number.
confidence	ConfidenceEnum	How strongly the geocoded location matches the request. Use together with `matchCodes` for a complete picture of match quality. See `ConfidenceEnum` for the value list and the factors that influence the rating.
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.
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.
type	string	The entity type that the geocoded location resolved to. One of: `Address`, `RoadBlock`, `RoadIntersection`, `Neighborhood`, `PopulatedPlace`, `Postcode1`, `AdminDivision1`, `AdminDivision2`, or `CountryRegion`.

FeatureTypeEnum

Enumeration

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.

Value	Description
Feature	The `GeoJSON Feature` object type. Appears on every Feature inside a `FeatureCollection` response, and at the root of the `Get Polygon` response.

GeocodePointsItem

Object

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.

Name	Type	Description
calculationMethod	CalculationMethodEnum	How the point was computed. For example, snapped to the rooftop of a building or interpolated along a road centerline. See `CalculationMethodEnum` for the value list.
geometry	GeoJsonPoint	The coordinate of this geocode point as a `GeoJSON Point`, with values in WGS 84 longitude/latitude order.
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.

GeocodingBatchRequestBody

Object

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

Name	Type	Description
batchItems	GeocodingBatchRequestItem[]	The geocoding queries to process in this batch. Each entry is one independent forward-geocoding request; the service returns one corresponding entry in `GeocodingBatchResponse.batchItems` per query, in the same order.

GeocodingBatchRequestItem

Object

One geocoding query inside a GeocodingBatchRequestBody.batchItems array. Each item is an independent forward-geocoding request equivalent to a single call to Get Geocoding, expressed as fields rather than as URL query parameters. The location can be supplied either as a free-form query string or as the structured fields below (addressLine, locality, countryRegion, the adminDistrict levels, postalCode); these two input modes are mutually exclusive — when query is set, the structured fields are ignored.

Name	Type	Default value	Description
addressLine	string		The street line of the address, typically the street name and number, or any other official street-level address. Ignored when `query` is set.
adminDistrict	string		The first-order administrative subdivision (such as a state or province) supplied as a name or short code. For example, `"WA"` for Washington. Ignored when `query` is set.
adminDistrict2	string		The second-order administrative subdivision (such as a county). For example, `"King"` for King County. Ignored when `query` is set.
adminDistrict3	string		The third-order administrative subdivision (such as a district, parish, or municipality), where the country, dependency, or region defines one. Ignored when `query` is set.
bbox	number[] (double)		A bounding box that scopes the search to a rectangular geographic area. Encoded as `[westLon, southLat, eastLon, northLat]` in WGS 84 longitude/latitude order, with each side ranging from approximately `0.00001` degrees (~1 meter) up to the full global extent (`-180, -90` to `180, 90`).
coordinates	number[] (double)		A point on the earth, encoded as `[longitude, latitude]` in WGS 84 order, used to bias results toward the user's location. When supplied, results closer to this point are typically more relevant to the user.
countryRegion	string		An ISO 3166-1 Alpha-2 region/country code that scopes the search to a single country or region. For example, `"FR"` for France. Ignored when `query` is set.
locality	string		The locality (city, town, or village) component of the address. For example, `"Seattle"`. Ignored when `query` is set.
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.
postalCode	string		The postal code component of the address. Ignored when `query` is set.
query	string		A free-form string describing the location to geocode, typically an address or landmark name. When set, the structured location fields below (`addressLine`, `locality`, `countryRegion`, the `adminDistrict` levels, `postalCode`) are ignored.
top	integer (int32) minimum: 1 maximum: 20	5	The maximum number of geocoded results returned for this query. Defaults to 5; minimum 1, maximum 20.
view	string	auto	An ISO 3166-1 Alpha-2 region/country code identifying the region whose geopolitical view should be applied to disputed borders and labels in the response. Defaults to `"auto"`, which selects the view based on the request origin. See Supported Views for the available values.

GeocodingBatchResponse

Object

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.

Name	Type	Description
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.
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.
summary	GeocodingBatchResponseSummary	Aggregate counts for the batch as a whole, the total submitted queries and how many of them completed successfully.

GeocodingBatchResponseItem

Object

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.

Name	Type	Description
error	ErrorDetail	Diagnostic information for a query that failed inside the batch, the per-entry error path complementing the success path on `features`. Populated only when the entry failed; see `ErrorDetail` for the per-error shape.
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.
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.
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	FeatureCollectionEnum	The `GeoJSON` object type of this entry's success body. Always `FeatureCollection`, as defined in RFC 7946. Populated only when the entry succeeded.

GeocodingBatchResponseSummary

Object

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.

Name	Type	Description
successfulRequests	integer (int32)	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 (int32)	The total number of queries submitted in the batch. Subtract `successfulRequests` to derive the number of queries that failed.

GeoJsonObjectType

Enumeration

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	`GeoJSON Point` geometry.
MultiPoint	`GeoJSON MultiPoint` geometry.
LineString	`GeoJSON LineString` geometry.
MultiLineString	`GeoJSON MultiLineString` geometry.
Polygon	`GeoJSON Polygon` geometry.
MultiPolygon	`GeoJSON MultiPolygon` geometry.
GeometryCollection	`GeoJSON GeometryCollection` geometry.
Feature	`GeoJSON Feature` object.
FeatureCollection	`GeoJSON FeatureCollection` object.

GeoJsonPoint

Object

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 `Position` is an array of numbers with two or more elements. The first two elements are longitude and latitude, precisely in that order. Altitude/Elevation is an optional third element. Please refer to RFC 7946 for details.
type	string: Point	Specifies the `GeoJSON` type. Must be one of the nine valid GeoJSON object types - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature and FeatureCollection.

Intersection

Object

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.

Name	Type	Description
baseStreet	string	The primary street of the intersection — typically the street the address number references.
displayName	string	A human-readable name for the intersection that combines the cross streets, such as `"5th Avenue & Main Street"`.
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.
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.

MatchCodesEnum

Enumeration

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.

Value	Description
Good	The geocoding service produced this candidate without broadening the query: the result matches the query at the specificity that was requested.
Ambiguous	The location is one of a set of possible matches. For example, when querying 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.

UsageTypeEnum

Enumeration

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.

Value	Description
Display	The geocode point is suitable for displaying the location on a map. For a feature with non-trivial extent (such as a park or building), the `Display` point is typically near the visual center of the feature.
Route	The geocode point is suitable as the destination of a route. For a feature with non-trivial extent (such as a park or building), the `Route` point is typically positioned at a vehicle-accessible entrance rather than at the visual center.