Search - Get Reverse Geocoding
Úselo para obtener información sobre la dirección y la ubicación de las coordenadas de longitud y latitud.
La API de Get Reverse Geocoding es una solicitud de GET HTTP que se usa para traducir una coordenada (ejemplo: 37.786505, -122.3862) en una dirección postal comprensible humana. Resulta útil en el seguimiento de aplicaciones en las que recibe una fuente GPS del dispositivo o recurso y desea conocer la dirección asociada a las coordenadas. Este punto de conexión devolverá información de dirección para una coordenada determinada.
GET {endpoint}/reverseGeocode?api-version=2026-01-01&coordinates={coordinates}
GET {endpoint}/reverseGeocode?api-version=2026-01-01&coordinates={coordinates}&resultTypes={resultTypes}&view={view}
Parámetros de identificador URI
| Nombre | En | Requerido | Tipo | Description |
|---|---|---|---|---|
|
endpoint
|
path | True |
string (uri) |
El nombre de host del servicio Azure Maps. Usa |
|
api-version
|
query | True |
string minLength: 1 |
Versión de API que se usará para esta operación. |
|
coordinates
|
query | True |
number[] |
Coordenadas de la ubicación en la que desea invertir el código geográfico. Ejemplo: &coordinates=lon,lat |
|
result
|
query |
Especifique los tipos de entidad que desee en la respuesta. Solo se devolverán los tipos que especifique. Si el punto no se puede asignar a los tipos de entidad especificados, no se devuelve información de ubicación en la respuesta. El valor predeterminado es todas las entidades posibles. Lista separada por comas de tipos de entidad seleccionados de las siguientes opciones.
Estos tipos de entidad se ordenan de la entidad más específica a la entidad menos específica. Cuando se encuentran entidades de más de un tipo de entidad, solo se devuelve la entidad más específica. Por ejemplo, si especifica Address y AdminDistrict1 como tipos de entidad y entidades se encontraron para ambos tipos, solo se devuelve la información de la entidad Address en la respuesta. |
||
|
view
|
query |
string |
Cadena que representa un código de país o región ISO 3166-1 Alpha-2. Esto modificará los bordes y etiquetas disputados geopolíticas para alinearse con la región de usuario especificada. De manera predeterminada, el parámetro View está establecido en "Auto", aunque no lo haya 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á destinada a usarse junto con el modelo de seguridad de Azure AD. Representa un ID único para la cuenta de Azure Maps y puede recuperarse desde la API de cuentas de Azure Maps Management Plane. Para más información sobre el uso de la seguridad Microsoft Entra ID en Azure Maps, consulte Gestionar 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 |
La solicitud se ha realizado correctamente. Media Types: "application/geo+json", "application/json" |
|
| Other Status Codes |
Una respuesta de error inesperada. Media Types: "application/geo+json", "application/json" Encabezados x-ms-error-code: string |
Seguridad
AadToken
Estos son los flujos Microsoft Entra OAuth 2.0. Cuando se combina con el control de acceso basado en roles Azure puede usarse para controlar el acceso a Azure Maps APIs REST. Los controles de acceso basados en roles de Azure se utilizan para designar el acceso a una o más cuentas o subrecursos de recursos 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 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.
Note
- Esta definición de seguridad requiere el uso del encabezado
x-ms-client-idpara indicar a qué recurso de Azure 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 URLs de Autorización y configuraciones de Microsoft Entra ID únicas. - 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 |
subscription-key
Se trata de una clave compartida que se aprovisiona al Creación de una cuenta de Azure Maps en Azure Portal o mediante PowerShell, la CLI, los SDK de Azure o la API REST.
Con esta clave, cualquier aplicación puede acceder a todas las API REST. En otras palabras, esta clave se puede usar como clave maestra en la cuenta en la que se emiten.
Para las aplicaciones expuestas públicamente, nuestra recomendación es usar las aplicaciones cliente confidenciales enfoque acceder a las API REST de Azure Maps para que la clave se pueda 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
Search point -122.138681, 47.630358
Solicitud de ejemplo
GET https://atlas.microsoft.com/reverseGeocode?api-version=2026-01-01&coordinates=-122.138681,47.630358
Respuesta de muestra
Content-Type: application/geo+json
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {
"address": {
"countryRegion": {
"name": "United States"
},
"adminDistricts": [
{
"name": "Washington",
"shortName": "WA"
},
{
"name": "King County",
"shortName": "King Co."
}
],
"formattedAddress": "15127 NE 24th St, Redmond, Washington 98052",
"streetName": "NE 24th St",
"streetNumber": "15127",
"locality": "Redmond",
"postalCode": "98052",
"addressLine": "15127 NE 24th St"
},
"type": "Address",
"confidence": "Medium",
"matchCodes": [
"Good"
],
"geocodePoints": [
{
"geometry": {
"type": "Point",
"coordinates": [
-122.138681,
47.630358
]
},
"calculationMethod": "Rooftop",
"usageTypes": [
"Display"
]
},
{
"geometry": {
"type": "Point",
"coordinates": [
-122.1386787,
47.6302179
]
},
"calculationMethod": "Rooftop",
"usageTypes": [
"Route"
]
}
]
},
"geometry": {
"type": "Point",
"coordinates": [
-122.138681,
47.630358
]
},
"bbox": [
-122.14632282407,
47.626495282429325,
-122.13103917593001,
47.63422071757068
]
}
]
}
Definiciones
| Nombre | Description |
|---|---|
| Address |
Dirección del resultado |
|
Address |
Nombre de subdivisión en el país o región de una dirección. |
|
Address |
País o región con su nombre y código ISO. |
|
Azure. |
Objeto de error. |
|
Azure. |
Respuesta que contiene los detalles del error. |
|
Azure. |
Objeto que contiene información más específica sobre el error. Según las directrices de Azure API REST - https://aka.ms/AzureRestApiGuidelines#handling-errors. |
|
Calculation |
Método que se usó para calcular el punto de código geográfico. |
|
Confidence |
Nivel de confianza de que el resultado de la ubicación geocodificada es una coincidencia. Use este valor con el código de coincidencia para determinar para obtener información más completa sobre la coincidencia. La confianza de una ubicación geocodificada se basa en muchos factores, incluida la importancia relativa de la ubicación geocodificada y la ubicación del usuario, si se especifica. |
|
Feature |
Especifica el tipo de |
|
Features |
Un objeto de características. |
|
Features |
Propiedades de la característica. |
|
Feature |
El tipo de una característica debe ser Característica. |
|
Geocode |
Un punto de geocódigo. |
|
Geocoding |
Este objeto se devuelve de una llamada de geocodificación correcta. |
|
Geo |
Especifica el tipo de |
|
Geo |
Un tipo de geometría |
| Intersection |
Dirección del resultado. |
|
Match |
Un enum que representa el código de coincidencia. |
|
Reverse |
Un enum que representa el tipo de resultado de geocodificación inversa. |
|
Usage |
Un enum que representa el tipo de uso. |
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 |
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 |
AddressAdminDistrictsItem
Nombre de subdivisión en el país o región de una dirección.
| Nombre | Tipo | Description |
|---|---|---|
| name |
string |
El nombre del campo adminDistrict correspondiente, Para adminDistrict[0], este podría ser el nombre completo del estado, como Washington, For adminDistrict[1], podría ser el nombre completo del condado. |
| shortName |
string |
El nombre corto del campo adminDistrict correspondiente, Para adminDistrict[0], podría ser un nombre corto de estado como WA, For adminDistrict[1], podría ser el nombre corto del condado. |
AddressCountryRegion
País o región con su nombre y código ISO.
| Nombre | Tipo | Description |
|---|---|---|
| ISO |
string |
ISO del país o región |
| name |
string |
nombre del país o región |
Azure.Core.Foundations.Error
Objeto de error.
| Nombre | Tipo | Description |
|---|---|---|
| code |
string |
Uno de un conjunto definido por el servidor de códigos de error. |
| details |
Matriz de detalles sobre errores específicos que llevaron a este error notificado. |
|
| innererror |
Objeto que contiene información más específica que el objeto actual sobre el error. |
|
| message |
string |
Representación legible del error. |
| target |
string |
Destino del error. |
Azure.Core.Foundations.ErrorResponse
Respuesta que contiene los detalles del error.
| Nombre | Tipo | Description |
|---|---|---|
| error |
Objeto de error. |
Azure.Core.Foundations.InnerError
Objeto que contiene información más específica sobre el error. Según las directrices de Azure API REST - https://aka.ms/AzureRestApiGuidelines#handling-errors.
| Nombre | Tipo | Description |
|---|---|---|
| code |
string |
Uno de un conjunto definido por el servidor de códigos de error. |
| innererror |
Error interno. |
CalculationMethodEnum
Método que se usó para calcular el punto de código geográfico.
| Valor | Description |
|---|---|
| Interpolation |
El punto de geocodificación se hizo coincidir con un punto de una carretera mediante interpolación. |
| InterpolationOffset |
El punto de geocodificación se hizo coincidir con un punto de una carretera mediante interpolación con un desplazamiento adicional para desplazar el punto al lado de la calle. |
| Parcel |
El punto de geocodificación se ha hecho coincidir con el centro de una parcela. |
| Rooftop |
El punto de geocodificación se hizo coincidir con la azotea de un edificio. |
ConfidenceEnum
Nivel de confianza de que el resultado de la ubicación geocodificada es una coincidencia. Use este valor con el código de coincidencia para determinar para obtener información más completa sobre la coincidencia.
La confianza de una ubicación geocodificada se basa en muchos factores, incluida la importancia relativa de la ubicación geocodificada y la ubicación del usuario, si se especifica.
| Valor | Description |
|---|---|
| High |
Si la confianza se establece en Si una solicitud incluye una ubicación o una vista, la clasificación puede cambiar adecuadamente. Por ejemplo, una consulta de ubicación para "París" devuelve "París, Francia" y "París, TX" con |
| Medium |
En algunas situaciones, es posible que la coincidencia devuelta no esté al mismo nivel que la información proporcionada en la solicitud. Por ejemplo, una solicitud puede especificar información de dirección y es posible que el servicio de geocodificación solo pueda coincidir con un código postal. En este caso, si el servicio de geocodificación tiene la confianza de que el código postal coincide con los datos, la confianza se establece en Si la información de ubicación de la consulta es ambigua y no hay información adicional para clasificar las ubicaciones (como la ubicación del usuario o la importancia relativa de la ubicación), la confianza se establece en Si la información de ubicación de la consulta no proporciona suficiente información para geocodificar una ubicación específica, es posible que se devuelva un valor de ubicación menos preciso y la confianza se establezca en |
| Low |
Low |
FeatureCollectionEnum
Especifica el tipo de GeoJSON. El único tipo de objeto admitido es FeatureCollection. Para obtener más información, vea RFC 7946.
| Valor | Description |
|---|---|
| FeatureCollection |
Especifica el tipo de objeto |
FeaturesItem
Un objeto de características.
FeaturesItemProperties
Propiedades de la característica.
| Nombre | Tipo | Description |
|---|---|---|
| address |
Dirección del resultado |
|
| confidence |
Nivel de confianza de que el resultado de la ubicación geocodificada es una coincidencia. Use este valor con el código de coincidencia para determinar para obtener información más completa sobre la coincidencia. La confianza de una ubicación geocodificada se basa en muchos factores, incluida la importancia relativa de la ubicación geocodificada y la ubicación del usuario, si se especifica. |
|
| geocodePoints |
Colección de puntos de código geográfico que difieren en cómo se calcularon y su uso sugerido. |
|
| matchCodes |
Uno o varios valores de código coincidentes que representan el nivel de geocodificación para cada ubicación de la respuesta. Por ejemplo, una ubicación con codificación geográfica con códigos de coincidencia de Del mismo modo, una ubicación codificada geográficamente con códigos de coincidencia de Los valores posibles son:
|
|
| type |
string |
Uno de: * Dirección * Barrio de Carretera * Intersección de Carretera * Barrio * Lugar Poblado * Código Postal 1 * División Administrativa1 * División Administrativa2 * PaísRegión |
FeatureTypeEnum
El tipo de una característica debe ser Característica.
| Valor | Description |
|---|---|
| Feature |
Especifica el tipo de objeto feature de |
GeocodePointsItem
Un punto de geocódigo.
GeocodingResponse
Este objeto se devuelve de una llamada de geocodificación correcta.
| Nombre | Tipo | Description |
|---|---|---|
| features |
Una serie de características devueltas de la consulta. |
|
| 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 |
GeoJsonObjectType
Especifica el tipo de GeoJSON. Debe ser uno de los nueve tipos de objeto GeoJSON válidos: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature y FeatureCollection.
| Valor | Description |
|---|---|
| Point |
|
| MultiPoint |
|
| LineString |
|
| MultiLineString |
|
| Polygon |
|
| MultiPolygon |
|
| GeometryCollection |
|
| Feature |
Objeto |
| FeatureCollection |
Objeto |
GeoJsonPoint
Un tipo de geometría GeoJSON Point válido. Consulte RFC 7946 para obtener más información.
Intersection
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 intersección de la calle. |
| secondaryStreet2 |
string |
Si existe, la segunda calle que interseca. |
MatchCodesEnum
Un enum que representa el código de coincidencia.
| Valor | Description |
|---|---|
| Good |
Bueno |
| Ambiguous |
Ambigua |
| UpHierarchy |
UpHierarchy |
ReverseGeocodingResultTypeEnum
Un enum que representa el tipo de resultado de geocodificación inversa.
| Valor | Description |
|---|---|
| Address |
Dirección |
| Neighborhood |
Vecindario |
| PopulatedPlace |
PopulatedPlace |
| Postcode1 |
Código postal1 |
| AdminDivision1 |
AdminDivision1 |
| AdminDivision2 |
AdminDivision2 |
| CountryRegion |
País/Región |
UsageTypeEnum
Un enum que representa el tipo de uso.
| Valor | Description |
|---|---|
| Display |
Mostrar |
| Route |
Route |