Eseguire la migrazione dell'API Find a Location by Query di Bing Maps
Questo articolo illustra come eseguire la migrazione dell'API Find a Location by Query di Bing Maps all'API Get Geocoding di Mappe di Azure. L'API Get Geocoding di Mappe di Azure viene usata per ottenere coordinate di longitudine e latitudine di un indirizzo, di un luogo o di un punto di riferimento. L'API Get Geocoding di Mappe di Azure supporta l'input di geocodifica in un formato non strutturato o strutturato. Questa documentazione sulla migrazione è destinata agli scenari in cui l'input di geocodifica, ad esempio l'indirizzo, la località, il CAP o il nome del punto di riferimento, si trova in un formato non strutturato (query=) - simile a quello supportato dall'API Find a Location by Query di Bing Maps. Per informazioni su come eseguire la migrazione degli scenari di Bing Maps in cui l'input di geocodifica è strutturato per trovare una posizione in base all'indirizzo, vedere Eseguire la migrazione dell'API Find a Location by Address di Bing Maps.
Prerequisiti
- Un account Azure
- Un account Mappe di Azure
- Una chiave di sottoscrizione o un altro tipo di autenticazione con Mappe di Azure
Differenze rilevanti
- L'API Find a Location by Query di Bing Maps supporta solo l'input di geocodifica in formato non strutturato, mentre l'API Get Geocoding di Mappe di Azure supporta l'input di geocodifica in un formato non strutturato (query=) o strutturato (addressLine=). Per la geocodifica dei nomi dei punti di riferimento, usare l'API Get Geocoding di Mappe di Azure con il formato di input non strutturato.
- L'API Find a Location by Query di Bing Maps restituisce coordinate in formato latitudine/longitudine, mentre l'API Get Geocoding di Mappe di Azure restituisce le coordinate in formato longitudine/latitudine, come definito dal formato GeoJSON.
- L'API Find a Location by Query di Bing Maps supporta il formato di risposta XML e JSON. L'API Get Geocoding di Mappe di Azure supporta GeoJSON.
- A differenza dell'API Find a Location by Query di Bing Maps, l'API Get Geocoding di Mappe di Azure dispone di un parametro di input
view, ovvero una stringa che rappresenta un codice paese/area ISO 3166-1 Alpha-2. Il parametro di inputviewmodifica i bordi e le etichette geopolitici contestati per allinearsi all'area utente specificata. Per altre informazioni, vedere Parametri URI. - A differenza dell'API Find a Location by Query di Bing Maps, l'API Get Geocoding di Mappe di Azure attualmente non supporta la geocodifica degli indirizzi per Cina, Giappone o Corea del Sud.
- A differenza di Bing Maps for Enterprise, Mappe di Azure è un servizio globale che supporta la specifica di un ambito geografico, il che consente di limitare la residenza dei dati alle aree geografiche di Europa (UE) o Stati Uniti (US). Tutte le richieste (inclusi i dati di input) vengono elaborate esclusivamente nell'area geografica specificata. Per altre informazioni, vedere Ambito geografico.
Sicurezza e autenticazione
Bing Maps for Enterprise supporta solo l'autenticazione con chiave API. Mappe di Azure supporta diversi modi per autenticare le chiamate API, ad esempio una chiave di sottoscrizione, Microsoft Entra ID e il token di firma di accesso condiviso (SAS). Per altre informazioni sulla sicurezza e l'autenticazione in Mappe di Azure, vedere Autenticazione con Mappe di Azure e la sezione Sicurezza nella documentazione di Mappe di Azure Ottenere la geocodifica.
Parametri della richiesta
Nella tabella seguente sono elencati i parametri di richiesta di Find a Location by Query di Bing Maps e l'equivalente di Mappe di Azure:
| Parametro di richiesta di Bing Mappe | Alias del parametro di richiesta di Bing Mappe | Mappe di Azure parametro di richiesta | Obbligatorio in Mappe di Azure | Mappe di Azure tipo di dati | Descrizione |
|---|---|---|---|---|---|
| Impostazioni cultura | c | Intestazione richiesta: Accept-Language | Falso | string | Come specificato nell'intestazione della richiesta di Mappe di Azure, culture definisce la lingua usata nei risultati della ricerca quando si usa l'API Get Geocoding di Mappe di Azure. Per altre informazioni, vedere Linguaggi supportati. |
| include | incl | Non necessario | Non necessario | Non necessaria | Nell'API Find a Location by Query di Bing Maps, il parametro di input include è necessario per ottenere un codice paese ISO a due lettere per il risultato della posizione nella risposta (include=ciso2) e per specificare che la risposta mostra come la stringa di query è stata analizzata in valori di indirizzo (include=queryParse). Nell'API Get Geocoding di Mappe di Azure il codice paese ISO a due lettere viene restituito per impostazione predefinita e non supporta un equivalente queryParse. |
| includeNeighborhood | inclnb | Non necessario | Non necessario | Non necessaria | Nell'API Get Geocoding di Mappe di Azure, le informazioni sul quartiere vengono restituite nella risposta per impostazione predefinita, se disponibili. |
| maxResults | maxRes | top | Falso | Integer (int32) | Nell'API Get Geocoding di Mappe di Azure il numero predefinito di risposte restituite è 5. Il valore minimo è 1, mentre quello massimo è 20. |
| query | q | query | Vero | string | |
| userIp | uip | Non supportato | Non supportate | Non supportate | |
| userLocation | ul | coordinate | Falso | number[] | Nell'API Get Geocoding di Mappe di Azure le coordinate sulla terra specificate come in formato longitudine e latitudine (longitude,latitude). Quando si specifica questo parametro, la posizione dell'utente viene presa in considerazione e i risultati restituiti sono più rilevanti per l'utente stesso. |
| userMapView | umv | bbox | Falso | number[] | Area rettangolare sulla terra definita come oggetto rettangolo di selezione. I lati dei rettangoli sono definiti dai valori di longitudine e latitudine (longitude1, latitude1, longitude2, latitude2). Usare la sintassi seguente per specificare un rettangolo di selezione: Longitudine occidentale, Latitudine meridionale, Longitudine orientale, Latitudine settentrionale Quando si specifica questo parametro, l'area geografica viene presa in considerazione quando si calcolano i risultati di una query sulla posizione. |
| userRegion | ur | vista | Falso | string | Stringa che rappresenta un codice area/paese ISO 3166-1 Alpha-2. Modifica i bordi e le etichette geopolitici contestati per allinearsi all'area utente specificata. Per impostazione predefinita, il parametro View è impostato su Auto, anche se non è stato definito nella richiesta. Per altre informazioni sulle viste disponibili, vedere Viste supportate. |
Per altre informazioni sui parametri di richiesta dell'API Get Geocoding di Mappe di Azure, vedere Parametri URI.
Esempi di richiesta
Richiesta POST dell'API Find a Location by Query di Bing Maps:
http://dev.virtualearth.net/REST/v1/Locations/15127 NE 24th Street Redmond WA&key={BingMapsKey}
Richiesta POST dell'API Get Geocoding di Mappe di Azure:
https://atlas.microsoft.com/geocode?api-version=2023-06-01&query=15127 NE 24th Street Redmond WA&subscription-key={Your-Azure-Maps-Subscription-key}
Campi di risposta
La tabella seguente elenca i campi che possono essere visualizzati nella risposta HTTP durante l'esecuzione della richiesta Find a Location by Query di Bing Maps e l'equivalente di Mappe di Azure:
| Campo Bing Maps | Campo Mappe di Azure | Descrizione |
|---|---|---|
| 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) |
funzionalità: bbox | In Trova una posizione tramite API Query di Bing Maps le coordinate nella risposta sono in formato latitudine/longitudine. Le coordinate nella risposta dell'API Get Geocoding di Mappe di Azure sono nel formato longitudine/latitudine (poiché viene usato il 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) |
Non supportate | formattedAddress è l'equivalente di Mappe di Azure. |
| punto (JSON) Punto (XML) |
features: coordinates | In Trova una posizione tramite API Query di Bing Maps le coordinate nella risposta sono in formato latitudine/longitudine. Le coordinate nella risposta dell'API Get Geocoding di Mappe di Azure sono nel formato longitudine/latitudine (poiché viene usato il formato GeoJSON). |
| queryParse (JSON) QueryParse (XML) |
Non supportate | |
| usageTypes (JSON) usageType (XML) |
properties: geocodePoints: usageTypes |
Per altre informazioni sui campi di risposta dell'API Get Geocoding di Mappe di Azure, vedere Definizioni.
Esempi di risposta
L'esempio JSON seguente mostra cosa viene restituito nel corpo della risposta HTTP durante l'esecuzione di una richiesta Find a Location by Query di 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"
L'esempio JSON seguente mostra cosa viene restituito nel corpo della risposta HTTP durante l'esecuzione di una richiesta Get Geocoding di Mappe di Azure:
{
"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"
}
]
}
}
}
]
}
Utilizzo delle transazioni
Come l'API Find a Location by Query di Bing Maps, l'API Get Geocoding di Mappe di Azure registra una transazione fatturabile per ogni richiesta. Per altre informazioni sulle transazioni di Mappe di Azure, vedere Informazioni sulle transazioni di Mappe di Azure.
Informazioni aggiuntive
- Get Geocoding Batch: usare per inviare un batch di query all'API Get Geocoding in una singola richiesta sincrona.
Supporto tecnico