Search - Get Geocode Autocomplete
Se usa para obtener una lista clasificada de entidades sugeridas en función de la ubicación de un usuario y una consulta parcial.
Dada una solicitud con la ubicación de un usuario y una consulta parcial que sirve como prefijo de una cadena de consulta completa (denominada prefijo de consulta), la API de autocompletado de Azure Maps devuelve una lista de entidades sugeridas que es más probable que el usuario esté buscando. Estas entidades se clasifican de mayor a menor probabilidad.
Importante
Al usar esta característica, acepta los términos legales de la versión preliminar. Para obtener más información, vea versión preliminar términos complementarios.
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 de identificador URI
| Nombre | En | Requerido | Tipo | Description |
|---|---|---|---|---|
|
api-version
|
query | True |
string |
Número de versión de la API de Azure Maps. |
|
query
|
query | True |
string |
Obligatorio. El prefijo de consulta del usuario. Ejemplo: "1 Micro" o "Muir Woods". |
|
bbox
|
query |
number[] |
Requerido cuando Ejemplo: lon1,lat1,lon2,lat2. Tamaño mínimo: aproximadamente 0,00001 grados (~0,01 metros). Tamaño máximo: hasta la extensión global completa (-180,-90 a 180,90) |
|
|
coordinates
|
query |
number[] |
Requerido cuando
Nota: |
|
|
country
|
query |
string |
Señal para el resultado de autocompletar a un código de región/país ISO 3166-1 Alpha-2 que se especifique, por ejemplo, FR. Solo se devolverán los resultados en el país o región especificados. |
|
|
result
|
query |
Una lista separada por comas de grupos de tipos de entidad devueltos. Los valores posibles son
|
||
|
result
|
query |
Una lista separada por comas de tipos de entidad devueltos. Cuando el grupo de tipos se establece en Dirección, los tipos admitidos son:
Todos los demás tipos pertenecen al grupo de tipos Lugar. Estos pueden incluir entidades como AdminDivision1, Neighborhood, PopulatedPlace y más. El valor predeterminado es todos los tipos de entidad posibles. |
||
|
top
|
query |
integer (int32) minimum: 1maximum: 20 |
Número máximo de respuestas que se devolverán. Predeterminado: 5, mínimo: 1 y máximo: 20. |
|
|
view
|
query |
string |
Una cadena que representa un código de región/país ISO 3166-1 Alpha-2. Esto alterará las fronteras y etiquetas geopolíticas en disputa para alinearlas con la región de usuario especificada. De forma predeterminada, el parámetro View se establece en "Auto" incluso si no lo ha definido en la solicitud. Consulte vistas admitidas para obtener más información y ver las vistas disponibles. |
Encabezado de la solicitud
| Nombre | Requerido | Tipo | Description |
|---|---|---|---|
| x-ms-client-id |
string |
Especifica qué cuenta está pensada para su uso junto con el modelo de seguridad de Azure AD. Representa un identificador único para la cuenta de Azure Maps y se puede recuperar de la API de cuenta del plano de administración de Azure Maps. Para obtener más información sobre el uso de la seguridad de ID de Microsoft Entra en Azure Maps, consulte Administración de la autenticación en Azure Maps. |
|
| Accept-Language |
string |
Idioma en el que se deben devolver los resultados de la búsqueda. Consulte idiomas admitidos para obtener más información. |
Respuestas
| Nombre | Tipo | Description |
|---|---|---|
| 200 OK |
OK Media Types: "application/geo+json" Encabezados x-ms-request-id: string |
|
| Other Status Codes |
Error inesperado. Media Types: "application/geo+json" |
Seguridad
AADToken
Estos son los flujos de Microsoft Entra OAuth 2.0. Cuando se empareja con acceso basado en rol de Azure control, se puede usar para controlar el acceso a las API REST de Azure Maps. Los controles de acceso basados en roles de Azure se usan para designar el acceso a una o varias cuentas de recursos o subrecursos de Azure Maps. Se puede conceder acceso a cualquier usuario, grupo o entidad de servicio a través de un rol integrado o de un rol personalizado compuesto por uno o varios permisos para las API REST de Azure Maps.
Para implementar escenarios, se recomienda ver los conceptos de autenticación. En resumen, esta definición de seguridad proporciona una solución para modelar aplicaciones a través de objetos capaces de controlar el acceso en determinadas API y ámbitos.
Nota:
- Esta definición de seguridad requiere el uso del encabezado para indicar a qué recurso de
x-ms-client-idAzure Maps solicita acceso la aplicación. Esto se puede adquirir desde la API de administración de Maps. - El
Authorization URLes específico de la instancia de nube pública de Azure. Las nubes soberanas tienen direcciones URL de autorización únicas y configuraciones de id. de Microsoft Entra. - El control de acceso basado en rol de Azure se configura desde el plano de administración de Azure a través de Azure Portal, PowerShell, la CLI, los SDK de Azure o las API REST.
- El uso de SDK web de Azure Maps permite la configuración basada en la configuración de una aplicación para varios casos de uso.
- Para obtener más información sobre la plataforma de identidad de Microsoft, consulte introducción a la plataforma de identidad de Microsoft.
Tipo:
oauth2
Flujo:
implicit
Dirección URL de autorización:
https://login.microsoftonline.com/common/oauth2/authorize
Ámbitos
| Nombre | Description |
|---|---|
| https://atlas.microsoft.com/.default | https://atlas.microsoft.com/.default |
subscription-key
Se trata de una clave compartida que se aprovisiona al crear una recurso de Azure Maps a través del plano de administración de Azure a través de Azure Portal, PowerShell, CLI, SDK de Azure o API REST.
Con esta clave, cualquier aplicación está autorizada para acceder a todas las API REST. En otras palabras, estos se pueden tratar actualmente como claves maestras para la cuenta para la que se emiten.
Para las aplicaciones expuestas públicamente, nuestra recomendación es usar el acceso de servidor a servidor de las API REST de Azure Maps donde esta clave se puede almacenar de forma segura.
Tipo:
apiKey
En:
header
SAS Token
Se crea un token de firma de acceso compartido a partir de la operación List SAS en el recurso de Azure Maps a través del plano de administración de Azure a través de Azure Portal, PowerShell, CLI, SDK de Azure o API REST.
Con este token, cualquier aplicación tiene autorización para acceder a los controles de acceso basados en rol de Azure y el control específico a la expiración, la tasa y las regiones de uso para el token determinado. Es decir, el token de SAS se puede usar para permitir que las aplicaciones controle el acceso de forma más segura que la clave compartida.
En el caso de las aplicaciones expuestas públicamente, nuestra recomendación es configurar una lista específica de orígenes permitidos en el recurso de cuenta de mapa de limitar el abuso de representación y renovar periódicamente el token de SAS.
Tipo:
apiKey
En:
header
Ejemplos
Autocomplete API call to search for '1 Microsoft'
Solicitud de ejemplo
GET https://atlas.microsoft.com/geocode:autocomplete?api-version=2025-06-01-preview&query=1 Microsoft&coordinates=-113.301894,49.201888
Respuesta de muestra
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
Solicitud de ejemplo
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
Respuesta de muestra
Content-Type: application/geo+json
{
"type": "FeatureCollection",
"features": []
}
Autocomplete API call to search for 'Muir Woods', filtered by address resultTypeGroups
Solicitud de ejemplo
GET https://atlas.microsoft.com/geocode:autocomplete?api-version=2025-06-01-preview&query=Muir Woods&coordinates=-113.301894,49.201888&resultTypeGroups=Address
Respuesta de muestra
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
Solicitud de ejemplo
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
Respuesta de muestra
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
Solicitud de ejemplo
GET https://atlas.microsoft.com/geocode:autocomplete?api-version=2025-06-01-preview&query=Muir Woods&coordinates=-122.581711,37.896980&resultTypes=Park
Respuesta de muestra
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
Solicitud de ejemplo
GET https://atlas.microsoft.com/geocode:autocomplete?api-version=2025-06-01-preview&query=Muir Woods&coordinates=-122.581711,37.896980&resultTypeGroups=Place
Respuesta de muestra
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
Solicitud de ejemplo
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
Respuesta de muestra
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"
}
}
}
]
}
Definiciones
| Nombre | Description |
|---|---|
| Address |
Dirección del resultado |
|
Admin |
Nombre de subdivisión en el país o región de una dirección. Este elemento normalmente se trata como la subdivisión administrativa de primer orden, pero en algunos casos también contiene la segunda, tercera o cuarta subdivisión de orden en un país, dependencia o región. |
|
Autocomplete |
Características de Autocompletar resultado |
|
Autocomplete |
Propiedades de Autocompletar resultado |
|
Autocomplete |
Este objeto se devuelve de una llamada de autocompletar correcta. |
|
Autocomplete |
Tipo de sugerencia |
|
Autocomplete |
Dirección o lugar |
|
Country |
País o región con su nombre y código ISO. |
|
Error |
Información adicional sobre el error de administración de recursos. |
|
Error |
Detalle del error. |
|
Error |
Respuesta de error |
|
Feature |
Especifica el tipo de |
|
Feature |
El tipo de una característica debe ser Feature. |
|
Geo |
Un tipo de geometría |
| Intersection |
La dirección del resultado. |
Address
Dirección del resultado
| Nombre | Tipo | Description |
|---|---|---|
| addressLine |
string |
AddressLine que incluye el nombre y el número de la calle |
| adminDistricts |
Nombre de subdivisión en el país o región de una dirección. Este elemento normalmente se trata como la subdivisión administrativa de primer orden, pero en algunos casos también contiene la segunda, tercera o cuarta subdivisión de orden en un país, dependencia o región. |
|
| countryRegion |
País o región con su nombre y código ISO. |
|
| formattedAddress |
string |
Propiedad de dirección con formato |
| intersection |
La dirección del resultado. |
|
| locality |
string |
Propiedad de localidad |
| neighborhood |
string |
Propiedad del vecindario |
| postalCode |
string |
Propiedad de código postal |
| streetName |
string |
El nombre de la calle de formattedAddress |
| streetNumber |
string |
El número en la calle, si está disponible, de formattedAddress |
AdminDistricts
Nombre de subdivisión en el país o región de una dirección. Este elemento normalmente se trata como la subdivisión administrativa de primer orden, pero en algunos casos también contiene la segunda, tercera o cuarta subdivisión de orden en un país, dependencia o región.
| Nombre | Tipo | Description |
|---|---|---|
| name |
string |
El nombre del campo adminDistrict correspondiente, For adminDistrict[0], este podría ser el nombre completo del estado como Washington, For adminDistrict[1], este podría ser el nombre completo del condado |
| shortName |
string |
El nombre corto del campo adminDistrict correspondiente, For adminDistrict[0], podría ser el nombre corto del estado como WA, For adminDistrict[1], este podría ser el nombre corto del condado |
AutocompleteFeature
Características de Autocompletar resultado
| Nombre | Tipo | Description |
|---|---|---|
| geometry |
Un tipo de geometría |
|
| properties |
Propiedades de Autocompletar resultado |
|
| type |
Especifica el tipo de |
AutocompleteProperties
Propiedades de Autocompletar resultado
| Nombre | Tipo | Description |
|---|---|---|
| address |
Dirección del resultado |
|
| name |
string |
El nombre del lugar. Este campo no aparecerá si el tipo devuelto es Dirección. |
| type |
Tipo de sugerencia |
|
| typeGroup |
Dirección o lugar |
AutocompleteResponse
Este objeto se devuelve de una llamada de autocompletar correcta.
| Nombre | Tipo | Description |
|---|---|---|
| features |
Características de Autocompletar resultado |
|
| nextLink |
string |
es el vínculo a la página siguiente de las características devueltas. Si es la última página, no hay este campo. |
| type |
Especifica el tipo de |
AutocompleteResultTypeEnum
Tipo de sugerencia
| 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
Dirección o lugar
| Valor | Description |
|---|---|
| Address |
Una ubicación de dirección específica. Los tipos admitidos son:
|
| Place |
Todos los demás tipos pertenecen al grupo de tipos Lugar. Estos pueden incluir entidades como AdminDivision1, Neighborhood, PopulatedPlace y más. |
CountryRegion
País o región con su nombre y código ISO.
| Nombre | Tipo | Description |
|---|---|---|
| ISO |
string |
ISO de país/región |
| name |
string |
nombre del país o región |
ErrorAdditionalInfo
Información adicional sobre el error de administración de recursos.
| Nombre | Tipo | Description |
|---|---|---|
| info |
object |
Información adicional. |
| type |
string |
Tipo de información adicional. |
ErrorDetail
Detalle del error.
| Nombre | Tipo | Description |
|---|---|---|
| additionalInfo |
Información adicional del error. |
|
| code |
string |
Código de error. |
| details |
Detalles del error. |
|
| message |
string |
El mensaje de error. |
| target |
string |
Destino del error. |
ErrorResponse
Respuesta de error
| Nombre | Tipo | Description |
|---|---|---|
| error |
Objeto de error. |
FeatureCollectionEnum
Especifica el tipo de GeoJSON. El único tipo de objeto admitido es FeatureCollection. Para obtener más información, consulte RFC 7946.
| Valor | Description |
|---|---|
| FeatureCollection |
Especifica el tipo de objeto |
FeatureTypeEnum
El tipo de una característica debe ser Feature.
| Valor | Description |
|---|---|
| Feature |
Especifica el tipo de objeto feature de |
GeoJsonPoint
Un tipo de geometría GeoJSON Point válido. Consulte RFC 7946 para obtener más información.
Intersection
La dirección del resultado.
| Nombre | Tipo | Description |
|---|---|---|
| baseStreet |
string |
Calle principal para la ubicación. |
| displayName |
string |
Nombre completo de la intersección. |
| intersectionType |
string |
Tipo de intersección. |
| secondaryStreet1 |
string |
La primera calle que se cruza. |
| secondaryStreet2 |
string |
Si lo hay, la segunda calle que se cruza. |