Migración de la API Find a Location by Address de Bing Maps
En este artículo, se explica cómo migrar la API Find a Location by Address de Bing Maps a la API Get Geocoding de Azure Maps. La API Get Geocoding de Azure Maps se usa para obtener coordenadas de longitud y latitud de una dirección postal, un lugar o un punto de referencia. La API Get Geocoding de Azure Maps admite la entrada de geocodificación en un formato no estructurado o estructurado. En este artículo, se tratan escenarios en los que la entrada de geocodificación, como la dirección postal, está en formato estructurado, similar a lo que admite la API Find a Location by Address de Bing Maps. Para obtener información sobre cómo migrar escenarios de Bing Maps en los que la entrada de geocodificación no está estructurada para obtener coordenadas de longitud y latitud de una dirección postal, un lugar o un punto de referencia, consulte Migración de la API Find a Location by Query de Bing Maps.
Requisitos previos
- Una cuenta de Azure
- Una cuenta de Azure Maps
- Una clave de suscripción u otra forma de Autenticación con Azure Maps
Diferencias destacadas
- La API Find a Location by Address de Bing Maps solo admite la entrada de geocodificación en formato estructurado, mientras que la API Get Geocoding de Azure Maps admite la entrada de geocodificación en un formato no estructurado (query=) o estructurado (addressLine=). Para los nombres de puntos de referencia de geocodificación, use la API Get Geocoding de Azure Maps mediante el formato de entrada no estructurado.
- La API Find a Location by Address de Bing Maps devuelve coordenadas en formato de latitud/longitud, mientras que la API Get Geocoding de Azure Maps devuelve coordenadas en formato de longitud/latitud, tal como se define en el formato GeoJSON.
- La API Find a Location by Address de Bing Maps admite el formato de respuesta XML y JSON. La API Get Geocoding de Azure Maps admite GeoJSON.
- A diferencia de la API Find a Location by Address de Bing Maps, la API Get Geocoding de Azure Maps tiene un parámetro de entrada
view, que es una cadena que representa un código ISO 3166-1 Alpha-2 de región o país. El parámetro de entradaviewmodifica las fronteras y las etiquetas con disputas geopolíticas para alinearse con la región de usuario especificada. Para obtener más información, consulte Parámetros de URI. - A diferencia de la API Find a Location by Address de Bing Maps, la API Get Geocoding de Azure Maps no admite actualmente la geocodificación de direcciones para China, Japón o Corea del Sur.
- A diferencia de Bing Maps for Enterprise, Azure Maps es un servicio global que admite la especificación de un ámbito geográfico, lo que le permite limitar la residencia de los datos a las áreas geográficas (geografías) de Europa (EU) o Estados Unidos (EE. UU.). Todas las solicitudes (incluidos los datos de entrada) se procesan exclusivamente en el área geográfica especificada. Para obtener más información, consulte el ámbito geográfico.
Seguridad y autenticación
Mapas de Bing para la empresa solo admite la autenticación de clave de API. Azure Maps admite varias formas de autenticar llamadas API, como una clave de suscripción, Microsoft Entra ID y token de firma de acceso compartido (SAS). Para más información sobre la seguridad y la autenticación en Azure Maps, consulte Autenticación con Azure Maps y la Sección seguridad en la documentación de obtención de geocodificación de Azure Maps.
Parámetros de solicitud
En la tabla siguiente, se enumeran los parámetros de solicitud de Find a Location by Address de Bing Maps y el equivalente de Azure Maps:
| Parámetro de solicitud de Bing Maps | Alias del parámetro de solicitud de Bing Maps | Parámetro de solicitud de Azure Maps | Obligatorio en Azure Maps | Tipo de datos de Azure Maps | Descripción |
|---|---|---|---|---|---|
| Parámetro de solicitud de Bing Maps | Alias del parámetro de solicitud de Bing Maps | Parámetro de solicitud de Azure Maps | Obligatorio en Azure Maps | Tipo de datos de Azure Maps | Nota |
| addressLine | addressLine | False | string | En la API Get Geocoding de Azure Maps, una dirección postal o una dirección postal con localidad y adminDistrict, es la entrada admitida para addressLine. |
|
| adminDistrict | adminDistrict | False | string | ||
| countryRegion | countryRegion | False | string | ||
| situación | situación | False | string | ||
| postalCode | postalCode | False | string | ||
| culture | c | Encabezado de solicitud: Accept-Language | False | string | Como se especifica en el encabezado de solicitud de Azure Maps, culture define el idioma usado en los resultados de la búsqueda al usar la API Get Geocoding de Azure Maps. Para más información, consulte Lenguajes admitidos. |
| include | incl | No es necesario | No es necesario | No es necesario | En la API Find a Location by Address de Bing Maps, se requiere el parámetro de entrada ‘include’ para obtener un código de país ISO de dos letras para el resultado de la ubicación en la respuesta (include=ciso2). En la API Get Geocoding de Azure Maps, el código de país ISO de dos letras se devuelve de manera predeterminada. |
| includeNeighborhood | inclnb | No es necesario | No es necesario | No es necesario | En la API Get Geocoding de Azure Maps, la información de vecindario se devuelve de manera predeterminada en la respuesta, cuando está disponible. |
| maxResults | maxRes | top | False | Entero (int32) | En la API Get Geocoding de Azure Maps, el número predeterminado de respuestas devueltas es 5. El valor mínimo es 1 y el máximo, 20. |
| strictMatch | sm | No compatible | No compatible | No compatible | |
| userIp | uip | No compatible | No compatible | No compatible | |
| userLocation | ul | coordenadas | False | number[] | En la API Get Geocoding de Azure Maps, las coordenadas de la tierra especificadas en formato de longitud y latitud (longitud,latitud). Al especificar este parámetro, se tiene en cuenta la ubicación del usuario y los resultados devueltos son más pertinentes para el usuario. |
| userMapView | umv | bbox | False | number[] | Un área rectangular en la tierra definida como un objeto de rectángulo delimitador. Los lados de los rectángulos se definen mediante valores de longitud y latitud (longitude1,latitude1,longitude2,latitude2). Utilice la siguiente sintaxis para especificar un rectángulo delimitador:West Longitude, South Latitude, East Longitude, North Latitude Al especificar este parámetro, el área geográfica se tiene en cuenta al calcular los resultados de una consulta de ubicación. |
| userRegion | ur | ver | False | string | Cadena que representa un código de país o región ISO 3166-1 Alpha-2 que modifica las fronteras y las etiquetas con disputas geopolíticas para alinearse con la región de usuario especificada. De manera predeterminada, el parámetro View se establece en Auto aunque no esté definido en la solicitud. Para obtener más información sobre las vistas disponibles, consulte Vistas admitidas. |
Para obtener más información sobre los parámetros de solicitud de la API Get Geocoding de Azure Maps, consulte Parámetros de URI.
Ejemplos de solicitud
Solicitud POST de la API Find a Location by Address de Bing Maps:
http://dev.virtualearth.net/REST/v1/Locations/US/WA/Redmond/15127 NE 24th Street?&key={BingMapsKey}
Solicitud POST de la API Get Geocoding de Azure Maps:
https://atlas.microsoft.com/geocode?api-version=2023-06-01&adminDistrict=WA&locality=Redmond&addressLine=15127 NE 24th Street&subscription-key={Your-Azure-Maps-Subscription-key}
Campos de respuesta
En la tabla siguiente, se enumeran los campos que pueden aparecer en la respuesta HTTP al ejecutar la solicitud de Find a Location by Address de Bing Maps y el equivalente de Azure Maps:
| Campo de Bing Maps | Campo de Azure Maps | Descripción |
|---|---|---|
| address: addressLine (JSON) Address: AddressLine (XML) |
address: addressLine | |
| address: adminDistrict (JSON) Address: AdminDistrict (XML) |
address: adminDistricts | |
| address: adminDistrict2 (JSON) Address: AdminDistrict2 (XML) |
address: adminDistricts | |
| address: countryRegion (JSON) Address: CountryRegion (XML) |
address: countryRegion | |
| address: countryRegionIso2 (JSON) Address: CountryRegionIso2 (XML) |
address: countryRegion - iso | |
| address: neighborhood (JSON) Address: Neighborhood (XML) |
address: neighborhood | |
| address: formattedAddress (JSON) Address: FormattedAddress (XML) |
address: formattedAddress | |
| address: locality (JSON) Address: Locality (XML) |
address: locality | |
| address: postalCode (JSON) Address: PostalCode (XML) |
address: postalCode | |
| address: Intersection – baseStreet (JSON) Address: Intersection – BaseStreet (XML) |
address: intersection -baseStreet | |
| address: Intersection – secondaryStreet1 (JSON) |
address: intersection - secondaryStreet1 | |
| address: Intersection – secondaryStreet2 (JSON) Address: Intersection – SecondaryStreet2 (XML) |
address: intersection - secondaryStreet2 | |
| address: Intersection – intersectionType (JSON) Address: Intersection – IntersectionType (XML) |
address: intersection - intersectionType | |
| address: Intersection – displayName (JSON) Address: Intersection – DisplayName (XML) |
address: intersection - displayName | |
| bbox (JSON) BoundingBox (XML) |
features: bbox | En la API Find a Location by Address de Bing Maps, las coordenadas de la respuesta están en formato latitud/longitud. Las coordenadas de la respuesta de la API Get Geocoding de Azure Maps están en formato longitud/latitud (ya que se usa el formato GeoJSON). |
| calculationMethod (JSON) CalculationMethod (XML) |
properties: geocodePoints - calculationMethod | |
| confidence (JSON) Confidence (XML) |
properties: confidence | |
| entityType (JSON) EntityType (XML) |
properties: type | |
| geocodePoints (JSON) GeocodePoint (XML) |
properties: geocodePoints - coordinates | |
| matchCodes (JSON) MatchCode (XML) |
properties: matchCodes | |
| name (JSON) Name (XML) |
No compatible | formattedAddress es el equivalente de Azure Maps. |
| point (JSON) Point (XML) |
features: coordinates | En la API Find a Location by Address de Bing Maps, las coordenadas de la respuesta están en formato latitud/longitud. Las coordenadas de la respuesta de la API Get Geocoding de Azure Maps están en formato longitud/latitud (ya que se usa el formato GeoJSON). |
| queryParse (JSON) QueryParse (XML) |
No compatible | |
| usageTypes (JSON) usageType (XML) |
properties: geocodePoints: usageTypes |
Para obtener más información sobre los campos de respuesta de la API Get Geocoding de Azure Maps, consulte Definiciones.
Ejemplos de respuesta
En el ejemplo JSON siguiente, se muestra lo que se devuelve en el cuerpo de la respuesta HTTP al ejecutar la solicitud de Find a Location by Address de Bing Maps:
{
"authenticationResultCode": "ValidCredentials",
"brandLogoUri": "https://dev.virtualearth.net/Branding/logo_powered_by.png",
"copyright": "Copyright © 2024 Microsoft and its suppliers. All rights reserved. This API cannot be accessed and the content and any results may not be used, reproduced or transmitted in any manner without express written permission from Microsoft Corporation.",
"resourceSets": [
{
"estimatedTotal": 1,
"resources": [
{
"__type": "Location:http://schemas.microsoft.com/search/local/ws/rest/v1",
"bbox": [
47.62649628242932,
-122.14631082421619,
47.634221717570675,
-122.1310271757838
],
"name": "15127 NE 24th St, Redmond, WA 98052",
"point": {
"type": "Point",
"coordinates": [
47.630359,
-122.138669
]
},
"address": {
"addressLine": "15127 NE 24th St",
"adminDistrict": "WA",
"adminDistrict2": "King County",
"countryRegion": "United States",
"formattedAddress": "15127 NE 24th St, Redmond, WA 98052",
"locality": "Redmond",
"postalCode": "98052"
},
"confidence": "High",
"entityType": "Address",
"geocodePoints": [
{
"type": "Point",
"coordinates": [
47.630359,
-122.138669
],
"calculationMethod": "Rooftop",
"usageTypes": [
"Display"
]
},
{
"type": "Point",
"coordinates": [
47.630563,
-122.1387383
],
"calculationMethod": "Rooftop",
"usageTypes": [
"Route"
]
}
],
"matchCodes": [
"Good"
]
}
]
}
],
"statusCode": 200,
"statusDescription": "OK",
"traceId": "e0a7cb31a835ffbcc7e2b8f6b1a0b4e0|MWH0032BE3|0.0.0.1|Ref A: 9BC4F0B708B04F2EA6D52CB3461458A6 Ref B: CO1EDGE1411 Ref C: 2024-04-23T23:44:47Z"
En el ejemplo JSON siguiente, se muestra lo que se devuelve en el cuerpo de la respuesta HTTP al ejecutar la solicitud de Get Geocoding de Azure Maps:
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
-122.138679,
47.630356
]
},
"bbox": [
-122.14632082377759,
47.62649328242932,
-122.1310371762224,
47.634218717570675
],
"properties": {
"type": "Address",
"confidence": "High",
"matchCodes": [
"Good"
],
"geocodePoints": [
{
"calculationMethod": "Rooftop",
"usageTypes": [
"Display"
],
"geometry": {
"type": "Point",
"coordinates": [
-122.138679,
47.630356
]
}
},
{
"calculationMethod": "Rooftop",
"usageTypes": [
"Route"
],
"geometry": {
"type": "Point",
"coordinates": [
-122.138685,
47.6305637
]
}
}
],
"address": {
"addressLine": "15127 NE 24th St",
"postalCode": "98052",
"locality": "Redmond",
"formattedAddress": "15127 NE 24th St, Redmond, WA 98052",
"countryRegion": {
"name": "United States",
"ISO": "US"
},
"adminDistricts": [
{
"shortName": "WA"
},
{
"shortName": "King County"
}
]
}
}
}
]
}
Uso de transacciones
Al igual que la API Find a Location by Address de Bing Maps, la API Get Geocoding de Azure Maps registra una transacción facturable por solicitud. Para más información sobre las transacciones de Azure Maps, vea Descripción de las transacciones de Azure Maps.
Información adicional
- Get Geocoding Batch: se usa para enviar un lote de consultas a la API Get Geocoding en una única solicitud sincrónica.
Soporte técnico