Search - Get Reverse Geocoding
Usare per ottenere un indirizzo e informazioni sulla posizione dalle coordinate di longitudine e latitudine.
L'API Get Reverse Geocoding
è una richiesta HTTP GET
usata per tradurre una coordinata (ad esempio: 37.786505, -122.3862) in un indirizzo comprensibile. Utile nelle applicazioni di rilevamento in cui si riceve un feed GPS dal dispositivo o asset e si desidera conoscere l'indirizzo associato alle coordinate. Questo endpoint restituirà le informazioni sull'indirizzo per una determinata coordinata.
GET https://atlas.microsoft.com/reverseGeocode?api-version=2023-06-01&coordinates={coordinates}
GET https://atlas.microsoft.com/reverseGeocode?api-version=2023-06-01&coordinates={coordinates}&resultTypes={resultTypes}&view={view}
Parametri dell'URI
Nome | In | Necessario | Tipo | Descrizione |
---|---|---|---|---|
api-version
|
query | True |
string |
Numero di versione dell'API Mappe di Azure. |
coordinates
|
query | True |
number[] |
Coordinate della posizione da invertire il codice geografico. Esempio: coordinate &=lon,lat |
result
|
query |
Specificare i tipi di entità desiderati nella risposta. Verranno restituiti solo i tipi specificati. Se il punto non può essere mappato ai tipi di entità specificati, nella risposta non vengono restituite informazioni sulla posizione. Il valore predefinito è tutte le entità possibili. Elenco delimitato da virgole di tipi di entità selezionati dalle opzioni seguenti.
Questi tipi di entità vengono ordinati dall'entità più specifica all'entità meno specifica. Quando vengono trovate entità di più tipi di entità, viene restituita solo l'entità più specifica. Ad esempio, se si specifica Address e AdminDistrict1 come tipi di entità e entità sono state trovate per entrambi i tipi, nella risposta vengono restituite solo le informazioni sull'entità Address. |
||
view
|
query |
string |
Stringa che rappresenta un codice di area/paese ISO 3166-1 Alfa-2. In questo modo verranno modificati 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 informazioni dettagliate, vedere Visualizzazioni supportate e visualizzare le visualizzazioni disponibili. |
Intestazione della richiesta
Nome | Necessario | Tipo | Descrizione |
---|---|---|---|
x-ms-client-id |
string |
Specifica l'account destinato all'utilizzo in combinazione con il modello di sicurezza di Azure AD. Rappresenta un ID univoco per l'account Mappe di Azure e può essere recuperato dall'API account del piano di gestione di Mappe di Azure. Per usare la sicurezza di Azure AD in Mappe di Azure, vedere gli articoli seguenti per indicazioni. |
|
Accept-Language |
string |
Lingua in cui devono essere restituiti i risultati della ricerca. Per informazioni dettagliate, vedere Lingue supportate . |
Risposte
Nome | Tipo | Descrizione |
---|---|---|
200 OK |
OK Media Types: "application/geo+json" |
|
Other Status Codes |
Si è verificato un errore imprevisto. Media Types: "application/geo+json" |
Sicurezza
AADToken
Si tratta dei flussi Microsoft Entra OAuth 2.0 . Se abbinato al controllo degli accessi in base al ruolo di Azure , può essere usato per controllare l'accesso alle API REST di Mappe di Azure. I controlli di accesso in base al ruolo di Azure vengono usati per designare l'accesso a uno o più account di risorse di Mappe di Azure o a risorse secondarie. A qualsiasi utente, gruppo o entità servizio può essere concesso l'accesso tramite un ruolo predefinito o un ruolo personalizzato composto da una o più autorizzazioni per le API REST di Mappe di Azure.
Per implementare scenari, è consigliabile visualizzare i concetti di autenticazione. In sintesi, questa definizione di sicurezza offre una soluzione per la modellazione di applicazioni tramite oggetti in grado di controllare l'accesso su API e ambiti specifici.
Nota
- Questa definizione di sicurezza richiede l'uso dell'intestazione
x-ms-client-id
per indicare a quale risorsa di Mappe di Azure l'applicazione richiede l'accesso. Questa operazione può essere acquisita dall'API di gestione mappe. - è
Authorization URL
specifico dell'istanza del cloud pubblico di Azure. I cloud sovrani hanno URL di autorizzazione univoci e configurazioni ID Microsoft Entra. - Il controllo degli accessi in base al ruolo di Azure viene configurato dal piano di gestione di Azure tramite il portale di Azure, PowerShell, l'interfaccia della riga di comando, gli SDK di Azure o le API REST.
- L'utilizzo di Azure Maps Web SDK consente la configurazione basata sulla configurazione di un'applicazione per più casi d'uso.
- Per altre informazioni su Microsoft Identity Platform, vedere Panoramica di Microsoft Identity Platform.
Tipo:
oauth2
Flow:
implicit
URL di autorizzazione:
https://login.microsoftonline.com/common/oauth2/authorize
Ambiti
Nome | Descrizione |
---|---|
https://atlas.microsoft.com/.default | https://atlas.microsoft.com/.default |
subscription-key
Si tratta di una chiave condivisa di cui viene effettuato il provisioning durante la creazione di una risorsa di Mappe di Azure tramite il portale di Azure, PowerShell, l'interfaccia della riga di comando, gli SDK di Azure o le API REST.
Con questa chiave, qualsiasi applicazione è autorizzata ad accedere a tutte le API REST. In altre parole, queste chiavi possono essere considerate come chiavi master per l'account per cui vengono rilasciate.
Per le applicazioni esposte pubblicamente, è consigliabile usare l'accesso da server a server delle API REST di Mappe di Azure in cui questa chiave può essere archiviata in modo sicuro.
Tipo:
apiKey
In:
header
SAS Token
Si tratta di un token di firma di accesso condiviso creato dall'operazione Elenca firma di accesso condiviso nella risorsa mappe di Azure tramite il piano di gestione di Azure tramite il portale di Azure, PowerShell, l'interfaccia della riga di comando, gli SDK di Azure o le API REST.
Con questo token, qualsiasi applicazione è autorizzata ad accedere con i controlli di accesso in base al ruolo di Azure e il controllo granulare alla scadenza, alla frequenza e alle aree d'uso per il token specifico. In altre parole, il token di firma di accesso condiviso può essere usato per consentire alle applicazioni di controllare l'accesso in modo più protetto rispetto alla chiave condivisa.
Per le applicazioni esposte pubblicamente, è consigliabile configurare un elenco specifico di origini consentite nella risorsa dell'account map per limitare l'abuso di rendering e rinnovare regolarmente il token di firma di accesso condiviso.
Tipo:
apiKey
In:
header
Esempio
Search point -122.138681, 47.630358
Esempio di richiesta
GET https://atlas.microsoft.com/reverseGeocode?api-version=2023-06-01&coordinates=-122.138681,47.630358
Risposta di esempio
Content-Type: application/geo+json
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {
"address": {
"countryRegion": {
"name": "United States"
},
"adminDistricts": [
{
"shortName": "WA"
},
{
"shortName": "King County"
}
],
"formattedAddress": "15127 NE 24th St, Redmond, WA 98052",
"locality": "Redmond",
"postalCode": "98052",
"addressLine": "15127 NE 24th St"
},
"type": "Address",
"confidence": "Medium",
"matchCodes": [
"Good"
],
"geocodePoints": [
{
"geometry": {
"type": "Point",
"coordinates": [
-122.138681,
47.630358
]
},
"calculationMethod": "Rooftop",
"usageTypes": [
"Display"
]
},
{
"geometry": {
"type": "Point",
"coordinates": [
-122.1386787,
47.6302179
]
},
"calculationMethod": "Rooftop",
"usageTypes": [
"Route"
]
}
]
},
"geometry": {
"type": "Point",
"coordinates": [
-122.138681,
47.630358
]
},
"bbox": [
-122.14632282407,
47.626495282429325,
-122.13103917593001,
47.63422071757068
]
}
]
}
Definizioni
Nome | Descrizione |
---|---|
Address |
Indirizzo del risultato |
Admin |
Nome della suddivisione nel paese o nell'area geografica per un indirizzo. Questo elemento viene in genere considerato come suddivisione amministrativa del primo ordine, ma in alcuni casi contiene anche la seconda, terza o quarta suddivisione dell'ordine in un paese, una dipendenza o un'area geografica. |
Calculation |
Metodo usato per calcolare il punto di geocodifica. |
Confidence |
Il livello di confidenza che il risultato della posizione geocodificata è una corrispondenza. Usare questo valore con il codice di corrispondenza per determinare per informazioni più complete sulla corrispondenza. L'attendibilità di una posizione geocodificata si basa su molti fattori, tra cui l'importanza relativa della posizione geocodificata e la posizione dell'utente, se specificato. |
Country |
|
Error |
Informazioni aggiuntive sull'errore di gestione delle risorse. |
Error |
Dettagli dell'errore. |
Error |
Risposta di errore |
Feature |
Il tipo di un oggetto FeatureCollection deve essere FeatureCollection. |
Features |
|
Feature |
Il tipo di una funzionalità deve essere Feature. |
Geocode |
Raccolta di punti geocodifica che differiscono in base alla modalità di calcolo e all'uso suggerito. |
Geocoding |
Questo oggetto viene restituito da una chiamata geocodifica riuscita |
Geo |
Tipo di geometria valido |
Intersection |
Indirizzo del risultato. |
Match |
Uno o più valori di codice corrispondenti che rappresentano il livello di geocodifica per ogni posizione nella risposta. Ad esempio, una posizione geocodificata con codici di corrispondenza di Analogamente, una posizione geocodificata con codici di corrispondenza di I valori possibili sono:
|
Properties | |
Reverse |
Specificare i tipi di entità desiderati nella risposta. Verranno restituiti solo i tipi specificati. Se il punto non può essere mappato ai tipi di entità specificati, nella risposta non vengono restituite informazioni sulla posizione. Il valore predefinito è tutte le entità possibili. Elenco delimitato da virgole di tipi di entità selezionati dalle opzioni seguenti.
Questi tipi di entità vengono ordinati dall'entità più specifica all'entità meno specifica. Quando vengono trovate entità di più tipi di entità, viene restituita solo l'entità più specifica. Ad esempio, se si specifica Address e AdminDistrict1 come tipi di entità e entità sono state trovate per entrambi i tipi, nella risposta vengono restituite solo le informazioni sull'entità Address. |
Usage |
L'uso migliore per il punto di geocodifica.
Ogni punto di geocodifica è definito come |
Address
Indirizzo del risultato
Nome | Tipo | Descrizione |
---|---|---|
addressLine |
string |
AddressLine che include nome e numero di strada |
adminDistricts |
Nome della suddivisione nel paese o nell'area geografica per un indirizzo. Questo elemento viene in genere considerato come suddivisione amministrativa del primo ordine, ma in alcuni casi contiene anche la seconda, terza o quarta suddivisione dell'ordine in un paese, una dipendenza o un'area geografica. |
|
countryRegion | ||
formattedAddress |
string |
Proprietà Address formattata |
intersection |
Indirizzo del risultato. |
|
locality |
string |
proprietà locality |
neighborhood |
string |
proprietà del quartiere |
postalCode |
string |
Proprietà Postal Code |
AdminDistricts
Nome della suddivisione nel paese o nell'area geografica per un indirizzo. Questo elemento viene in genere considerato come suddivisione amministrativa del primo ordine, ma in alcuni casi contiene anche la seconda, terza o quarta suddivisione dell'ordine in un paese, una dipendenza o un'area geografica.
Nome | Tipo | Descrizione |
---|---|---|
name |
string |
Il nome del campo adminDistrict corrispondente, Per adminDistrict[0], potrebbe trattarsi del nome completo dello stato, ad esempio Washington, Per adminDistrict[1], questo potrebbe essere il nome completo della contea |
shortName |
string |
Nome breve per il campo adminDistrict corrispondente, Per adminDistrict[0], potrebbe trattarsi di un nome breve di stato, ad esempio WA, Per adminDistrict[1], potrebbe trattarsi del nome breve della contea |
CalculationMethodEnum
Metodo usato per calcolare il punto di geocodifica.
Nome | Tipo | Descrizione |
---|---|---|
Interpolation |
string |
Il punto di geocodifica è stato confrontato con un punto su una strada usando l'interpolazione. |
InterpolationOffset |
string |
Il punto di geocodifica è stato confrontato con un punto su una strada utilizzando l'interpolazione con un offset aggiuntivo per spostare il punto sul lato della strada. |
Parcel |
string |
Il punto di geocodifica è stato associato al centro di un pacco. |
Rooftop |
string |
Il punto di geocodifica è stato abbinato al tetto di un edificio. |
ConfidenceEnum
Il livello di confidenza che il risultato della posizione geocodificata è una corrispondenza. Usare questo valore con il codice di corrispondenza per determinare per informazioni più complete sulla corrispondenza.
L'attendibilità di una posizione geocodificata si basa su molti fattori, tra cui l'importanza relativa della posizione geocodificata e la posizione dell'utente, se specificato.
Nome | Tipo | Descrizione |
---|---|---|
High |
string |
Se l'attendibilità è impostata su Se una richiesta include una posizione o una visualizzazione, la classificazione può cambiare in modo appropriato. Ad esempio, una query di posizione per "Parigi" restituisce "Parigi, Francia" e "Parigi, TX" con |
Low |
string |
|
Medium |
string |
In alcune situazioni, la corrispondenza restituita potrebbe non essere allo stesso livello delle informazioni fornite nella richiesta. Ad esempio, una richiesta può specificare le informazioni sull'indirizzo e il servizio di geocodifica può corrispondere solo a un codice postale. In questo caso, se il servizio di geocodifica ha la certezza che il codice postale corrisponda ai dati, l'attendibilità viene impostata su e il codice di corrispondenza è impostato Se le informazioni sulla posizione nella query sono ambigue e non sono presenti informazioni aggiuntive per classificare le posizioni , ad esempio la posizione dell'utente o l'importanza relativa della posizione, l'attendibilità viene impostata su Se le informazioni sulla posizione nella query non forniscono informazioni sufficienti per la geocodifica di una posizione specifica, è possibile che venga restituito un valore di posizione meno preciso e che l'attendibilità sia impostata su |
CountryRegion
Nome | Tipo | Descrizione |
---|---|---|
ISO |
string |
ISO del paese/area geografica |
name |
string |
nome del paese/area geografica |
ErrorAdditionalInfo
Informazioni aggiuntive sull'errore di gestione delle risorse.
Nome | Tipo | Descrizione |
---|---|---|
info |
object |
Informazioni aggiuntive. |
type |
string |
Tipo di informazioni aggiuntive. |
ErrorDetail
Dettagli dell'errore.
Nome | Tipo | Descrizione |
---|---|---|
additionalInfo |
Informazioni aggiuntive sull'errore. |
|
code |
string |
Codice di errore. |
details |
Dettagli dell'errore. |
|
message |
string |
Messaggio di errore. |
target |
string |
Destinazione dell'errore. |
ErrorResponse
Risposta di errore
Nome | Tipo | Descrizione |
---|---|---|
error |
Oggetto error. |
FeatureCollectionEnum
Il tipo di un oggetto FeatureCollection deve essere FeatureCollection.
Nome | Tipo | Descrizione |
---|---|---|
FeatureCollection |
string |
FeaturesItem
Nome | Tipo | Descrizione |
---|---|---|
bbox |
number[] |
Riquadro. Proiezione usata : EPSG:3857. Per informazioni dettagliate, vedere RFC 7946 . |
geometry |
Tipo di geometria valido |
|
id |
string |
ID per la funzionalità restituita |
properties | ||
type |
Il tipo di una funzionalità deve essere Feature. |
FeatureTypeEnum
Il tipo di una funzionalità deve essere Feature.
Nome | Tipo | Descrizione |
---|---|---|
Feature |
string |
GeocodePoints
Raccolta di punti geocodifica che differiscono in base alla modalità di calcolo e all'uso suggerito.
Nome | Tipo | Descrizione |
---|---|---|
calculationMethod |
Metodo usato per calcolare il punto di geocodifica. |
|
geometry |
Tipo di geometria valido |
|
usageTypes |
L'uso migliore per il punto di geocodifica.
Ogni punto di geocodifica è definito come |
GeocodingResponse
Questo oggetto viene restituito da una chiamata geocodifica riuscita
Nome | Tipo | Descrizione |
---|---|---|
features | ||
nextLink |
string |
è il collegamento alla pagina successiva delle funzionalità restituite. Se si tratta dell'ultima pagina, nessun campo. |
type |
Il tipo di un oggetto FeatureCollection deve essere FeatureCollection. |
GeoJsonPoint
Tipo di geometria valido GeoJSON Point
. Per informazioni dettagliate, vedere RFC 7946 .
Nome | Tipo | Descrizione |
---|---|---|
bbox |
number[] |
Riquadro. Proiezione usata : EPSG:3857. Per informazioni dettagliate, vedere RFC 7946 . |
coordinates |
number[] |
Un |
type |
string:
Point |
Specifica il tipo di oggetto |
Intersection
Indirizzo del risultato.
Nome | Tipo | Descrizione |
---|---|---|
baseStreet |
string |
Strada primaria per la posizione. |
displayName |
string |
Nome completo dell'intersezione. |
intersectionType |
string |
Tipo di intersezione. |
secondaryStreet1 |
string |
La prima strada intersecante. |
secondaryStreet2 |
string |
In caso affermativo, la seconda strada intersecante. |
MatchCodesEnum
Uno o più valori di codice corrispondenti che rappresentano il livello di geocodifica per ogni posizione nella risposta.
Ad esempio, una posizione geocodificata con codici di corrispondenza di Good
e Ambiguous
indica che sono state trovate più posizioni geocodificate per le informazioni sulla posizione e che il servizio di geocodifica non ha eseguito ricerche nella gerarchia superiore per trovare una corrispondenza.
Analogamente, una posizione geocodificata con codici di corrispondenza di Ambiguous
e UpHierarchy
implica che non è stato possibile trovare una posizione geografica corrispondente a tutte le informazioni sulla posizione fornite, quindi il servizio di geocodice doveva cercare in alto la gerarchia e trovare più corrispondenze a quel livello. Un esempio di up an Ambiguous
e UpHierarchy
result è quando si forniscono informazioni complete sull'indirizzo, ma il servizio di geocodifica non è in grado di individuare una corrispondenza per l'indirizzo stradale e restituisce invece le informazioni per più di un valore RoadBlock.
I valori possibili sono:
Good
: il percorso ha una sola corrispondenza o tutte le corrispondenze restituite sono considerate corrispondenze complesse. Ad esempio, una query per New York restituisce diverse corrispondenze Valide.
Ambiguous
: il percorso è uno dei set di possibili corrispondenze. Ad esempio, quando si esegue una query per l'indirizzo 128 Main St., la risposta può restituire due posizioni per 128 North Main St. e 128 South Main St. perché non sono disponibili informazioni sufficienti per determinare quale opzione scegliere.
UpHierarchy
: la posizione rappresenta uno spostamento verso l'alto nella gerarchia geografica. Ciò si verifica quando non è stata trovata una corrispondenza per la richiesta di posizione, quindi viene restituito un risultato meno preciso. Ad esempio, se non è possibile trovare una corrispondenza per l'indirizzo richiesto, potrebbe essere restituito un codice di corrispondenza di con un tipo di UpHierarchy
entità RoadBlock.
Nome | Tipo | Descrizione |
---|---|---|
Ambiguous |
string |
|
Good |
string |
|
UpHierarchy |
string |
Properties
Nome | Tipo | Descrizione |
---|---|---|
address |
Indirizzo del risultato |
|
confidence |
Il livello di confidenza che il risultato della posizione geocodificata è una corrispondenza. Usare questo valore con il codice di corrispondenza per determinare per informazioni più complete sulla corrispondenza. L'attendibilità di una posizione geocodificata si basa su molti fattori, tra cui l'importanza relativa della posizione geocodificata e la posizione dell'utente, se specificato. |
|
geocodePoints |
Raccolta di punti geocodifica che differiscono in base alla modalità di calcolo e all'uso suggerito. |
|
matchCodes |
Uno o più valori di codice corrispondenti che rappresentano il livello di geocodifica per ogni posizione nella risposta. Ad esempio, una posizione geocodificata con codici di corrispondenza di Analogamente, una posizione geocodificata con codici di corrispondenza di I valori possibili sono:
|
|
type |
string |
Uno dei valori possibili:
|
ReverseGeocodingResultTypeEnum
Specificare i tipi di entità desiderati nella risposta. Verranno restituiti solo i tipi specificati. Se il punto non può essere mappato ai tipi di entità specificati, nella risposta non vengono restituite informazioni sulla posizione. Il valore predefinito è tutte le entità possibili. Elenco delimitato da virgole di tipi di entità selezionati dalle opzioni seguenti.
- Indirizzo
- Quartiere
- PopulatedPlace
- Codice postale1
- AdminDivision1
- AdminDivision2
- CountryRegion
Questi tipi di entità vengono ordinati dall'entità più specifica all'entità meno specifica. Quando vengono trovate entità di più tipi di entità, viene restituita solo l'entità più specifica. Ad esempio, se si specifica Address e AdminDistrict1 come tipi di entità e entità sono state trovate per entrambi i tipi, nella risposta vengono restituite solo le informazioni sull'entità Address.
Nome | Tipo | Descrizione |
---|---|---|
Address |
string |
|
AdminDivision1 |
string |
|
AdminDivision2 |
string |
|
CountryRegion |
string |
|
Neighborhood |
string |
|
PopulatedPlace |
string |
|
Postcode1 |
string |
UsageTypeEnum
L'uso migliore per il punto di geocodifica.
Ogni punto di geocodifica è definito come Route
punto, punto Display
o entrambi.
Usare Route
i punti se si sta creando una route per la posizione. Usare Display
i punti se viene visualizzata la posizione su una mappa. Ad esempio, se la posizione è un parco, un Route
punto può specificare un ingresso al parco in cui è possibile entrare con un'auto e un Display
punto può essere un punto che specifica il centro del parco.
Nome | Tipo | Descrizione |
---|---|---|
Display |
string |
|
Route |
string |