Search - Get Geocode Autocomplete
Use para obter uma lista classificada de entidades sugeridas com base na localização de um usuário e em uma consulta parcial.
Dada uma solicitação com o local de um usuário e uma consulta parcial que serve como o prefixo de uma cadeia de caracteres de consulta completa (referida como um prefixo de consulta), a API de Preenchimento Automático do Azure Maps retorna uma lista de entidades sugeridas que o usuário provavelmente está procurando. Estas entidades são classificadas do mais ao menos provável.
Importante
Ao usar esse recurso, você concorda com os termos legais de visualização. Para obter mais informações, consulte Preview Supplemental Terms.
GET https://atlas.microsoft.com/geocode:autocomplete?api-version=2025-06-01-preview&query={query}
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}
Parâmetros do URI
| Name | Em | Necessário | Tipo | Description |
|---|---|---|---|---|
|
api-version
|
query | True |
string |
Número da versão da API do Azure Maps. |
|
query
|
query | True |
string |
Required. O prefixo da consulta do usuário. Exemplo: "1 Micro" ou "Muir Woods". |
|
bbox
|
query |
number[] |
Necessário quando Exemplo: lon1,lat1,lon2,lat2. Tamanho mínimo: aproximadamente 0,00001 graus (~0,01 metros). Tamanho máximo: até a extensão global total (-180,-90 a 180,90) |
|
|
coordinates
|
query |
number[] |
Necessário quando
Observação: |
|
|
country
|
query |
string |
Sinal para o resultado de preenchimento automático para um código de região/país ISO 3166-1 Alpha-2 especificado, por exemplo, FR. Somente os resultados no país/região especificado serão retornados. |
|
|
result
|
query |
Uma lista separada por vírgulas de grupos de tipos de entidade retornados. Os valores possíveis são
|
||
|
result
|
query |
Uma lista separada por vírgulas dos tipos de entidade retornados. Quando o grupo de tipos é definido como Endereço, os tipos suportados são:
Todos os outros tipos pertencem ao grupo Tipo de lugar. Isso pode incluir entidades como AdminDivision1, Neighborhood, PopulatedPlace e muito mais. O valor padrão é todos os tipos de entidade possíveis. |
||
|
top
|
query |
integer (int32) minimum: 1maximum: 20 |
Número máximo de respostas que serão devolvidas. Padrão: 5, mínimo: 1 e máximo: 20. |
|
|
view
|
query |
string |
Uma cadeia de caracteres que representa um código de região/país ISO 3166-1 Alpha-2. Isso alterará fronteiras e rótulos disputados geopoliticamente para se alinhar com a região de usuário especificada. Por padrão, o parâmetro View é definido como "Auto", mesmo que você não o tenha definido na solicitação. Consulte de Visualizações Suportadas para obter detalhes e ver as Visualizações disponíveis. |
Cabeçalho do Pedido
| Name | Necessário | Tipo | Description |
|---|---|---|---|
| x-ms-client-id |
string |
Especifica qual conta deve ser usada em conjunto com o modelo de segurança do Azure AD. Ele representa uma ID exclusiva para a conta do Azure Maps e pode ser recuperado da API de Conta do plano de gerenciamento do Azure Maps. Para obter mais informações sobre como usar a segurança do Microsoft Entra ID no Azure Maps, consulte Gerenciar autenticação no Azure Maps. |
|
| Accept-Language |
string |
Idioma em que os resultados da pesquisa devem ser retornados. |
Respostas
| Name | Tipo | Description |
|---|---|---|
| 200 OK |
OK Media Types: "application/geo+json" Cabeçalhos x-ms-request-id: string |
|
| Other Status Codes |
Ocorreu um erro inesperado. Media Types: "application/geo+json" |
Segurança
AADToken
Estes são os Microsoft Entra OAuth 2.0 Flows. Quando emparelhado com controle de de acesso baseado em função do Azure, ele pode ser usado para controlar o acesso às APIs REST do Azure Maps. Os controles de acesso baseados em função do Azure são usados para designar o acesso a uma ou mais contas de recursos ou subrecursos do Azure Maps. Qualquer usuário, grupo ou entidade de serviço pode receber acesso por meio de uma função interna ou uma função personalizada composta por uma ou mais permissões para APIs REST do Azure Maps.
Para implementar cenários, recomendamos a visualização conceitos de autenticação. Em resumo, essa definição de segurança fornece uma solução para modelar aplicativos(s) por meio de objetos capazes de controle de acesso em APIs e escopos específicos.
Observação
- Essa definição de segurança requer o uso do cabeçalho
x-ms-client-idpara indicar a qual recurso do Azure Maps o aplicativo está solicitando acesso. Isso pode ser adquirido na API de gerenciamento do Maps. - O
Authorization URLé específico para a instância de nuvem pública do Azure. As nuvens soberanas têm URLs de autorização exclusivas e configurações de ID do Microsoft Entra. - O controle de acesso baseado em função do Azure é configurado a partir do plano de gerenciamento do Azure por meio do portal do Azure, PowerShell, CLI, SDKs do Azure ou APIs REST.
- O uso do SDK da Web do Azure Maps permite a configuração baseada em configuração de um aplicativo para vários casos de uso.
- Para obter mais informações sobre a plataforma de identidade da Microsoft, consulte visão geral da plataforma de identidade da Microsoft.
Tipo:
oauth2
Fluxo:
implicit
URL de Autorização:
https://login.microsoftonline.com/common/oauth2/authorize
Âmbitos
| Name | Description |
|---|---|
| https://atlas.microsoft.com/.default | https://atlas.microsoft.com/.default |
subscription-key
Essa é uma chave compartilhada que é provisionada ao criar um de recursos do
Com essa chave, qualquer aplicativo está autorizado a acessar todas as APIs REST. Por outras palavras, estas podem atualmente ser tratadas como chaves mestras para a conta para a qual foram emitidas.
Para aplicativos expostos publicamente, nossa recomendação é usar o acesso de servidor para servidor das APIs REST do Azure Maps onde essa chave pode ser armazenada com segurança.
Tipo:
apiKey
Em:
header
SAS Token
Este é um token de assinatura de acesso compartilhado criado a partir da operação Listar SAS no de recursos do
Com esse token, qualquer aplicativo é autorizado a acessar com controles de acesso baseados em função do Azure e controle de grão fino para a expiração, taxa e região(ões) de uso para o token específico. Em outras palavras, o Token SAS pode ser usado para permitir que os aplicativos controlem o acesso de forma mais segura do que a chave compartilhada.
Para aplicativos expostos publicamente, nossa recomendação é configurar uma lista específica de origens permitidas no de recursos da conta do
Tipo:
apiKey
Em:
header
Exemplos
Autocomplete API call to search for '1 Microsoft'
Pedido de amostra
GET https://atlas.microsoft.com/geocode:autocomplete?api-version=2025-06-01-preview&query=1 Microsoft&coordinates=-113.301894,49.201888
Resposta da amostra
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
Pedido de amostra
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
Resposta da amostra
Content-Type: application/geo+json
{
"type": "FeatureCollection",
"features": []
}
Autocomplete API call to search for 'Muir Woods', filtered by address resultTypeGroups
Pedido de amostra
GET https://atlas.microsoft.com/geocode:autocomplete?api-version=2025-06-01-preview&query=Muir Woods&coordinates=-113.301894,49.201888&resultTypeGroups=Address
Resposta da amostra
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
Pedido de amostra
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
Resposta da amostra
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
Pedido de amostra
GET https://atlas.microsoft.com/geocode:autocomplete?api-version=2025-06-01-preview&query=Muir Woods&coordinates=-122.581711,37.896980&resultTypes=Park
Resposta da amostra
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
Pedido de amostra
GET https://atlas.microsoft.com/geocode:autocomplete?api-version=2025-06-01-preview&query=Muir Woods&coordinates=-122.581711,37.896980&resultTypeGroups=Place
Resposta da amostra
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
Pedido de amostra
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
Resposta da amostra
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"
}
}
}
]
}
Definições
| Name | Description |
|---|---|
| Address |
O endereço do resultado |
|
Admin |
O nome da subdivisão no país ou região de um endereço. Este elemento é normalmente tratado como a subdivisão administrativa de primeira ordem, mas em alguns casos também contém a subdivisão de segunda, terceira ou quarta ordem em um país, dependência ou região. |
|
Autocomplete |
Características do resultado de preenchimento automático |
|
Autocomplete |
Propriedades do resultado de preenchimento automático |
|
Autocomplete |
Este objeto é retornado de uma chamada de preenchimento automático bem-sucedida. |
|
Autocomplete |
Tipo de sugestão |
|
Autocomplete |
Endereço ou Local |
|
Country |
País ou região com o seu nome e código ISO. |
|
Error |
O erro de gerenciamento de recursos informações adicionais. |
|
Error |
O detalhe do erro. |
|
Error |
Resposta de erro |
|
Feature |
Especifica o tipo de |
|
Feature |
O tipo de recurso deve ser Recurso. |
|
Geo |
Um tipo de geometria |
| Intersection |
O endereço do resultado. |
Address
O endereço do resultado
| Name | Tipo | Description |
|---|---|---|
| addressLine |
string |
AddressLine que inclui o nome e o número da rua |
| adminDistricts |
O nome da subdivisão no país ou região de um endereço. Este elemento é normalmente tratado como a subdivisão administrativa de primeira ordem, mas em alguns casos também contém a subdivisão de segunda, terceira ou quarta ordem em um país, dependência ou região. |
|
| countryRegion |
País ou região com o seu nome e código ISO. |
|
| formattedAddress |
string |
Propriedade de endereço formatado |
| intersection |
O endereço do resultado. |
|
| locality |
string |
Propriedade de localidade |
| neighborhood |
string |
Propriedade do bairro |
| postalCode |
string |
Propriedade do código postal |
| streetName |
string |
O nome da rua de formattedAddress |
| streetNumber |
string |
O número na rua, se disponível, de formattedAddress |
AdminDistricts
O nome da subdivisão no país ou região de um endereço. Este elemento é normalmente tratado como a subdivisão administrativa de primeira ordem, mas em alguns casos também contém a subdivisão de segunda, terceira ou quarta ordem em um país, dependência ou região.
| Name | Tipo | Description |
|---|---|---|
| name |
string |
O nome para o campo adminDistrict correspondente, Para adminDistrict[0], este poderia ser o nome completo do estado, como Washington, Para adminDistrict[1], este poderia ser o nome completo do condado |
| shortName |
string |
O nome curto para o campo adminDistrict correspondente, Para adminDistrict[0], este poderia ser o nome curto do estado, como WA, Para adminDistrict[1], este poderia ser o nome curto do condado |
AutocompleteFeature
Características do resultado de preenchimento automático
| Name | Tipo | Description |
|---|---|---|
| geometry |
Um tipo de geometria |
|
| properties |
Propriedades do resultado de preenchimento automático |
|
| type |
Especifica o tipo de |
AutocompleteProperties
Propriedades do resultado de preenchimento automático
| Name | Tipo | Description |
|---|---|---|
| address |
O endereço do resultado |
|
| name |
string |
O nome do lugar. Este campo não aparecerá se o tipo retornado for Endereço. |
| type |
Tipo de sugestão |
|
| typeGroup |
Endereço ou Local |
AutocompleteResponse
Este objeto é retornado de uma chamada de preenchimento automático bem-sucedida.
| Name | Tipo | Description |
|---|---|---|
| features |
Características do resultado de preenchimento automático |
|
| nextLink |
string |
O é o link para a próxima página dos recursos retornados. Se for a última página, não há este campo. |
| type |
Especifica o tipo de |
AutocompleteResultTypeEnum
Tipo de sugestão
| Valor | 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
Endereço ou Local
| Valor | Description |
|---|---|
| Address |
Um local de endereço específico. Os tipos suportados são:
|
| Place |
Todos os outros tipos pertencem ao grupo Tipo de lugar. Isso pode incluir entidades como AdminDivision1, Neighborhood, PopulatedPlace e muito mais. |
CountryRegion
País ou região com o seu nome e código ISO.
| Name | Tipo | Description |
|---|---|---|
| ISO |
string |
ISO do país/região |
| name |
string |
nome do país/região |
ErrorAdditionalInfo
O erro de gerenciamento de recursos informações adicionais.
| Name | Tipo | Description |
|---|---|---|
| info |
object |
As informações adicionais. |
| type |
string |
O tipo de informação adicional. |
ErrorDetail
O detalhe do erro.
| Name | Tipo | Description |
|---|---|---|
| additionalInfo |
O erro informações adicionais. |
|
| code |
string |
O código de erro. |
| details |
Os detalhes do erro. |
|
| message |
string |
A mensagem de erro. |
| target |
string |
O destino do erro. |
ErrorResponse
Resposta de erro
| Name | Tipo | Description |
|---|---|---|
| error |
O objeto de erro. |
FeatureCollectionEnum
Especifica o tipo de GeoJSON. O único tipo de objeto suportado é FeatureCollection. Para obter mais informações, consulte RFC 7946.
| Valor | Description |
|---|---|
| FeatureCollection |
Especifica o tipo de objeto |
FeatureTypeEnum
O tipo de recurso deve ser Recurso.
| Valor | Description |
|---|---|
| Feature |
Especifica o tipo de objeto |
GeoJsonPoint
Um tipo de geometria GeoJSON Point válido. Consulte RFC 7946 para obter detalhes.
Intersection
O endereço do resultado.
| Name | Tipo | Description |
|---|---|---|
| baseStreet |
string |
Rua principal para o local. |
| displayName |
string |
Nome completo do cruzamento. |
| intersectionType |
string |
Tipo de intersecção. |
| secondaryStreet1 |
string |
A primeira rua que se cruza. |
| secondaryStreet2 |
string |
Se houver, a segunda rua que se cruza. |