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=2023-06-01

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 https://atlas.microsoft.com/geocode:batch?api-version=2023-06-01

URI Parameters

Name In Required Type Description
api-version
query True

string

Version number of Azure Maps API.

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. To use Azure AD security in Azure Maps see the following articles for guidance.

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 list of queries to process.

Responses

Name Type Description
200 OK

GeocodingBatchResponse

OK

Other Status Codes

ErrorResponse

An unexpected error occurred.

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

subscription-key

This is a shared key that is provisioned when creating an Azure Maps resource through the Azure management plane via Azure portal, PowerShell, CLI, Azure SDKs, or REST APIs.

With this key, any application is authorized to access all REST APIs. In other words, these can currently be treated as master keys to the account which they are issued for.

For publicly exposed applications, our recommendation is to use server-to-server access of Azure Maps REST APIs where this 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

POST https://atlas.microsoft.com/geocode:batch?api-version=2023-06-01

{
  "batchItems": [
    {
      "addressLine": "One, Microsoft Way, Redmond, WA 98052",
      "top": 2,
      "optionalId": "4C3681A6C8AA4AC3441412763A2A25C81444DC8B"
    },
    {
      "addressLine": "Pike Pl",
      "adminDistrict": "WA",
      "locality": "Seattle",
      "top": 3
    }
  ]
}

Sample response

{
  "summary": {
    "successfulRequests": 1,
    "totalRequests": 2
  },
  "batchItems": [
    {
      "type": "FeatureCollection",
      "features": [
        {
          "type": "Feature",
          "properties": {
            "type": "Address",
            "confidence": "High",
            "matchCodes": [
              "Good"
            ],
            "address": {
              "locality": "Redmond",
              "adminDistricts": [
                {
                  "shortName": "WA"
                },
                {
                  "shortName": "King"
                }
              ],
              "countryRegion": {
                "ISO": "US",
                "name": "United States"
              },
              "postalCode": "98052",
              "formattedAddress": "1 Microsoft Way, Redmond, WA 98052",
              "addressLine": "1 Microsoft Way"
            },
            "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
          ]
        }
      ]
    },
    {
      "error": {
        "code": "Conflicting Parameters",
        "message": "When 'query' is present, only the following parameters are valid: 'bbox, location, view, top'. 'addressLine' was passed"
      }
    }
  ]
}

Definitions

Name Description
Address

The address of the result

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.

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 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.

CountryRegion
ErrorAdditionalInfo

The resource management error additional info.

ErrorDetail

The error detail.

ErrorResponse

Error response

FeatureCollectionEnum

The type of a FeatureCollection object must be FeatureCollection.

FeaturesItem
FeatureTypeEnum

The type of a feature must be Feature.

GeocodePoints

A collection of geocode points that differ in how they were calculated and their suggested use.

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.

GeocodingBatchRequestItem

Batch Query object

GeocodingBatchResponse

This object is returned from a successful Geocoding Batch service call.

GeocodingBatchResponseItem
GeoJsonPoint

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

Intersection

The address of the result.

MatchCodesEnum

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.

Properties
Summary

Summary for the batch request

UsageTypeEnum

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.

Address

The address of the result

Name Type Description
addressLine

string

AddressLine that includes Street Name and Number

adminDistricts

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

CountryRegion

formattedAddress

string

Formatted Address property

intersection

Intersection

The address of the result.

locality

string

locality property

neighborhood

string

neighborhood property

postalCode

string

Postal Code property

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.

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

CalculationMethodEnum

The method that was used to compute the geocode point.

Name Type Description
Interpolation

string

The geocode point was matched to a point on a road using interpolation.

InterpolationOffset

string

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

string

The geocode point was matched to the center of a parcel.

Rooftop

string

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.

Name Type Description
High

string

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 appropriately. For example, a location query for "Paris" returns "Paris, France" and "Paris, TX" both 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.

Low

string

Medium

string

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 Medium and the match code is set to UpHierarchy to specify that it 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 "148th Ave SE" and "148th Ave NE" both 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.

CountryRegion

Name Type Description
ISO

string

ISO of country/region

name

string

name of country/region

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

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.

ErrorResponse

Error response

Name Type Description
error

ErrorDetail

The error object.

FeatureCollectionEnum

The type of a FeatureCollection object must be FeatureCollection.

Name Type Description
FeatureCollection

string

FeaturesItem

Name Type Description
bbox

number[]

Bounding box. Projection used - EPSG:3857. Please refer to RFC 7946 for details.

geometry

GeoJsonPoint

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

id

string

ID for feature returned

properties

Properties

type

FeatureTypeEnum

The type of a feature must be Feature.

FeatureTypeEnum

The type of a feature must be Feature.

Name Type Description
Feature

string

GeocodePoints

A collection of geocode points that differ in how they were calculated and their suggested use.

Name Type Description
calculationMethod

CalculationMethodEnum

The method that was used to compute the geocode point.

geometry

GeoJsonPoint

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

usageTypes

UsageTypeEnum[]

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.

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

GeocodingBatchRequestItem[]

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.

If query is given, should not use this parameter.

adminDistrict

string

The country subdivision portion of an address, such as WA.

If query is given, should not use this parameter.

adminDistrict2

string

The county for the structured address, such as King.

If query is given, should not use this parameter.

adminDistrict3

string

The named area for the structured address.

If query is given, should not use this parameter.

bbox

number[]

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[]

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./

If query is given, should not use this parameter.

locality

string

The locality portion of an address, such as Seattle.

If query is given, should not use this parameter.

optionalId

string

id of the request which would show in corresponding batchItem

postalCode

string

The postal code portion of an address.

If query is given, should not use this parameter.

query

string

A string that contains information about a location, such as an address or landmark name.

top

integer

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

GeocodingBatchResponseItem[]

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

Summary for the batch request

GeocodingBatchResponseItem

Name Type Description
error

ErrorDetail

The error detail.

features

FeaturesItem[]

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

FeatureCollectionEnum

The type of a FeatureCollection object must be FeatureCollection.

GeoJsonPoint

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

Name Type Description
bbox

number[]

Bounding box. Projection used - EPSG:3857. Please refer to RFC 7946 for details.

coordinates

number[]

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

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

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.

Name Type Description
Ambiguous

string

Good

string

UpHierarchy

string

Properties

Name Type Description
address

Address

The address of the result

confidence

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.

geocodePoints

GeocodePoints[]

A collection of geocode points that differ in how they were calculated and their suggested use.

matchCodes

MatchCodesEnum[]

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.

type

string

One of:

  • Address
  • RoadBlock
  • RoadIntersection
  • Neighborhood
  • PopulatedPlace
  • Postcode1
  • AdminDivision1
  • AdminDivision2
  • CountryRegion

Summary

Summary for the batch request

Name Type Description
successfulRequests

integer

Number of successful requests in the batch

totalRequests

integer

Total number of requests in the batch

UsageTypeEnum

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.

Name Type Description
Display

string

Route

string