Search - Get Reverse Geocoding
Umożliwia uzyskanie adresu ulicy i informacji o lokalizacji na podstawie współrzędnych długości i szerokości geograficznej.
Interfejs API Get Reverse Geocoding to żądanie GET HTTP używane do tłumaczenia współrzędnych (na przykład: 37.786505, -122.3862) na zrozumiały dla człowieka adres ulicy. Przydatne w aplikacjach do śledzenia, w których otrzymujesz kanał informacyjny GPS z urządzenia lub elementu zawartości i chcesz znać adres skojarzony ze współrzędnymi. Ten punkt końcowy zwróci informacje o adresie dla danej współrzędnej.
GET {endpoint}/reverseGeocode?api-version=2026-01-01&coordinates={coordinates}
GET {endpoint}/reverseGeocode?api-version=2026-01-01&coordinates={coordinates}&resultTypes={resultTypes}&view={view}
Parametry identyfikatora URI
| Nazwa | W | Wymagane | Typ | Opis |
|---|---|---|---|---|
|
endpoint
|
path | True |
string (uri) |
Nazwa hosta usługi Azure Maps. Użyj |
|
api-version
|
query | True |
string minLength: 1 |
Wersja interfejsu API do użycia dla tej operacji. |
|
coordinates
|
query | True |
number[] |
Współrzędne lokalizacji, w której chcesz odwrócić kod geograficzny. Przykład: współrzędne &=lon,lat |
|
result
|
query |
Określ typy jednostek, które mają być w odpowiedzi. Zostaną zwrócone tylko określone typy. Jeśli nie można zamapować punktu na określone typy jednostek, w odpowiedzi nie są zwracane żadne informacje o lokalizacji. Wartość domyślna to wszystkie możliwe jednostki. Rozdzielona przecinkami lista typów jednostek wybranych z następujących opcji.
Te typy jednostek są uporządkowane od najbardziej określonej jednostki do najmniej konkretnej jednostki. Gdy znaleziono jednostki o więcej niż jednym typie jednostki, zwracana jest tylko najbardziej określona jednostka. Jeśli na przykład określisz adres i adminDistrict1 jako typy jednostek i jednostki dla obu typów, w odpowiedzi zostanie zwrócona tylko informacja o jednostce Adres. |
||
|
view
|
query |
string |
Ciąg reprezentujący kod ISO 3166-1 Alfa-2 w regionie/kraju. Spowoduje to zmianę spornych geopolitycznych granic i etykiet w celu dopasowania ich do określonego regionu użytkownika. Domyślnie parametr Widok jest ustawiony na wartość "Auto", nawet jeśli nie zdefiniowano go w żądaniu. Aby uzyskać szczegółowe informacje, zobacz Obsługiwane widoki, aby uzyskać szczegółowe informacje i wyświetlić dostępne widoki. |
Nagłówek żądania
| Nazwa | Wymagane | Typ | Opis |
|---|---|---|---|
| x-ms-client-id |
string |
Określa, które konto jest przeznaczone do użycia w połączeniu z modelem bezpieczeństwa Azure AD. Reprezentuje unikalny identyfikator dla konta Azure Maps i można go pobrać z API konta Azure Maps management plane. Więcej informacji na temat korzystania z Microsoft Entra ID zabezpieczeń w Azure Maps można znaleźć w Manage authentication in Azure Maps. |
|
| Accept-Language |
string |
Język, w którym powinny być zwracane wyniki wyszukiwania. Aby uzyskać szczegółowe informacje, zobacz Obsługiwane języki. |
Odpowiedzi
| Nazwa | Typ | Opis |
|---|---|---|
| 200 OK |
Żądanie zakończyło się pomyślnie. Media Types: "application/geo+json", "application/json" |
|
| Other Status Codes |
Nieoczekiwana odpowiedź na błąd. Media Types: "application/geo+json", "application/json" Nagłówki x-ms-error-code: string |
Zabezpieczenia
AadToken
Są to przepływy Microsoft Entra OAuth 2.0. W połączeniu z Azure zarządzaniem dostępem opartym na rolach może być używany do kontroli dostępu do Azure Maps API REST. Kontrola dostępu oparta na rolach Azure służy do wyznaczania dostępu do jednego lub więcej kont zasobów lub podzasobów Azure Maps. Każdy użytkownik, grupa lub jednostka usługi mogą mieć dostęp za pośrednictwem wbudowanej roli lub roli niestandardowej składającej się z co najmniej jednego uprawnienia do interfejsów API REST usługi Azure Maps.
Aby zaimplementować scenariusze, zalecamy wyświetlenie koncepcji uwierzytelniania . Podsumowując, ta definicja zabezpieczeń zawiera rozwiązanie do modelowania aplikacji za pośrednictwem obiektów, które mogą kontrolować dostęp do określonych interfejsów API i zakresów.
Note
- Ta definicja zabezpieczeń wymaga użycia nagłówka
x-ms-client-idw celu wskazania, do którego zasobu usługi Azure Maps aplikacja żąda dostępu. Można to uzyskać za pomocą interfejsu API zarządzania usługami Maps. -
Authorization URLjest specyficzna dla wystąpienia chmury publicznej platformy Azure. Suwerenne chmury mają unikalne adresy URL autoryzacji oraz konfiguracje Microsoft Entra ID. - Kontrola dostępu oparta na rolach platformy Azure jest konfigurowana na podstawie płaszczyzny zarządzania platformy Azure za pośrednictwem witryny Azure Portal, programu PowerShell, interfejsu wiersza polecenia, zestawów AZURE SDK lub interfejsów API REST.
- Użycie zestawu Web SDK usługi Azure Maps umożliwia skonfigurowanie aplikacji na podstawie konfiguracji dla wielu przypadków użycia.
- Aby uzyskać więcej informacji na temat platformy tożsamości firmy Microsoft, zobacz Platforma tożsamości Microsoft overview.
Typ:
oauth2
Flow:
implicit
Adres URL autoryzacji:
https://login.microsoftonline.com/common/oauth2/authorize
Zakresy
| Nazwa | Opis |
|---|---|
| https://atlas.microsoft.com/.default |
subscription-key
Jest to klucz wspólny aprowizowany podczas tworzenie konta usługi Azure Maps w witrynie Azure Portal lub przy użyciu programu PowerShell, interfejsu wiersza polecenia, zestawów SDK platformy Azure lub interfejsu API REST.
Za pomocą tego klucza każda aplikacja może uzyskiwać dostęp do całego interfejsu API REST. Innymi słowy, ten klucz może służyć jako klucz główny na koncie, w którym są wystawiane.
W przypadku publicznie uwidocznionych aplikacji zalecamy użycie poufnych aplikacji klienckich podejście do uzyskiwania dostępu do interfejsów API REST usługi Azure Maps, aby klucz mógł być bezpiecznie przechowywany.
Typ:
apiKey
W:
header
SAS Token
Jest to token sygnatury dostępu współdzielonego tworzony na podstawie operacji List SAS na zasobie usługi Azure Maps za pośrednictwem płaszczyzny zarządzania platformy Azure za pośrednictwem witryny Azure Portal, programu PowerShell, interfejsu wiersza polecenia, zestawów AZURE SDK lub interfejsów API REST.
Dzięki temu tokenowi każda aplikacja jest autoryzowana do uzyskiwania dostępu za pomocą kontroli dostępu opartej na rolach platformy Azure i szczegółowej kontroli wygaśnięcia, szybkości i regionów użycia dla określonego tokenu. Innymi słowy, token SAS może służyć do umożliwienia aplikacjom kontrolowania dostępu w sposób bardziej zabezpieczony niż klucz wspólny.
W przypadku publicznie uwidocznionych aplikacji zalecamy skonfigurowanie określonej listy dozwolonych źródeł w zasobie Mapowanie konta w celu ograniczenia nadużyć renderowania i regularnego odnawiania tokenu SAS.
Typ:
apiKey
W:
header
Przykłady
Search point -122.138681, 47.630358
Przykładowe żądanie
GET https://atlas.microsoft.com/reverseGeocode?api-version=2026-01-01&coordinates=-122.138681,47.630358
Przykładowa odpowiedź
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
]
}
]
}
Definicje
| Nazwa | Opis |
|---|---|
| Address |
Adres wyniku |
|
Address |
Nazwa poddziału w kraju lub regionie dla adresu. |
|
Address |
Kraj lub region wraz z jego nazwą i kodem ISO. |
|
Azure. |
Obiekt błędu. |
|
Azure. |
Odpowiedź zawierająca szczegóły błędu. |
|
Azure. |
Obiekt zawierający bardziej szczegółowe informacje o błędzie. Zgodnie z Azure wytycznymi API REST - https://aka.ms/AzureRestApiGuidelines#handling-errors. |
|
Calculation |
Metoda, która została użyta do obliczenia punktu kodu geograficznego. |
|
Confidence |
Poziom pewności, że wynik geokodowanej lokalizacji jest zgodny. Użyj tej wartości z kodem dopasowania, aby określić więcej pełnych informacji o dopasowaniu. Pewność lokalizacji zakodowanej geograficznie opiera się na wielu czynnikach, w tym względnym znaczeniu lokalizacji zakodowanej geograficznie i lokalizacji użytkownika, jeśli zostanie określona. |
|
Feature |
Określa typ |
|
Features |
Obiekt cechowy. |
|
Features |
Właściwości cechy. |
|
Feature |
Typ funkcji musi mieć wartość Funkcja. |
|
Geocode |
Punkt geokodowy. |
|
Geocoding |
Ten obiekt jest zwracany z pomyślnego wywołania geokodowania |
|
Geo |
Określa typ |
|
Geo |
Prawidłowy typ geometrii |
| Intersection |
Adres wyniku. |
|
Match |
Enum reprezentujące kod meczu. |
|
Reverse |
Enum reprezentujące odwrotny typ wyniku geokodowania. |
|
Usage |
Enum reprezentujące typ użycia. |
Address
Adres wyniku
| Nazwa | Typ | Opis |
|---|---|---|
| addressLine |
string |
AddressLine, który zawiera nazwę ulicy i numer |
| adminDistricts |
Nazwa poddziału w kraju lub regionie dla adresu. Ten element jest zwykle traktowany jako podsieć administracyjna pierwszego zamówienia, ale w niektórych przypadkach zawiera również drugą, trzecią lub czwartą podział kolejności w kraju, zależności lub regionie. |
|
| countryRegion |
Kraj lub region wraz z jego nazwą i kodem ISO. |
|
| formattedAddress |
string |
Właściwość Sformatowany adres |
| intersection |
Adres wyniku. |
|
| locality |
string |
Właściwość lokalna |
| neighborhood |
string |
Nieruchomość w sąsiedztwie |
| postalCode |
string |
Właściwość Kod pocztowy |
| streetName |
string |
Nazwa ulicy z formattedAddress |
| streetNumber |
string |
Numer na ulicy, jeśli jest dostępny, from formattedAddress |
AddressAdminDistrictsItem
Nazwa poddziału w kraju lub regionie dla adresu.
| Nazwa | Typ | Opis |
|---|---|---|
| name |
string |
Nazwa odpowiedniego pola adminDistrict, For adminDistrict[0], może to być pełna nazwa stanu, takiego jak Washington, For adminDistrict[1], może to być pełna nazwa powiatu |
| shortName |
string |
Krótka nazwa odpowiedniego pola adminDistrict, For adminDistrict[0], może to być krótka nazwa stanu, takiego jak WA, For adminDistrict[1], może to być krótka nazwa hrabstwa |
AddressCountryRegion
Kraj lub region wraz z jego nazwą i kodem ISO.
| Nazwa | Typ | Opis |
|---|---|---|
| ISO |
string |
ISO kraju/regionu |
| name |
string |
nazwa kraju/regionu |
Azure.Core.Foundations.Error
Obiekt błędu.
| Nazwa | Typ | Opis |
|---|---|---|
| code |
string |
Jeden z zdefiniowanych przez serwer zestaw kodów błędów. |
| details |
Tablica szczegółów dotyczących określonych błędów, które doprowadziły do tego zgłoszonego błędu. |
|
| innererror |
Obiekt zawierający bardziej szczegółowe informacje niż bieżący obiekt o błędzie. |
|
| message |
string |
Czytelna dla człowieka reprezentacja błędu. |
| target |
string |
Element docelowy błędu. |
Azure.Core.Foundations.ErrorResponse
Odpowiedź zawierająca szczegóły błędu.
| Nazwa | Typ | Opis |
|---|---|---|
| error |
Obiekt błędu. |
Azure.Core.Foundations.InnerError
Obiekt zawierający bardziej szczegółowe informacje o błędzie. Zgodnie z Azure wytycznymi API REST - https://aka.ms/AzureRestApiGuidelines#handling-errors.
| Nazwa | Typ | Opis |
|---|---|---|
| code |
string |
Jeden z zdefiniowanych przez serwer zestaw kodów błędów. |
| innererror |
Błąd wewnętrzny. |
CalculationMethodEnum
Metoda, która została użyta do obliczenia punktu kodu geograficznego.
| Wartość | Opis |
|---|---|
| Interpolation |
Punkt geokodowy został dopasowany do punktu na drodze za pomocą interpolacji. |
| InterpolationOffset |
Punkt geokodowy został dopasowany do punktu na drodze za pomocą interpolacji z dodatkowym przesunięciem w celu przesunięcia punktu na bok ulicy. |
| Parcel |
Punkt geokodowania został dopasowany do środka działki. |
| Rooftop |
Punkt geokodowy został dopasowany do dachu budynku. |
ConfidenceEnum
Poziom pewności, że wynik geokodowanej lokalizacji jest zgodny. Użyj tej wartości z kodem dopasowania, aby określić więcej pełnych informacji o dopasowaniu.
Pewność lokalizacji zakodowanej geograficznie opiera się na wielu czynnikach, w tym względnym znaczeniu lokalizacji zakodowanej geograficznie i lokalizacji użytkownika, jeśli zostanie określona.
| Wartość | Opis |
|---|---|
| High |
Jeśli poziom ufności jest ustawiony na Jeśli żądanie zawiera lokalizację lub widok, klasyfikacja może się odpowiednio zmienić. Na przykład zapytanie o lokalizację "Paryż" zwraca z pewnością "Paryż, Francja" i "Paryż, Teksas". |
| Medium |
W niektórych sytuacjach zwrócone dopasowanie może nie być na tym samym poziomie, co informacje podane w żądaniu. Na przykład żądanie może zawierać informacje adresowe, a usługa geokodowania może być w stanie dopasować tylko kod pocztowy. W takim przypadku, jeśli usługa geokodowania ma pewność, że kod pocztowy jest zgodny z danymi, ufność jest ustawiana na Jeśli informacje o lokalizacji w zapytaniu są niejednoznaczne i nie ma dodatkowych informacji umożliwiających uszeregowanie lokalizacji (takich jak lokalizacja użytkownika lub względna ważność lokalizacji), ufność jest ustawiana na Jeśli informacje o lokalizacji w zapytaniu nie zawierają wystarczających informacji do geokodowania określonej lokalizacji, może zostać zwrócona mniej dokładna wartość lokalizacji, a ufność zostanie ustawiona na |
| Low |
Low |
FeatureCollectionEnum
Określa typ GeoJSON. Jedynym obsługiwanym typem obiektu jest FeatureCollection. Aby uzyskać więcej informacji, zobacz RFC 7946.
| Wartość | Opis |
|---|---|
| FeatureCollection |
Określa typ obiektu |
FeaturesItem
Obiekt cechowy.
| Nazwa | Typ | Opis |
|---|---|---|
| bbox |
number[] (double) |
Obwiedni. Używane projekcje — EPSG:3857. Aby uzyskać szczegółowe informacje, zobacz RFC 7946. |
| geometry |
Prawidłowy typ geometrii |
|
| id |
string |
Identyfikator zwracanej funkcji |
| properties |
Właściwości cechy. |
|
| type |
Typ funkcji musi mieć wartość Funkcja. |
FeaturesItemProperties
Właściwości cechy.
| Nazwa | Typ | Opis |
|---|---|---|
| address |
Adres wyniku |
|
| confidence |
Poziom pewności, że wynik geokodowanej lokalizacji jest zgodny. Użyj tej wartości z kodem dopasowania, aby określić więcej pełnych informacji o dopasowaniu. Pewność lokalizacji zakodowanej geograficznie opiera się na wielu czynnikach, w tym względnym znaczeniu lokalizacji zakodowanej geograficznie i lokalizacji użytkownika, jeśli zostanie określona. |
|
| geocodePoints |
Kolekcja punktów kodu geograficznego, które różnią się sposobem ich obliczania i sugerowanym użyciem. |
|
| matchCodes |
Co najmniej jedna zgodna wartość kodu reprezentująca poziom geokodowania dla każdej lokalizacji w odpowiedzi. Na przykład lokalizacja geokodowana z kodami dopasowania Podobnie lokalizacja geokodowana z kodami dopasowania Możliwe wartości to:
|
|
| type |
string |
Jeden z: * Adres * RoadBlock * RoadIntersection * Neighborhood * PopulatedPlace * Kod pocztowy 1 * AdminDivision1 * AdminDivision2 * CountryRegion |
FeatureTypeEnum
Typ funkcji musi mieć wartość Funkcja.
| Wartość | Opis |
|---|---|
| Feature |
Określa typ obiektu funkcji |
GeocodePointsItem
Punkt geokodowy.
| Nazwa | Typ | Opis |
|---|---|---|
| calculationMethod |
Metoda, która została użyta do obliczenia punktu kodu geograficznego. |
|
| geometry |
Prawidłowy typ geometrii |
|
| usageTypes |
Najlepsze zastosowanie dla punktu kodu geograficznego. Każdy punkt kodu geograficznego jest definiowany jako punkt |
GeocodingResponse
Ten obiekt jest zwracany z pomyślnego wywołania geokodowania
| Nazwa | Typ | Opis |
|---|---|---|
| features |
Z zapytania powrócił szereg cech. |
|
| nextLink |
string |
Jest to link do następnej strony zwróconych funkcji. Jeśli jest to ostatnia strona, nie ma tego pola. |
| type |
Określa typ |
GeoJsonObjectType
Określa typ GeoJSON. Musi być jednym z dziewięciu prawidłowych typów obiektów GeoJSON — Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature i FeatureCollection.
| Wartość | Opis |
|---|---|
| Point |
|
| MultiPoint |
|
| LineString |
|
| MultiLineString |
|
| Polygon |
|
| MultiPolygon |
|
| GeometryCollection |
|
| Feature |
|
| FeatureCollection |
|
GeoJsonPoint
Prawidłowy typ geometrii GeoJSON Point. Aby uzyskać szczegółowe informacje, zobacz RFC 7946.
| Nazwa | Typ | Opis |
|---|---|---|
| bbox |
number[] (double) |
Obwiedni. Używane projekcje — EPSG:3857. Aby uzyskać szczegółowe informacje, zobacz RFC 7946. |
| coordinates |
number[] (double) |
|
| type |
string:
Point |
Określa typ |
Intersection
Adres wyniku.
| Nazwa | Typ | Opis |
|---|---|---|
| baseStreet |
string |
Główna ulica dla lokalizacji. |
| displayName |
string |
Pełna nazwa skrzyżowania. |
| intersectionType |
string |
Typ skrzyżowania. |
| secondaryStreet1 |
string |
Pierwsza przecinając ulicę. |
| secondaryStreet2 |
string |
Jeśli istnieje, druga przecinając ulicę. |
MatchCodesEnum
Enum reprezentujące kod meczu.
| Wartość | Opis |
|---|---|
| Good |
Dobrze |
| Ambiguous |
Dwuznaczny |
| UpHierarchy |
UpHierarchy |
ReverseGeocodingResultTypeEnum
Enum reprezentujące odwrotny typ wyniku geokodowania.
| Wartość | Opis |
|---|---|
| Address |
Address |
| Neighborhood |
Sąsiedztwo |
| PopulatedPlace |
Zapełnione miejsce |
| Postcode1 |
Kod pocztowy1 |
| AdminDivision1 |
AdminDivision1 |
| AdminDivision2 |
AdminDivision2 |
| CountryRegion |
CountryRegion |
UsageTypeEnum
Enum reprezentujące typ użycia.
| Wartość | Opis |
|---|---|
| Display |
Display |
| Route |
Marszruta |