Search - Get Search Address Reverse

Referencia

Servicio:: Maps

Versión de la API:: 1.0

Use para obtener información de ubicación y dirección postal de las coordenadas de latitud y longitud.

La API de Get Search Address Reverse es y http GET solicitud que devuelve una dirección postal o una ubicación cuando se proporcionan coordenadas de latitud y longitud.

Puede haber ocasiones en las que necesite traducir una coordenada (ejemplo: 37.786505, -122.3862) en una dirección postal comprensible para personas. La mayoría de las veces esto es necesario en las aplicaciones de seguimiento donde se recibe una fuente GPS del dispositivo o recurso y desea saber qué dirección se encuentra la coordenada. Este punto de conexión devolverá información de dirección para una coordenada determinada.

GET https://atlas.microsoft.com/search/address/reverse/{format}?api-version=1.0&query={query}

Con parámetros opcionales:

GET https://atlas.microsoft.com/search/address/reverse/{format}?api-version=1.0&query={query}&language={language}&returnSpeedLimit={returnSpeedLimit}&heading={heading}&radius={radius}&number={number}&returnRoadUse={returnRoadUse}&roadUse={roadUse}&allowFreeformNewline={allowFreeformNewline}&returnMatchType={returnMatchType}&entityType={entityType}&view={view}

Parámetros de identificador URI

Nombre	En	Requerido	Tipo	Description
format	path	True	ResponseFormat	Formato deseado de la respuesta. El valor puede ser json o xml.
api-version	query	True	string	Número de versión de la API de Azure Maps.
query	query	True	number[]	La consulta aplicable especificada como una cadena separada por comas compuesta por latitud seguida de longitud, por ejemplo, "47.641268,-122.125679".
allowFreeformNewline	query		boolean	Formato de nuevas líneas en la dirección con formato. Si es true, la dirección contendrá nuevas líneas. Si es false, las nuevas líneas se convertirán en comas.
entityType	query		GeographicEntityType	Especifica el nivel de filtrado realizado en zonas geográficas. Limita la búsqueda de tipos de entidad geography especificados, por ejemplo, devolver solo el municipio. La respuesta resultante contendrá el identificador de geografía, así como el tipo de entidad coincidente. Si proporciona más de una entidad como una lista separada por comas, el punto de conexión devolverá la "entidad más pequeña disponible". El identificador de geometría devuelto se puede usar para obtener la geometría de esa geografía a través de Get Search Polygon API. Los parámetros siguientes se omiten cuando se establece entityType: encabezado número returnRoadUse returnSpeedLimit Uso en carretera returnMatchType
heading	query		integer minimum: -360 maximum: 360	El encabezado direccional del vehículo en grados, para viajar a lo largo de un segmento de carretera. 0 es Norte, 90 es Este y así sucesivamente, los valores van de -360 a 360. La precisión puede incluir hasta un decimal
language	query		string	Idioma en el que se deben devolver los resultados de la búsqueda. Debe ser una de las etiquetas de idioma IETF admitidas, sin distinción entre mayúsculas y minúsculas. Cuando los datos del idioma especificado no están disponibles para un campo específico, se usa el idioma predeterminado. Consulte idiomas admitidos para obtener más información.
number	query		string	Número de calle como una cadena. Si se envía un número junto con la solicitud, la respuesta puede incluir el lado de la calle (izquierda/derecha) y también una posición de desplazamiento para ese número.
radius	query		integer	Radio en metros a para que los resultados se restrinjan al área definida.
returnMatchType	query		boolean	Incluya información sobre el tipo de coincidencia del geocodificador obtenido en la respuesta.
returnRoadUse	query		boolean	Booleano. Para habilitar el retorno de la matriz de uso de carreteras para geocódigos inversos en el nivel de calle
returnSpeedLimit	query		boolean	Booleano. Para habilitar la devolución del límite de velocidad publicado
roadUse	query		RoadUseType[]	Para restringir los códigos geográficos inversos a un determinado tipo de uso de carreteras. La matriz de uso de carreteras para códigos geográficos inversos puede ser uno o varios de LimitedAccess, Arterial, Terminal, Rampa, Rotary, LocalStreet
view	query		LocalizedMapView	El parámetro View (también denominado parámetro "user region") permite mostrar los mapas correctos para un determinado país o región para regiones geopolíticamente disputadas. Los distintos países o regiones tienen vistas diferentes de estas regiones y el parámetro View permite que la aplicación cumpla con la vista requerida por el país o región a la que va a servir la aplicación. De forma predeterminada, el parámetro View se establece en "Unified" incluso si no lo ha definido en la solicitud. Es su responsabilidad determinar la ubicación de los usuarios y, a continuación, establecer el parámetro View correctamente para esa ubicación. Como alternativa, tiene la opción de establecer "View=Auto", que devolverá los datos del mapa en función de la dirección IP de la solicitud. El parámetro View de Azure Maps debe usarse de conformidad con las leyes aplicables, incluidas las relativas a la asignación, del país o región en el que los mapas, imágenes y otros datos y contenido de terceros a los que está autorizado para acceder a través de Azure Maps está disponible. Ejemplo: view=IN. 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 Id. de Microsoft Entra. 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 usar la seguridad del identificador de Entra de Microsoft en Azure Maps, consulte los siguientes artículos de para obtener instrucciones.

Respuestas

Nombre	Tipo	Description
200 OK	ReverseSearchAddressResult	De acuerdo
Other Status Codes	ErrorResponse	Se ha producido un error inesperado.

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 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 x-ms-client-id para indicar a qué recurso de Azure Maps solicita acceso la aplicación. Esto se puede adquirir desde la API de administración de de Maps.
El Authorization URL es 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 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: query

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

Searches addresses for coordinates 37.337,-121.89

Solicitud de ejemplo

HTTP

GET https://atlas.microsoft.com/search/address/reverse/json?api-version=1.0&query=37.337,-121.89

Respuesta de muestra

status code:: 200

{
  "summary": {
    "queryTime": 5,
    "numResults": 1
  },
  "addresses": [
    {
      "address": {
        "streetNumber": "31",
        "routeNumbers": [],
        "streetName": "N 2nd St",
        "streetNameAndNumber": "31 N 2nd St",
        "countryCode": "US",
        "countrySubdivisionCode": "CA",
        "countrySubdivisionName": "California",
        "municipality": "San Jose",
        "postalCode": "95113",
        "country": "United States of America",
        "countryCodeISO3": "USA",
        "freeformAddress": "31 N 2nd St, San Jose CA 95113",
        "extendedPostalCode": "951131217"
      },
      "position": "37.337090,-121.889820"
    }
  ]
}

Definiciones

Nombre	Description
Address	Dirección del resultado
BoundingBoxCompassNotation	Cuadro de límite de la ubicación.
Entity	Origen del tipo de entidad del cuadro de límite. Para la geocodificación inversa, siempre es igual a la posición.
ErrorAdditionalInfo	Información adicional sobre el error de administración de recursos.
ErrorDetail	Detalle del error.
ErrorResponse	Respuesta de error
GeographicEntityType	Tipo de entidad Geography. Presente solo cuando se solicitó entityType y está disponible.
LatLongPairAbbreviated	Una ubicación representada como latitud y longitud con nombres cortos "lat" & "lon".
LocalizedMapView	El parámetro View (también denominado parámetro "user region") permite mostrar los mapas correctos para un determinado país o región para regiones geopolíticamente disputadas. Los distintos países o regiones tienen vistas diferentes de estas regiones y el parámetro View permite que la aplicación cumpla con la vista requerida por el país o región a la que va a servir la aplicación. De forma predeterminada, el parámetro View se establece en "Unified" incluso si no lo ha definido en la solicitud. Es su responsabilidad determinar la ubicación de los usuarios y, a continuación, establecer el parámetro View correctamente para esa ubicación. Como alternativa, tiene la opción de establecer "View=Auto", que devolverá los datos del mapa en función de la dirección IP de la solicitud. El parámetro View de Azure Maps debe usarse de conformidad con las leyes aplicables, incluidas las relativas a la asignación, del país o región en el que los mapas, imágenes y otros datos y contenido de terceros a los que está autorizado para acceder a través de Azure Maps está disponible. Ejemplo: view=IN. Consulte vistas admitidas para obtener más información y ver las vistas disponibles.
MatchType	Tipos de coincidencias para una operación de búsqueda de direcciones inversas.
QueryType	Tipo de consulta que se devuelve: NEARBY o NON_NEAR.
ResponseFormat	Formato deseado de la respuesta. El valor puede ser json o xml.
ReverseSearchAddressResult	Este objeto se devuelve de una llamada inversa de dirección de búsqueda correcta.
ReverseSearchAddressResultItem	Objeto result para una respuesta inversa de dirección de búsqueda
RoadUseType	Describe los posibles usos de una carretera.
SearchSummary	Objeto summary para una respuesta de Search API.

Address

Object

Dirección del resultado

Nombre	Tipo	Description
boundingBox	BoundingBoxCompassNotation	Cuadro de límite de la ubicación.
buildingNumber	string	Número de edificio en la calle. EN DESUSO, use streetNumber en su lugar.
country	string	nombre de país o región
countryCode	string	País (Nota: Se trata de un código de dos letras, no un nombre de país o región).
countryCodeISO3	string	Código de país ISO alfa-3
countrySecondarySubdivision	string	Condado
countrySubdivision	string	Estado o provincia
countrySubdivisionCode	string	`countrySubdivisionCode` prefijo por `countryCode` ( countryCode-countrySubdivisionCode ) y el guión forma el código ISO 3166-2. Ejemplos: TX para Texas, SCT para Escocia y ON para Ontario.
countrySubdivisionName	string	Nombre completo de un primer nivel de jerarquía administrativa de país o región. Este campo solo aparece en caso de que countrySubdivision se presente en un formulario abreviado. Solo se admite para ESTADOS UNIDOS, Canadá y Reino Unido.
countryTertiarySubdivision	string	Área con nombre
crossStreet	string	Nombre de la calle que se cruza.
extendedPostalCode	string	Código postal extendido (la disponibilidad depende de la región).
freeformAddress	string	Una línea de direcciones con formato según las reglas de formato del país o región de origen de un resultado, o en el caso de un país o región, su nombre completo de país o región.
localName	string	Componente de dirección que representa el nombre de un área geográfica o localidad que agrupa varios objetos direccionables con fines de direccionamiento, sin ser una unidad administrativa. Este campo se usa para compilar la propiedad `freeformAddress`. `localName` representa el municipio postal. Dependiendo de la ubicación, `localName` es el nombre conocido de una ciudad o ciudad. Para el nombre conocido de una ciudad o ciudad, use `localName` en lugar de `municipality`.
municipality	string	Ciudad/Ciudad Nota: `municipality` representa el municipio residencial. Dependiendo de la ubicación, el valor de `municipality` puede diferir del nombre conocido de una ciudad o ciudad. Para el nombre conocido de la ciudad o la ciudad, se recomienda usar el valor de `localName` en lugar del valor de `municipality`.
municipalitySubdivision	string	Sub/Super City
neighbourhood	string	Un barrio es una zona geográficamente localizada dentro de una ciudad o ciudad con características distintivas e interacciones sociales entre los habitantes.
postalCode	string	Código postal/código postal
routeNumbers	string[]	Códigos usados para identificar inequívocamente la calle
street	string	Nombre de la calle. EN DESUSO, use streetName en su lugar.
streetName	string	Nombre de la calle.
streetNameAndNumber	string	Nombre y número de la calle.
streetNumber	string	Número de edificio en la calle.

BoundingBoxCompassNotation

Object

Cuadro de límite de la ubicación.

Nombre	Tipo	Description
entity	Entity	Origen del tipo de entidad del cuadro de límite. Para la geocodificación inversa, siempre es igual a la posición.
northEast	string	Latitud norte-este,coordenada de longitud del rectángulo de selección como floats separados por comas
southWest	string	Latitud sur-oeste,coordenada de longitud del rectángulo delimitador como floats separados por comas

Entity

Enumeración

Origen del tipo de entidad del cuadro de límite. Para la geocodificación inversa, siempre es igual a la posición.

Valor	Description
position	Entidad Position

ErrorAdditionalInfo

Object

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

Object

Detalle del error.

Nombre	Tipo	Description
additionalInfo	ErrorAdditionalInfo[]	Información adicional del error.
code	string	Código de error.
details	ErrorDetail[]	Detalles del error.
message	string	Mensaje de error.
target	string	Destino del error.

ErrorResponse

Object

Respuesta de error

Nombre	Tipo	Description
error	ErrorDetail	Objeto de error.

GeographicEntityType

Enumeración

Tipo de entidad Geography. Presente solo cuando se solicitó entityType y está disponible.

Valor	Description
Country	nombre de país o región
CountrySecondarySubdivision	Condado
CountrySubdivision	Estado o provincia
CountryTertiarySubdivision	Área con nombre
Municipality	Ciudad/Ciudad
MunicipalitySubdivision	Sub/Super City
Neighbourhood	Datos de formas
PostalCodeArea	Código postal/código postal

LatLongPairAbbreviated

Object

Una ubicación representada como latitud y longitud con nombres cortos "lat" & "lon".

Nombre	Tipo	Description
lat	number (double)	Latitude (propiedad)
lon	number (double)	Longitud (propiedad)

LocalizedMapView

Enumeración

El parámetro View (también denominado parámetro "user region") permite mostrar los mapas correctos para un determinado país o región para regiones geopolíticamente disputadas. Los distintos países o regiones tienen vistas diferentes de estas regiones y el parámetro View permite que la aplicación cumpla con la vista requerida por el país o región a la que va a servir la aplicación. De forma predeterminada, el parámetro View se establece en "Unified" incluso si no lo ha definido en la solicitud. Es su responsabilidad determinar la ubicación de los usuarios y, a continuación, establecer el parámetro View correctamente para esa ubicación. Como alternativa, tiene la opción de establecer "View=Auto", que devolverá los datos del mapa en función de la dirección IP de la solicitud. El parámetro View de Azure Maps debe usarse de conformidad con las leyes aplicables, incluidas las relativas a la asignación, del país o región en el que los mapas, imágenes y otros datos y contenido de terceros a los que está autorizado para acceder a través de Azure Maps está disponible. Ejemplo: view=IN.

Consulte vistas admitidas para obtener más información y ver las vistas disponibles.

Valor	Description
AE	Emiratos Árabes Unidos (vista árabe)
AR	Argentina (Vista argentina)
Auto	Devuelve los datos del mapa en función de la dirección IP de la solicitud.
BH	Bahréin (vista árabe)
IN	India (Vista india)
IQ	Irak (vista árabe)
JO	Jordania (vista árabe)
KW	Kuwait (vista árabe)
LB	Líbano (vista árabe)
MA	Marruecos (Vista marroquí)
OM	Oman (vista árabe)
PK	Pakistán (Vista paquistaní)
PS	Autoridad Palestina (vista árabe)
QA	Qatar (vista árabe)
SA	Arabia Saudita (vista árabe)
SY	Siria (vista árabe)
Unified	Vista unificada (otros)
YE	Yemen (vista árabe)

MatchType

Enumeración

Tipos de coincidencias para una operación de búsqueda de direcciones inversas.

Valor	Description
AddressPoint
HouseNumberRange
Street

QueryType

Enumeración

Tipo de consulta que se devuelve: NEARBY o NON_NEAR.

Valor	Description
NEARBY	La búsqueda se realizó alrededor de una determinada latitud y longitud con un radio definido
NON_NEAR	La búsqueda se realizó globalmente, sin sesgo en una determinada latitud y longitud, y sin radio definido

ResponseFormat

Enumeración

Formato deseado de la respuesta. El valor puede ser json o xml.

Valor	Description
json	el formato de intercambio de datos de notación de objetos JavaScript
xml	el lenguaje de marcado extensible

ReverseSearchAddressResult

Object

Este objeto se devuelve de una llamada inversa de dirección de búsqueda correcta.

Nombre	Tipo	Description
addresses	ReverseSearchAddressResultItem[]	Matriz de direcciones
summary	SearchSummary	Objeto Summary para una respuesta inversa de dirección de búsqueda

ReverseSearchAddressResultItem

Object

Objeto result para una respuesta inversa de dirección de búsqueda

Nombre	Tipo	Description
address	Address	Dirección del resultado
matchType	MatchType	Información sobre el tipo de coincidencia. Uno de los valores siguientes: AddressPoint (Punto de dirección) HouseNumberRange Calle
position	string	Propiedad Position en forma de "{latitud},{longitud}"
roadUse	RoadUseType[]	Describe los posibles usos de una carretera.

RoadUseType

Enumeración

Describe los posibles usos de una carretera.

Valor	Description
Arterial
LimitedAccess
LocalStreet
Ramp
Rotary
Terminal

SearchSummary

Object

Objeto summary para una respuesta de Search API.

Nombre	Tipo	Description
fuzzyLevel	integer	Nivel aproximado máximo necesario para proporcionar resultados.
geoBias	LatLongPairAbbreviated	Indicación de cuándo el motor de búsqueda interno ha aplicado un sesgo geoespacial para mejorar la clasificación de los resultados. En algunos métodos, esto puede verse afectado estableciendo los parámetros lat y lon cuando están disponibles. En otros casos, es puramente interno.
limit	integer	Número máximo de respuestas que se devolverán
numResults	integer	Número de resultados en la respuesta.
offset	integer	Desplazamiento inicial de los resultados devueltos en el conjunto de resultados completo.
query	string	Parámetro de consulta que se usó para generar estos resultados de búsqueda.
queryTime	integer	Tiempo dedicado a resolver la consulta, en milisegundos.
queryType	QueryType	Tipo de consulta que se devuelve: NEARBY o NON_NEAR.
totalResults	integer	Número total de resultados encontrados.

Compartir a través de

Search - Get Search Address Reverse

Parámetros de identificador URI

Encabezado de la solicitud

Respuestas

Seguridad

AADToken

Ámbitos

subscription-key

SAS Token

Ejemplos

Searches addresses for coordinates 37.337,-121.89

Solicitud de ejemplo

Respuesta de muestra

Definiciones

Address

BoundingBoxCompassNotation

Entity

ErrorAdditionalInfo

ErrorDetail

ErrorResponse

GeographicEntityType

LatLongPairAbbreviated

LocalizedMapView

MatchType

QueryType

ResponseFormat

ReverseSearchAddressResult

ReverseSearchAddressResultItem

RoadUseType

SearchSummary