Share via

Search - Get Geocode Autocomplete

Service:
Maps
API Version:
2025-06-01-preview

Use to get ranked list of suggested entities based on a user's location and a partial query.

Given a request with a user’s location and a partial query that serves as the prefix of a full query string (referred to as a query prefix), the Azure Maps Autocomplete API returns a list of suggested entities that the user is most likely searching for. These entities are ranked from most to least likely.

Important

By using this feature, you agree to the preview legal terms. For more information, see Preview Supplemental Terms.

GET https://atlas.microsoft.com/geocode:autocomplete?api-version=2025-06-01-preview&query={query}
With optional parameters: 
GET https://atlas.microsoft.com/geocode:autocomplete?api-version=2025-06-01-preview&query={query}&coordinates={coordinates}&bbox={bbox}&top={top}&resultTypeGroups={resultTypeGroups}&resultTypes={resultTypes}&view={view}&countryRegion={countryRegion}

URI Parameters

Name In Required Type Description
api-version
 query True

string

Version number of Azure Maps API.
query
 query True

string

Required. The user's query prefix.

Example: "1 Micro" or "Muir Woods".
bbox
 query

number[]

Required when coordinates is not provided. A rectangular area on the earth defined as a bounding box object. The sides of the rectangle are defined by longitude and latitude values. 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.

Minimum size: approximately 0.00001 degrees (~0.01 meters).

Maximum size: up to the full global extent (-180,-90 to 180,90)
coordinates
 query

number[]

Required when bbox is not provided. 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: &coordinates=lon,lat

Note: coordinates becomes a secondary signal if bbox is provided.
countryRegion
 query

string

Signal for the autocomplete result to an ISO 3166-1 Alpha-2 region/country code that is specified e.g. FR. Only results in the specified country/region will be returned.
resultTypeGroups
 query

AutocompleteResultTypeGroupsEnum[]

A comma separated list of returned entity type groups. The possible values are

  • Address
  • Place
resultTypes
 query

AutocompleteResultTypeEnum[]

A comma separated list of returned entity types. When type group is set to Address, the supported types are:

  • Address
  • RoadBlock

All other types belong to the Place type group. These may include entities such as AdminDivision1, Neighborhood, PopulatedPlace, and more. Default value is all possible entity types.
top
 query

integer (int32)

minimum: 1
maximum: 20

Maximum number of responses that will be returned. Default: 5, minimum: 1 and maximum: 20.
view
 query

string

A string that represents an ISO 3166-1 Alpha-2 region/country code. This will alter Geopolitical disputed borders and labels to align with the specified user region. By default, the View parameter is set to “Auto” even if you haven’t defined it in the request.

Please refer to Supported Views for details and to see the available Views.

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.

Responses

Name Type Description
200 OK

AutocompleteResponse

OK

Media Types: "application/geo+json"

Headers

x-ms-request-id: string
Other Status Codes

ErrorResponse

An unexpected error occurred.

Media Types: "application/geo+json"

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

Autocomplete API call to search for '1 Microsoft'
Autocomplete API call to search for '1 Microsoft Way, Redmond', filtered by roadblock resultTypes, place resultTypeGroups, and return empty result
Autocomplete API call to search for 'Muir Woods', filtered by address resultTypeGroups
Autocomplete API call to search for 'Muir Woods', filtered by park and populated place resultTypes, place resultTypeGroups
Autocomplete API call to search for 'Muir Woods', filtered by park resultTypes
Autocomplete API call to search for 'Muir Woods', filtered by place resultTypeGroups
Autocomplete API call to search for 'Muir Woods', filtered by roadblock resultTypes, address resultTypeGroups

Autocomplete API call to search for '1 Microsoft'

Sample request

GET https://atlas.microsoft.com/geocode:autocomplete?api-version=2025-06-01-preview&query=1 Microsoft&coordinates=-113.301894,49.201888

Sample response

Status code:
200 
Content-Type: application/geo+json
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": null,
      "properties": {
        "typeGroup": "Address",
        "type": "Address",
        "address": {
          "streetNumber": "1",
          "streetName": "Microsoft Way",
          "addressLine": "1 Microsoft Way",
          "locality": "Redmond",
          "adminDistricts": [
            {
              "name": "Washington"
            },
            {
              "name": "King County"
            }
          ],
          "countryRegion": {
            "ISO": "US",
            "name": "United States"
          },
          "postalCode": "98052",
          "formattedAddress": "1 Microsoft Way, Redmond, Washington 98052, United States"
        }
      }
    },
    {
      "type": "Feature",
      "geometry": null,
      "properties": {
        "typeGroup": "Place",
        "type": "LandmarkBuilding",
        "address": {
          "locality": "Bellevue",
          "adminDistricts": [
            {
              "name": "Washington"
            },
            {
              "name": "King County"
            }
          ],
          "countryRegion": {
            "ISO": "US",
            "name": "United States"
          },
          "formattedAddress": "Bellevue, Washington, United States"
        },
        "name": "Microsoft-Advanta C"
      }
    }
  ]
}

Autocomplete API call to search for '1 Microsoft Way, Redmond', filtered by roadblock resultTypes, place resultTypeGroups, and return empty result

Sample request

GET https://atlas.microsoft.com/geocode:autocomplete?api-version=2025-06-01-preview&query=1 Microsoft Way, Redmond&coordinates=-113.301894,49.201888&resultTypeGroups=Place&resultTypes=RoadBlock

Sample response

Status code:
200 
Content-Type: application/geo+json
{
  "type": "FeatureCollection",
  "features": []
}

Autocomplete API call to search for 'Muir Woods', filtered by address resultTypeGroups

Sample request

GET https://atlas.microsoft.com/geocode:autocomplete?api-version=2025-06-01-preview&query=Muir Woods&coordinates=-113.301894,49.201888&resultTypeGroups=Address

Sample response

Status code:
200 
Content-Type: application/geo+json
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": null,
      "properties": {
        "typeGroup": "Address",
        "type": "Address",
        "address": {
          "streetName": "Muir Woods Rd",
          "addressLine": " Muir Woods Rd",
          "locality": "Sausalito",
          "adminDistricts": [
            {
              "name": "California"
            },
            {
              "name": "Marin County"
            }
          ],
          "countryRegion": {
            "ISO": "US",
            "name": "United States"
          },
          "postalCode": "94965",
          "formattedAddress": "Muir Woods Rd, Sausalito, California 94965, United States"
        }
      }
    },
    {
      "type": "Feature",
      "geometry": null,
      "properties": {
        "typeGroup": "Address",
        "type": "RoadBlock",
        "address": {
          "streetName": "Muir St",
          "addressLine": " Muir St",
          "locality": "Grosse Pointe Farms",
          "adminDistricts": [
            {
              "name": "Michigan"
            },
            {
              "name": "Wayne County"
            }
          ],
          "countryRegion": {
            "ISO": "US",
            "name": "United States"
          },
          "postalCode": "48236",
          "formattedAddress": "Muir St, Grosse Pointe Farms, Michigan 48236, United States"
        }
      }
    }
  ]
}

Autocomplete API call to search for 'Muir Woods', filtered by park and populated place resultTypes, place resultTypeGroups

Sample request

GET https://atlas.microsoft.com/geocode:autocomplete?api-version=2025-06-01-preview&query=Muir Woods&coordinates=-122.581711,37.896980&resultTypeGroups=Place&resultTypes=Park,PopulatedPlace

Sample response

Status code:
200 
Content-Type: application/geo+json
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": null,
      "properties": {
        "typeGroup": "Place",
        "type": "PopulatedPlace",
        "address": {
          "locality": "Muir Woods",
          "adminDistricts": [
            {
              "name": "Georgia"
            },
            {
              "name": "Fulton County"
            }
          ],
          "countryRegion": {
            "ISO": "US",
            "name": "United States"
          },
          "postalCode": "30349",
          "formattedAddress": "Muir Woods, Georgia 30349, United States"
        }
      }
    },
    {
      "type": "Feature",
      "geometry": null,
      "properties": {
        "typeGroup": "Place",
        "type": "Park",
        "address": {
          "adminDistricts": [
            {
              "name": "California"
            },
            {
              "name": "Marin County"
            }
          ],
          "countryRegion": {
            "ISO": "US",
            "name": "United States"
          },
          "formattedAddress": "California"
        },
        "name": "Muir Woods National Park"
      }
    }
  ]
}

Autocomplete API call to search for 'Muir Woods', filtered by park resultTypes

Sample request

GET https://atlas.microsoft.com/geocode:autocomplete?api-version=2025-06-01-preview&query=Muir Woods&coordinates=-122.581711,37.896980&resultTypes=Park

Sample response

Status code:
200 
Content-Type: application/geo+json
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": null,
      "properties": {
        "typeGroup": "Place",
        "type": "Park",
        "address": {
          "adminDistricts": [
            {
              "name": "California"
            },
            {
              "name": "Marin County"
            }
          ],
          "countryRegion": {
            "ISO": "US",
            "name": "United States"
          },
          "formattedAddress": "California"
        },
        "name": "Muir Woods National Monument"
      }
    }
  ]
}

Autocomplete API call to search for 'Muir Woods', filtered by place resultTypeGroups

Sample request

GET https://atlas.microsoft.com/geocode:autocomplete?api-version=2025-06-01-preview&query=Muir Woods&coordinates=-122.581711,37.896980&resultTypeGroups=Place

Sample response

Status code:
200 
Content-Type: application/geo+json
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": null,
      "properties": {
        "typeGroup": "Place",
        "type": "Forest",
        "address": {
          "adminDistricts": [
            {
              "name": "Wisconsin"
            },
            {
              "name": "Dane County"
            }
          ],
          "countryRegion": {
            "ISO": "US",
            "name": "United States"
          },
          "formattedAddress": "Wisconsin"
        },
        "name": "Muir Woods"
      }
    },
    {
      "type": "Feature",
      "geometry": null,
      "properties": {
        "typeGroup": "Place",
        "type": "PopulatedPlace",
        "address": {
          "locality": "Muir Woods",
          "adminDistricts": [
            {
              "name": "Georgia"
            },
            {
              "name": "Fulton County"
            }
          ],
          "countryRegion": {
            "ISO": "US",
            "name": "United States"
          },
          "postalCode": "30349",
          "formattedAddress": "Muir Woods, Georgia 30349, United States"
        }
      }
    },
    {
      "type": "Feature",
      "geometry": null,
      "properties": {
        "typeGroup": "Place",
        "type": "Park",
        "address": {
          "adminDistricts": [
            {
              "name": "California"
            },
            {
              "name": "Marin County"
            }
          ],
          "countryRegion": {
            "ISO": "US",
            "name": "United States"
          },
          "formattedAddress": "California"
        },
        "name": "Muir Woods National Monument"
      }
    }
  ]
}

Autocomplete API call to search for 'Muir Woods', filtered by roadblock resultTypes, address resultTypeGroups

Sample request

GET https://atlas.microsoft.com/geocode:autocomplete?api-version=2025-06-01-preview&query=Muir Woods&coordinates=-113.301894,49.201888&resultTypeGroups=Address&resultTypes=RoadBlock

Sample response

Status code:
200 
Content-Type: application/geo+json
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": null,
      "properties": {
        "typeGroup": "Address",
        "type": "RoadBlock",
        "address": {
          "streetName": "Muir St",
          "addressLine": " Muir St",
          "locality": "Grosse Pointe Farms",
          "adminDistricts": [
            {
              "name": "Michigan"
            },
            {
              "name": "Wayne County"
            }
          ],
          "countryRegion": {
            "ISO": "US",
            "name": "United States"
          },
          "postalCode": "48236",
          "formattedAddress": "Muir St, Grosse Pointe Farms, Michigan 48236, United States"
        }
      }
    }
  ]
}

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

Features of Autocomplete Result
AutocompleteProperties

Properties of Autocomplete Result
AutocompleteResponse

This object is returned from a successful autocomplete call.
AutocompleteResultTypeEnum

Type of suggestion
AutocompleteResultTypeGroupsEnum

Address or Place
CountryRegion

Country or region with its name and ISO code.
ErrorAdditionalInfo

The resource management error additional info.
ErrorDetail

The error detail.
ErrorResponse

Error response
FeatureCollectionEnum

Specifies the GeoJSON type. The only supported object type is FeatureCollection. For more information, see RFC 7946.
FeatureTypeEnum

The type of a feature must be Feature.
GeoJsonPoint

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

The address of the result.

Address

Object

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

Country or region with its name and ISO code.
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
streetName

string

The name of the street from formattedAddress
streetNumber

string

The number in the street, if available, from formattedAddress

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

AutocompleteFeature

Object

Features of Autocomplete Result

Name Type Description
geometry

GeoJsonPoint

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

AutocompleteProperties

Properties of Autocomplete Result
type

FeatureTypeEnum

Specifies the GeoJSON type. The only supported object type is Feature. For more information, see RFC 7946.

AutocompleteProperties

Object

Properties of Autocomplete Result

Name Type Description
address

Address

The address of the result
name

string

The name of the place. This field will not appear if the returned type is Address.
type

AutocompleteResultTypeEnum

Type of suggestion
typeGroup

AutocompleteResultTypeGroupsEnum

Address or Place

AutocompleteResponse

Object

This object is returned from a successful autocomplete call.

Name Type Description
features

AutocompleteFeature[]

Features of Autocomplete Result
nextLink

string

The is the link to the next page of the features returned. If it's the last page, no this field.
type

FeatureCollectionEnum

Specifies the GeoJSON type. The only supported object type is FeatureCollection. For more information, see RFC 7946.

AutocompleteResultTypeEnum

Enumeration

Type of suggestion

Value Description
Address
AdminDivision1
AdminDivision2
AdminDivision3
AdministrativeBuilding
Airport
AirportTerminal
AmusementPark
AncientSite
Aquarium
Archipelago
Basin
Battlefield
Bay
Beach
Bridge
BusinessStructure
Camp
Canal
Casino
Castle
Cave
Cemetery
Channel
Church
Cliff
Coast
CommunityCenter
Continent
CountryRegion
Crater
CulturalRegion
Dam
Delta
Desert
DrainageBasin
Dune
FacilityStructure
FerryTerminal
FinancialStructure
FireStation
Forest
Fort
Garden
Geyser
Glacier
GolfCourse
GreaterPopulatedPlace
HigherEducationFacility
HistoricalSite
Hospital
HotSpring
Ice
IndigenousPeoplesReserve
IndustrialStructure
Island
Isthmus
Lake
LandArea
Landform
LandmarkBuilding
Library
Lighthouse
Marina
Market
MedicalStructure
MetroStation
MilitaryBase
Mission
Monument
Mosque
Mountain
MountainRange
MultiModalStation
Museum
NauticalStructure
Neighborhood
Oasis
ObservationPoint
Ocean
OfficeBuilding
Other
Park
ParkingStructure
Pass
Peninsula
Plain
Planet
Plateau
Playground
PlayingField
Pole
PoliticalUnit
PopulatedPlace
Port
Postcode1
Promontory
RaceTrack
RailwayStation
Reef
ReligiousStructure
Reserve
ResidentialStructure
River
RoadBlock
Ruin
ScientificResearchBase
Sea
SeaplaneLandingArea
Shrine
SkiArea
Spring
Stadium
StatisticalDistrict
Temple
Theater
TouristRailway
TouristStructure
Trailhead
TransportationStructure
Tunnel
Valley
Volcano
Walkway
Wall
WaterFeature
Waterfall
Wetland
Winery
Zoo

AutocompleteResultTypeGroupsEnum

Enumeration

Address or Place

Value Description
Address

A specific address location. Supported types are:

  • Address
  • RoadBlock
Place

All other types belong to the Place type group. These may include entities such as AdminDivision1, Neighborhood, PopulatedPlace, and more.

CountryRegion

Object

Country or region with its name and ISO code.

Name Type Description
ISO

string

ISO of country/region
name

string

name of country/region

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.

ErrorResponse

Object

Error response

Name Type Description
error

ErrorDetail

The error object.

FeatureCollectionEnum

Enumeration

Specifies the GeoJSON type. The only supported object type is FeatureCollection. For more information, see RFC 7946.

Value Description
FeatureCollection

Specifies the GeoJSON FeatureCollection object type.

FeatureTypeEnum

Enumeration

The type of a feature must be Feature.

Value Description
Feature

Specifies the GeoJSON Feature object type.

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

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.