Migración de API Geocode Dataflow de Mapas de Bing
En este artículo se explica cómo migrar la API Geocode Dataflow de Mapas de Bing a las API Geocoding Batch y Reverse Geocoding Batch de Azure Maps. La API Geocoding Batch de Azure Maps se usa para obtener las coordenadas de latitud y longitud de una dirección o el nombre de un lugar en el modo por lotes con una sola llamada API. La API Geocoding Batch de Azure Maps es una solicitud HTTP POST que envía lotes de consultas a la API Geocoding de Azure Maps en una única solicitud. La API Reverse Geocoding Batch de Azure Maps se usa para traducir las coordenadas de latitud y longitud a una dirección que los humanos puedan entender. La API Reverse Geocoding Batch de Azure Maps es una solicitud HTTP POST que envía lotes de consultas a la API Get Reverse Geocoding de Azure Maps en una única solicitud.
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 Geocode Dataflow de Mapas de Bing es compatible con la geocodificación por lotes directa e inversa dentro de la misma API. Azure Maps tiene API independientes para la geocodificación directa e inversa.
- La API Geocode Dataflow de Mapas de Bing requiere que cargue sus datos de ubicación en forma de archivo de datos XML o de texto (csv, delimitado por pestañas y por barras verticales). Las API Geocoding Batch y Reverse Geocoding Batch de Azure Maps no utiliza ningún método de carga de archivos de datos, sino una solicitud HTTP POST con datos de ubicación en formato GeoJSON en el cuerpo de la solicitud.
- La API Geocode Dataflow de Mapas de Bing es compatible con un máximo de 200 000 entidades por carga. Las API Geocoding Batch y Reverse Geocoding Batch de Azure Maps admiten un máximo de 100 consultas por lotes en las solicitudes sincrónicas y 200 000 en las solicitudes asincrónicas.
- La API Geocode Dataflow de Mapas de Bing requiere una serie de llamadas API tras la carga inicial de datos para obtener el estado y descargar los resultados. Las solicitudes sincrónicas de las API Geocoding Batch y Reverse Geocoding Batch de Azure Maps no requieren llamadas API adicionales. La solicitud asincrónica requiere llamadas adicionales para obtener el estado del proceso por lotes y descargar los resultados.
- Las coordenadas de Geocode Dataflow de Mapas de Bing están en formato latitud/longitud. Las coordenadas de las API Geocoding Batch y Reverse Geocoding Batch de Azure Maps están en formato longitud/latitud (debido a que están en formato GeoJSON).
- A diferencia de Mapas de Bing para la empresa, 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 Ámbito geográfico del servicio de Azure Maps.
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 las llamadas API, como una clave de suscripción, Microsoft Entra ID o un token de firma de acceso compartido (SAS). Para más información sobre seguridad y autenticación en Azure Maps, consulte Autenticación con Azure Maps y la Sección de seguridad en la documentación de Geocoding Batch de Azure Maps.
Parámetros de solicitud
En la tabla siguiente se enumeran los parámetros de solicitud de Geocode Dataflow de Mapas de Bing y su equivalente en Azure Maps:
| Parámetro de Mapas de Bing | Parámetro de Azure Maps | Descripción |
|---|---|---|
| dataLocation | No es necesario | |
| input | No es necesario | La API Geocode Dataflow de Mapas de Bing es compatible con los formatos XML y de texto (csv, delimitado por pestañas y por barras verticales) para el archivo de datos de entrada de la geocodificación por lotes. Azure Maps es compatible con el formato JSON para los datos de entrada de geocodificación por lotes en la solicitud HTTP POST. |
| output | No es necesario | La API Geocode Dataflow de Mapas de Bing es compatible con JSON y XML para los datos de salida de la geocodificación por lotes. Azure Maps es compatible con el formato JSON para los datos de salida de la geocodificación por lotes. |
Para más información sobre los parámetros de URI de Azure Maps y el cuerpo de la solicitud, consulte la documentación sobre Geocoding Batch y Reverse Geocoding Batch de Azure Maps.
Comparación de entrada y salida de Data Schema 2.0 de Mapas de Bing con las API de Geocode Batch y Reverse Geocode Batch de Azure Maps:
| Campo de Mapas de Bing | Operación de Mapas de Bing | Campo de Azure Maps | Tipo de datos de Azure Maps | Descripción |
|---|---|---|---|---|
| Address.AddressLine | Solicitud de código geográfico Respuesta de código geográfico |
addressLine | string | |
| Address.AdminDistrict | Solicitud de código geográfico Respuesta de código geográfico |
adminDistrict | string | |
| Address.CountryRegion | Solicitud de código geográfico Respuesta de código geográfico |
countryRegion | string | |
| Address.District | Solicitud de código geográfico | adminDistrict2 | string | |
| Address.FormattedAddress | Respuesta de código geográfico | |||
| Address.Landmark | Respuesta de código geográfico | No compatible | No compatible | |
| Address.Locality | Solicitud de código geográfico Respuesta de código geográfico |
situación | string | |
| Address.Neighborhood | Respuesta de código geográfico | neighborhood | string | |
| Address.PostalCode | Solicitud de código geográfico Respuesta de código geográfico |
postalCode | string | |
| Address.PostalTown | Solicitud de código geográfico | adminDistrict3 | ||
| BoundingBox.SouthLatitude, BoundingBox.EastLongitude, BoundingBox.NorthLatitude, BoundingBox.EastLongitude | Respuesta de código geográfico | bbox | number[] | La proyección de Azure Maps usada es EPSG:3857. Para más información, consulte RFC 7946. |
| Confianza | Respuesta de código geográfico | confidence | ConfidenceEnum | Para más información, consulte la documentación de las API Geocoding Batch y Reverse Geocoding Batch de Azure Maps. |
| ConfidenceFilter.MinimumConfidence | Solicitud de código geográfico Solicitud de código geográfico inversa |
No compatible | No compatible | |
| Referencia cultural | Solicitud de código geográfico Solicitud de código geográfico inversa |
Encabezado de solicitud: Accept-Language | string | Para más información, vea Idiomas admitidos por Azure Maps. |
| EntityType | Respuesta de código geográfico | type | string | Para más información, consulte la documentación de las API Geocoding Batch y Reverse Geocoding Batch de Azure Maps. |
| FaultReason | Respuesta de código geográfico | No compatible | No compatible | |
| GeocodeEntity | Contenedor XML | No es necesario | No es necesario | |
| GeocodeFeed | Contenedor XML | No es necesario | No es necesario | |
| GeocodePoint | Respuesta de código geográfico | geocodePoints | GeocodePoints[] | Para más información, consulte la documentación de las API Geocoding Batch y Reverse Geocoding Batch de Azure Maps. |
| GeocodeRequest | Contenedor XML | No es necesario | No es necesario | Azure Maps tiene API separadas para la geocodificación directa e inversa. |
| Identificador | Solicitud de código geográfico | No es necesario | No es necesario | |
| IncludeEntityTypes | Solicitud de código geográfico Solicitud de código geográfico inversa |
No compatible | No compatible | |
| IncludeNeighborhood | Solicitud de código geográfico Solicitud de código geográfico inversa |
No es necesario | No es necesario | En Azure Maps, la información de vecindario se devuelve de forma predeterminada en la respuesta, cuando está disponible. |
| IncludeQueryParse | Solicitud de código geográfico | No compatible | No compatible | |
| Location.Latitude Location.Longitude |
Solicitud de código geográfico inversa | coordenadas | number[] | Se requiere como entrada si se usa la API Reverse Geocoding Batch de Azure Maps para hacer la codificación geográfica inversa. |
| MatchCodes | Respuesta de código geográfico | matchCodes | MatchCodesEnum | Para más información, consulte la documentación de las API Geocoding Batch y Reverse Geocoding Batch de Azure Maps. |
| MaxResults | Solicitud de código geográfico Solicitud de código geográfico inversa |
top | integer int32 |
En Azure Maps, el número máximo de respuestas que se devuelven. El valor predeterminado es 5, el mínimo es 1 y el máximo es 20. |
| Nombre | Respuesta de código geográfico | No compatible | No compatible | |
| Point.Latitude, Point.Longitude | Respuesta de código geográfico | coordenadas | number[] | Mapas de Bing devuelve las coordenadas en formato latitud/longitud. Azure Maps devuelve las coordenadas en formato longitud/latitud (debido a que están en formato GeoJSON). |
| Consultar | Solicitud de código geográfico | query | string | |
| QueryParseValue | Respuesta de código geográfico | No compatible | No compatible | |
| ReverseGeocodeRequest | Contenedor XML | No es necesario | No es necesario | Azure Maps tiene API separadas para la geocodificación directa e inversa. |
| StatusCode | Respuesta de código geográfico | No compatible | No compatible | |
| StrictMatch | Solicitud de código geográfico | No compatible | No compatible | |
| TraceId | Respuesta de código geográfico | No compatible | No compatible | |
| Versión | No es necesario | No es necesario |
Para más información sobre los campos de respuesta de Geocoding Batch de Azure Maps, consulte la respuesta Definiciones.
Ejemplos de solicitud
Solicitud de la API Geocode Dataflow de Mapas de Bing:
http://spatial.virtualearth.net/REST/v1/Dataflows/Geocode?input=xml&key={BingMapsKey}
Para ver ejemplos que muestran datos de entrada y salida de muestra para la versión 2.0 de Geocode Dataflow, consulte Datos de entrada y salida de muestra de Geocode Dataflow, versión 2.0.
Solicitud de API Geocoding Batch de Azure Maps:
POST https://atlas.microsoft.com/geocode:batch?api-version=2023-06-01&subscription-key={Your-Azure-Maps-Subscription-key}
Para enviar las consultas de geocodificación, use una solicitud HTTP POST en la que el cuerpo de la solicitud contenga la matriz batchItems en formato JSON y el encabezado Content-Type establecido en application/json.
El siguiente JSON muestra un ejemplo de solicitud que contiene dos consultas de geocodificación, con una ubicación en formato no estructurado y otra en formato estructurado:
{
"batchItems": [
{
"addressLine": "One, Microsoft Way, Redmond, WA 98052",
"top": 2
},
{
"addressLine": "Pike Pl",
"adminDistrict": "WA",
"locality": "Seattle",
"top": 3
}
]
}
Ejemplo de solicitud de la API Reverse Geocoding Batch de Azure Maps:
POST https://atlas.microsoft.com/reverseGeocode:batch?api-version=2023-06-01&subscription-key={Your-Azure-Maps-Subscription-key}
Para enviar las consultas de geocodificación inversa, use una solicitud HTTP POST en la que el cuerpo de la solicitud contenga una matriz batchItems en formato JSON y el encabezado Content-Type esté establecido en application/json.
El siguiente JSON muestra una solicitud de ejemplo que contiene dos consultas de geocodificación inversa:
{
"batchItems": [
{
"coordinates": [
-122.128275,
47.639429
],
"resultTypes": [
"Address",
"PopulatedPlace"
],
"optionalId": "4C3681A6C8AA4AC3441412763A2A25C81444DC8B"
},
{
"coordinates": [
-122.341979399674,
47.6095253501216
],
"optionalId": "6M9W39P12SNHGAIZ4JQ7F57NWJLV2BRYEQRD7OH7"
}
]
}
Ejemplos de respuesta
Se proporciona una URL para descargar los resultados del trabajo de geocodificación cuando el trabajo por lotes de Geocode Dataflow de Mapas de Bing se procesa con éxito, como muestra el estado del trabajo completado. Para ver un ejemplo de una salida correcta de Geocode Dataflow de Mapas de Bing, consulte Datos de entrada y salida de muestra de Geocode Dataflow, versión 2.0 en la documentación de Mapas de Bing.
El siguiente ejemplo muestra lo que se devuelve en el cuerpo de la respuesta HTTP al ejecutar una solicitud de la API Geocoding Batch de Azure Maps:
{
"summary": {
"successfulRequests": 1,
"totalRequests": 2
},
"batchItems": [
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {
"type": "Address",
"confidence": "High",
"matchCodes": [
"Good"
],
"address": {
"locality": "Redmond",
"adminDistricts": [
{
"shortName": "WA"
},
{
"shortName": "King"
}
],
"countryRegion": {
"ISO": "US",
"name": "United States"
},
"postalCode": "98052",
"formattedAddress": "1 Microsoft Way, Redmond, WA 98052",
"addressLine": "1 Microsoft Way"
},
"geocodePoints": [
{
"geometry": {
"type": "Point",
"coordinates": [
-122.128275,
47.639429
]
},
"calculationMethod": "Rooftop",
"usageTypes": [
"Display",
"Route"
]
},
{
"geometry": {
"type": "Point",
"coordinates": [
-122.127028,
47.638545
]
},
"calculationMethod": "Rooftop",
"usageTypes": [
"Route"
]
}
]
},
"geometry": {
"type": "Point",
"coordinates": [
-122.128275,
47.639429
]
},
"bbox": [
-122.1359181505759,
47.63556628242932,
-122.1206318494241,
47.643291717570676
]
}
]
},
{
"error": {
"code": "Conflicting Parameters",
"message": "When 'query' is present, only the following parameters are valid: 'bbox, location, view, top'. 'addressLine' was passed"
}
}
]
}
En el ejemplo siguiente se muestra lo que se devuelve en el cuerpo de la respuesta HTTP al ejecutar una solicitud de la API Reverse Geocoding Batch de Azure Maps:
{
"batchItems": [
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
-122.1294081,
47.6391325
]
},
"properties": {
"geocodePoints": [
{
"geometry": {
"type": "Point",
"coordinates": [
-122.1294081,
47.6391325
]
},
"calculationMethod": "Rooftop",
"usageTypes": [
"Display"
]
}
],
"address": {
"addressLine": "15770 NE 31st St",
"adminDistricts": [
{
"shortName": "WA"
},
{
"shortName": "King Co."
}
],
"countryRegion": {
"name": "United States",
"iso": "US"
},
"locality": "Redmond",
"neighborhood": "Overlake",
"postalCode": "98052",
"formattedAddress": "15770 NE 31st St, Redmond, WA 98052, United States"
},
"confidence": "High",
"matchCodes": [
"Good"
],
"type": "Address"
},
"bbox": [
-122.13705120720665,
47.635269782429326,
-122.12176499279336,
47.64299521757068
]
}
]
},
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
-122.341979399674,
47.6095253501216
]
},
"properties": {
"geocodePoints": [
{
"geometry": {
"type": "Point",
"coordinates": [
-122.341979399674,
47.6095253501216
]
},
"calculationMethod": "Interpolation",
"usageTypes": [
"Display",
"Route"
]
}
],
"address": {
"addressLine": "1736 Pike Pl",
"adminDistricts": [
{
"shortName": "WA"
},
{
"shortName": "King Co."
}
],
"countryRegion": {
"name": "United States",
"iso": "US"
},
"intersection": {
"baseStreet": "Pike Pl",
"displayName": "Pike Pl and Stewart St",
"intersectionType": "Near",
"secondaryStreet1": "Stewart St",
"secondaryStreet2": null
},
"locality": "Seattle",
"neighborhood": "Downtown Seattle",
"postalCode": "98101",
"formattedAddress": "1736 Pike Pl, Seattle, WA 98101, United States"
},
"confidence": "Medium",
"matchCodes": [
"Good"
],
"type": "Address"
},
"bbox": [
-122.34961817972945,
47.605662632550924,
-122.33434061961856,
47.61338806769228
]
}
]
}
],
"summary": {
"successfulRequests": 2,
"totalRequests": 2
}
}
Uso de transacciones
De forma similar a la API Geocode Dataflow de Mapas de Bing, las API Geocoding Batch y Reverse Geocoding Batch de Azure Maps registran una transacción facturable por elemento geocodificado. Por ejemplo, 100 ubicaciones geocodificadas en la solicitud por lotes dan lugar a 100 transacciones facturables. Para más información sobre las transacciones de Azure Maps, vea Descripción de las transacciones de Azure Maps.
Información adicional
Más API de geocodificación de Azure Maps
- Get Geocoding: se usa para obtener coordenadas de latitud y longitud a partir de una dirección postal o nombre de un lugar.
- Get Reverse Geocoding: se usa para obtener una dirección postal e información de ubicación a partir de coordenadas de latitud y longitud.
Soporte técnico