Condividi tramite


Search - Get Reverse Geocoding

Utilizzare per ottenere un indirizzo stradale e informazioni sulla posizione dalle coordinate di longitudine e latitudine.
L'API Get Reverse Geocoding è una richiesta HTTP GET usata per convertire una coordinata (ad esempio: 37.786505, -122.3862) in un indirizzo di strada 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à informazioni sull'indirizzo per una determinata coordinata.

GET {endpoint}/reverseGeocode?api-version=2026-01-01&coordinates={coordinates}
GET {endpoint}/reverseGeocode?api-version=2026-01-01&coordinates={coordinates}&resultTypes={resultTypes}&view={view}

Parametri dell'URI

Nome In Necessario Tipo Descrizione
endpoint
path True

string

api-version
query True

string

minLength: 1

Versione dell'API da usare per questa operazione.

coordinates
query True

number[]

Coordinate della posizione in cui si vuole invertire il codice geografico. Esempio: coordinate &=lon,lat

resultTypes
query

ReverseGeocodingResultTypeEnum[]

Specificare i tipi di entità desiderati nella risposta. Verranno restituiti solo i tipi specificati. Se non è possibile eseguire il mapping del punto 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.

  • Address
  • Quartiere
  • PopulatedPlace
  • Codice postale1
  • AdminDivision1
  • AdminDivision2
  • Paese/Regione

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 area/paese ISO 3166-1 Alpha-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 e per visualizzare le visualizzazioni disponibili, vedere viste supportate.

Intestazione della richiesta

Nome Necessario Tipo Descrizione
x-ms-client-id

string

Specifica quale account è destinato all'uso in combinazione con il modello di sicurezza di Azure AD. Rappresenta un ID unico per l'account Mappe di Azure e può essere recuperato dall'API Account del piano di gestione Mappe di Azure. Per maggiori informazioni sull'uso della sicurezza Microsoft Entra ID in Mappe di Azure, vedi Gestire l'autenticazione in Mappe di Azure.

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

GeocodingResponse

La richiesta ha avuto esito positivo.

Media Types: "application/geo+json", "application/json"

Other Status Codes

Azure.Core.Foundations.ErrorResponse

Risposta di errore imprevista.

Media Types: "application/geo+json", "application/json"

Intestazioni

x-ms-error-code: string

Sicurezza

AadToken

Questi sono i flussi Microsoft Entra OAuth 2.0. Quando abbinata al controllo Azure basato su ruolo può essere utilizzata per controllare l'accesso alle API REST di Mappe di Azure. I controlli di accesso basati su ruoli di Azure sono utilizzati per designare l'accesso a uno o più account o sottorisorse risorse di Mappe di Azure. Qualsiasi utente, gruppo o principale di servizio può ricevere l'accesso tramite un ruolo integrato o un ruolo personalizzato composto da uno o più permessi per Mappe di Azure API REST.\n\nPer implementare scenari, consigliamo di consultare i concetti di autenticazione . In sintesi, questa definizione di sicurezza fornisce una soluzione per modellare l'applicazione tramite oggetti in grado di controllo degli accessi su API e ambiti specifici.\n\n#### Note\n* Questa definizione di sicurezza richiede l'uso dell'intestazione x-ms-client-id per indicare a quale Mappe di Azure risorsa l'applicazione richiede accesso. Questo può essere acquisito dall'API di gestione Maps.\n* \nIl Authorization URL è specifico per l'istanza Azure cloud pubblico. I cloud sovrani hanno URL di autorizzazione unici e configurazioni Microsoft Entra ID. \n* \nIl controllo accessibile basato sul ruolo Azure viene configurato dal piano di gestione Azure tramite Azure portale, PowerShell, CLI, Azure SDK o API REST.\n* \nUtilizzo del Mappe di Azure Web SDK consente la configurazione di un'applicazione basata sulla configurazione per molteplici casi d'uso.\n* Per maggiori informazioni su Microsoft Identity Platform, vedi Microsoft Identity Platform panoramica.

Tipo: oauth2
Flow: implicit
URL di autorizzazione: https://login.microsoftonline.com/common/oauth2/authorize

Ambiti

Nome Descrizione
https://atlas.microsoft.com/.default

subscription-key

Questa è una chiave condivisa che viene fornita quando Crea un account Mappe di Azure nel portale Azure o utilizzando PowerShell, CLI, Azure SDK o API REST.\n\n Con questa chiave, qualsiasi applicazione può accedere a tutte le API REST. In altre parole, questa chiave può essere utilizzata come chiave master nell'account in cui vengono rilasciate.\n\n Per applicazioni pubblicamente esposte, la nostra raccomandazione è di utilizzare l'approccio confidential per accedere alle API REST Mappe di Azure modo che la tua chiave possa essere memorizzata in modo sicuro.

Tipo: apiKey
In: header

SAS Token

Questo token di firma di accesso condiviso viene creato dall'operazione List SAS sulla risorsa Mappe di Azure tramite il piano di gestione Azure tramite portale Azure, PowerShell, CLI, Azure SDK o API REST.\n\n Con questo token, qualsiasi applicazione è autorizzata ad accedere con Azure Controlli di accesso basati su ruoli e controllo sottile sulla scadenza, la velocità e la regione/i di utilizzo per il token specifico. In altre parole, il Token SAS può essere utilizzato per permettere alle applicazioni di controllare l'accesso in modo più sicuro rispetto alla chiave condivisa.\n\n Per applicazioni pubblicamente esposte, la nostra raccomandazione è di configurare una lista specifica di origini consentite sulla risorsa dell'account Map per limitare l'abuso di rendering e rinnovare regolarmente il token SAS.

Tipo: apiKey
In: header

Esempio

Search point -122.138681, 47.630358

Esempio di richiesta

GET {endpoint}/reverseGeocode?api-version=2026-01-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": [
            {
              "name": "Washington",
              "shortName": "WA"
            },
            {
              "name": "King County",
              "shortName": "King Co."
            }
          ],
          "formattedAddress": "15127 NE 24th St, Redmond, Washington 98052",
          "streetName": "NE 24th St",
          "streetNumber": "15127",
          "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

AddressAdminDistrictsItem

Nome della suddivisione nel paese o nell'area geografica per un indirizzo.

AddressCountryRegion

Paese o regione con il suo nome e codice ISO.

Azure.Core.Foundations.Error

Oggetto error.

Azure.Core.Foundations.ErrorResponse

Risposta contenente i dettagli dell'errore.

Azure.Core.Foundations.InnerError

Oggetto contenente informazioni più specifiche sull'errore. Secondo le linee guida Azure REST API - https://aka.ms/AzureRestApiGuidelines#handling-errors.

CalculationMethodEnum

Metodo usato per calcolare il punto di geocodifica.

ConfidenceEnum

Il livello di attendibilità 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.

FeatureCollectionEnum

Specifica il tipo di GeoJSON. L'unico tipo di oggetto supportato è FeatureCollection. Per altre informazioni, vedere RFC 7946.

FeaturesItem

Un oggetto caratteristica.

FeaturesItemProperties

Proprietà della caratteristica.

FeatureTypeEnum

Il tipo di una funzionalità deve essere Feature.

GeocodePointsItem

Un punto di geocodifica.

GeocodingResponse

Questo oggetto viene restituito da una chiamata geocodifica riuscita

GeoJsonObjectType

Specifica il tipo di GeoJSON. Deve essere uno dei nove tipi di oggetto GeoJSON validi: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature e FeatureCollection.

GeoJsonPoint

Tipo geometry GeoJSON Point valido. Per informazioni dettagliate, vedere RFC 7946.

Intersection

Indirizzo del risultato.

MatchCodesEnum

Un enum che rappresenta il codice di corrispondenza.

ReverseGeocodingResultTypeEnum

Un enum che rappresenta il tipo di risultato di geocodifica inversa.

UsageTypeEnum

Un enum che rappresenta il tipo di uso.

Address

Indirizzo del risultato

Nome Tipo Descrizione
addressLine

string

AddressLine che include il nome della via e il numero civico

adminDistricts

AddressAdminDistrictsItem[]

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

AddressCountryRegion

Paese o regione con il suo nome e codice ISO.

formattedAddress

string

Proprietà dell'indirizzo formattato

intersection

Intersection

Indirizzo del risultato.

locality

string

Proprietà della località

neighborhood

string

Proprietà del quartiere

postalCode

string

Proprietà del codice postale

streetName

string

Il nome della via da formattedAddress

streetNumber

string

Il numero nella via, se disponibile, da formattedAddress

AddressAdminDistrictsItem

Nome della suddivisione nel paese o nell'area geografica per un indirizzo.

Nome Tipo Descrizione
name

string

Nome per il campo adminDistrict corrispondente, Per adminDistrict[0], questo potrebbe essere il nome completo dello stato, ad esempio Washington, Per adminDistrict[1], potrebbe trattarsi del nome completo della contea

shortName

string

Nome breve per il campo adminDistrict corrispondente, Per adminDistrict[0], questo potrebbe essere il nome breve dello stato, ad esempio WA, Per adminDistrict[1], questo potrebbe essere il nome breve della contea

AddressCountryRegion

Paese o regione con il suo nome e codice ISO.

Nome Tipo Descrizione
ISO

string

ISO del paese/area geografica

name

string

nome del paese/area geografica

Azure.Core.Foundations.Error

Oggetto error.

Nome Tipo Descrizione
code

string

Uno di un set definito dal server di codici di errore.

details

Azure.Core.Foundations.Error[]

Matrice di dettagli sugli errori specifici che hanno causato l'errore segnalato.

innererror

Azure.Core.Foundations.InnerError

Oggetto contenente informazioni più specifiche dell'oggetto corrente sull'errore.

message

string

Rappresentazione leggibile dell'errore.

target

string

Destinazione dell'errore.

Azure.Core.Foundations.ErrorResponse

Risposta contenente i dettagli dell'errore.

Nome Tipo Descrizione
error

Azure.Core.Foundations.Error

Oggetto error.

Azure.Core.Foundations.InnerError

Oggetto contenente informazioni più specifiche sull'errore. Secondo le linee guida Azure REST API - https://aka.ms/AzureRestApiGuidelines#handling-errors.

Nome Tipo Descrizione
code

string

Uno di un set definito dal server di codici di errore.

innererror

Azure.Core.Foundations.InnerError

Errore interno.

CalculationMethodEnum

Metodo usato per calcolare il punto di geocodifica.

Valore Descrizione
Interpolation

Il punto di geocodifica è stato abbinato a un punto su una strada utilizzando l'interpolazione.

InterpolationOffset

Il punto di geocodifica è stato abbinato a un punto di una strada utilizzando l'interpolazione con uno scostamento aggiuntivo per spostare il punto sul lato della strada.

Parcel

Il punto di geocodifica è stato abbinato al centro di una particella.

Rooftop

Il punto di geocodifica è stato abbinato al tetto di un edificio.

ConfidenceEnum

Il livello di attendibilità 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.

Valore Descrizione
High

Se l'attendibilità è impostata su High, sono state trovate una o più corrispondenze forti. Più High corrispondenze di attendibilità vengono ordinate in ordine di classificazione in base all'importanza, se applicabile. Ad esempio, i punti di riferimento hanno importanza, ma gli indirizzi no.

Se una richiesta include una posizione o una vista, la classificazione potrebbe cambiare in modo appropriato. Ad esempio, una query di posizione per "Parigi" restituisce "Parigi, Francia" e "Parigi, TX" entrambi con High sicurezza. "Parigi, Francia" è sempre al primo posto in base all'importanza, a meno che la posizione di un utente non indichi che l'utente si trova a Parigi, Texas o molto vicino a essa, o la visualizzazione della mappa indichi che l'utente sta effettuando una ricerca in quell'area.

Medium

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ò essere in grado di 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 Medium e il codice di corrispondenza viene impostato su UpHierarchy per specificare che non è possibile corrispondere a tutte le informazioni e ha dovuto eseguire la ricerca verso l'alto nella gerarchia.

Se le informazioni sulla posizione nella query sono ambigue e non sono disponibili informazioni aggiuntive per classificare le posizioni, ad esempio la posizione dell'utente o l'importanza relativa della posizione, l'attendibilità viene impostata su Medium. Ad esempio, una query di posizione per "148th Ave, Bellevue" può restituire "148th Ave SE" e "148th Ave NE" entrambi con Medium sicurezza.

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à venga impostata su Medium. Ad esempio, se viene fornito un indirizzo, ma non viene trovata una corrispondenza per il numero civico, è possibile che venga restituito il risultato della geocodifica con un tipo di entità Roadblock.

Low

Low

FeatureCollectionEnum

Specifica il tipo di GeoJSON. L'unico tipo di oggetto supportato è FeatureCollection. Per altre informazioni, vedere RFC 7946.

Valore Descrizione
FeatureCollection

Specifica il tipo di oggetto GeoJSONFeatureCollection.

FeaturesItem

Un oggetto caratteristica.

Nome Tipo Descrizione
bbox

number[] (double)

Riquadro. Proiezione usata - EPSG:3857. Per informazioni dettagliate, vedere RFC 7946.

geometry

GeoJsonPoint

Tipo geometry GeoJSON Point valido. Per informazioni dettagliate, vedere RFC 7946.

id

string

ID per la funzionalità restituita

properties

FeaturesItemProperties

Proprietà della caratteristica.

type

FeatureTypeEnum

Il tipo di una funzionalità deve essere Feature.

FeaturesItemProperties

Proprietà della caratteristica.

Nome Tipo Descrizione
address

Address

Indirizzo del risultato

confidence

ConfidenceEnum

Il livello di attendibilità 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

GeocodePointsItem[]

Raccolta di punti di geocodice che differiscono in base alla modalità di calcolo e all'uso suggerito.

matchCodes

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ù di una posizione geografica per le informazioni sulla posizione e che il servizio di geocodice non disponeva di una gerarchia di ricerca 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 geocodifica doveva cercare nella gerarchia superiore e trovare più corrispondenze a tale livello. Un esempio di Ambiguous e UpHierarchy risultato è quando si forniscono informazioni complete sull'indirizzo, ma il servizio di geocodice non riesce a individuare una corrispondenza per l'indirizzo stradale e restituisce invece informazioni per più di un valore RoadBlock.

I valori possibili sono:

Good: la posizione ha una sola corrispondenza o tutte le corrispondenze restituite vengono considerate corrispondenze complesse. Ad esempio, una query per New York restituisce diverse corrispondenze valide.

Ambiguous: la posizione è una delle 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 della 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 UpHierarchy con un tipo di entità RoadBlock.

type

string

Uno di: * Indirizzo * Blocco stradale * Intersezione stradale * Quartiere * Luogo abitato * Codice postale1 * DivisioneAmministrativa1 * DivisioneAmministrativa2 * RegionePaese

FeatureTypeEnum

Il tipo di una funzionalità deve essere Feature.

Valore Descrizione
Feature

Specifica il tipo di oggetto Feature GeoJSON.

GeocodePointsItem

Un punto di geocodifica.

Nome Tipo Descrizione
calculationMethod

CalculationMethodEnum

Metodo usato per calcolare il punto di geocodifica.

geometry

GeoJsonPoint

Tipo geometry GeoJSON Point valido. Per informazioni dettagliate, vedere RFC 7946.

usageTypes

UsageTypeEnum[]

Uso ottimale per il punto di geocodifica. Ogni punto di geocodice viene definito come punto Route, un punto Display o entrambi. Usare Route punti se si sta creando una route per la posizione. Usare Display punti se viene visualizzata la posizione in una mappa. Ad esempio, se la posizione è un parco, un punto di Route può specificare un ingresso al parco in cui è possibile entrare con un'auto e un punto Display può essere un punto che specifica il centro del parco.

GeocodingResponse

Questo oggetto viene restituito da una chiamata geocodifica riuscita

Nome Tipo Descrizione
features

FeaturesItem[]

Una serie di funzionalità restituite dalla query.

nextLink

string

è il collegamento alla pagina successiva delle funzionalità restituite. Se si tratta dell'ultima pagina, nessun campo.

type

FeatureCollectionEnum

Specifica il tipo di GeoJSON. L'unico tipo di oggetto supportato è FeatureCollection. Per altre informazioni, vedere RFC 7946.

GeoJsonObjectType

Specifica il tipo di GeoJSON. Deve essere uno dei nove tipi di oggetto GeoJSON validi: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature e FeatureCollection.

Valore Descrizione
Point

GeoJSON Point geometria.

MultiPoint

GeoJSON MultiPoint geometria.

LineString

GeoJSON LineString geometria.

MultiLineString

GeoJSON MultiLineString geometria.

Polygon

GeoJSON Polygon geometria.

MultiPolygon

GeoJSON MultiPolygon geometria.

GeometryCollection

GeoJSON GeometryCollection geometria.

Feature

Oggetto GeoJSON Feature.

FeatureCollection

Oggetto GeoJSON FeatureCollection.

GeoJsonPoint

Tipo geometry GeoJSON Point valido. Per informazioni dettagliate, vedere RFC 7946.

Nome Tipo Descrizione
bbox

number[] (double)

Riquadro. Proiezione usata - EPSG:3857. Per informazioni dettagliate, vedere RFC 7946.

coordinates

number[] (double)

Un Position è una matrice di numeri con due o più elementi. I primi due elementi sono longitudine e latitudine, esattamente in tale ordine. altitudine/elevazione è un terzo elemento facoltativo. Per informazioni dettagliate, vedere RFC 7946.

type string:

Point

Specifica il tipo di GeoJSON. Deve essere uno dei nove tipi di oggetto GeoJSON validi: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature e FeatureCollection.

Intersection

Indirizzo del risultato.

Nome Tipo Descrizione
baseStreet

string

Strada principale per la posizione.

displayName

string

Nome completo dell'intersezione.

intersectionType

string

Tipo di intersezione.

secondaryStreet1

string

La prima strada che si interseca.

secondaryStreet2

string

In caso affermativo, la seconda strada intersecante.

MatchCodesEnum

Un enum che rappresenta il codice di corrispondenza.

Valore Descrizione
Good

Bene

Ambiguous

Ambiguous

UpHierarchy

UpHierarchy

ReverseGeocodingResultTypeEnum

Un enum che rappresenta il tipo di risultato di geocodifica inversa.

Valore Descrizione
Address

Address

Neighborhood

Quartiere

PopulatedPlace

PopulatedPlace

Postcode1

Codice postale1

AdminDivision1

AdminDivision1

AdminDivision2

AdminDivision2

CountryRegion

Paese/Regione

UsageTypeEnum

Un enum che rappresenta il tipo di uso.

Valore Descrizione
Display

Display

Route

Itinerario