Migración de la API Find a Location by Query de Bing Maps

Artículo
05/19/2024

En este artículo se explica cómo migrar la API Find a Location by Query 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. Esta documentación de migración es para escenarios en los que la entrada de geocodificación, como la dirección postal, la localidad, el código postal o el nombre de punto de referencia, tiene un formato no estructurado (query=): similar al que admite la API Find a Location by Query de Bing Maps. Para obtener información sobre cómo migrar escenarios de Bing Maps en los que la entrada de geocodificación esté estructurada para encontrar una ubicación por dirección, consulte Migración de la API Find a Location by Address 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 Query de Bing Maps solo admite la entrada de geocodificación en formato no estructurado, mientras que la API Get Geocoding de Azure Maps admite la entrada de geocodificación en 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 Query 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 y como se define en el formato GeoJSON.
La API Find a Location by Query 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 Query 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 entrada view modifica las etiquetas y fronteras 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 Query 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 para 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 datos a las áreas geográficas (geoáreas) 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 Query 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
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 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 Query de Bing Maps, el parámetro de entrada `include` es necesario para obtener un código de país ISO de dos letras para el resultado de la ubicación en la respuesta (include=ciso2) y para especificar que la respuesta muestre cómo se analizó la cadena de consulta en valores de dirección (include=queryParse). En la API Get Geocoding de Azure Maps, el código de país ISO de dos letras se devuelve de forma predeterminada y no se admite un queryParse equivalente.
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 forma 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.
consulta	q	query	True	string
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 se especifican 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 relevantes para el usuario.
userMapView	umv	bbox	False	number[]	Área rectangular en la tierra definida como 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. Esto modifica las etiquetas y fronteras con disputas geopolíticas para alinearse con la región de usuario especificada. De forma predeterminada, el parámetro Vista se establece en Auto aunque no se defina 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 Query de Bing Maps:

http://dev.virtualearth.net/REST/v1/Locations/15127 NE 24th Street Redmond WA&key={BingMapsKey}

Solicitud POST de la API Get Geocoding de Azure Maps:

https://atlas.microsoft.com/geocode?api-version=2023-06-01&query=15127 NE 24th Street Redmond WA&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 Query 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 Query 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 Query 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 Query 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": "7896468b37528ac145ef77cc62484fd6|MWH0032BE2|0.0.0.1|Ref A: 7D01B283F7644D2891600E265FB30B24 Ref B: CO1EDGE2318 Ref C: 2024-04-23T18:29:55Z"

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 Query 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

Foro de preguntas y respuestas de Microsoft

Compartir a través de