Udostępnij za pośrednictwem


Search - Get Search Address Reverse

Użyj polecenia , aby uzyskać informacje o adresie ulicy i lokalizacji ze współrzędnych szerokości i długości geograficznej.
Interfejs API Get Search Address Reverse to żądanie http GET, które zwraca adres ulicy lub lokalizację, gdy dana współrzędna szerokości i długości geograficznej.

Czasami trzeba przetłumaczyć współrzędną (na przykład 37.786505, -122.3862) na zrozumiały dla człowieka adres ulicy. Najczęściej jest to potrzebne w aplikacjach śledzących, w których otrzymujesz kanał informacyjny GPS z urządzenia lub zasobu i chcesz wiedzieć, jaki adres znajduje się współrzędna. Ten punkt końcowy zwróci informacje o adresie dla danej współrzędnej.

GET https://atlas.microsoft.com/search/address/reverse/{format}?api-version=1.0&query={query}
GET https://atlas.microsoft.com/search/address/reverse/{format}?api-version=1.0&query={query}&language={language}&returnSpeedLimit={returnSpeedLimit}&heading={heading}&radius={radius}&number={number}&returnRoadUse={returnRoadUse}&roadUse={roadUse}&allowFreeformNewline={allowFreeformNewline}&returnMatchType={returnMatchType}&entityType={entityType}&view={view}

Parametry identyfikatora URI

Nazwa W Wymagane Typ Opis
format
path True

ResponseFormat

Żądany format odpowiedzi. Wartość może być json lub xml.

api-version
query True

string

Numer wersji interfejsu API usługi Azure Maps.

query
query True

number[]

Odpowiednie zapytanie określone jako ciąg rozdzielony przecinkami składające się z szerokości geograficznej, po której następuje długość geograficzna, np. "47.641268,-122.125679".

allowFreeformNewline
query

boolean

Format nowych linii w sformatowanych adresach.

Jeśli wartość true, adres będzie zawierać nowe linie. Jeśli wartość false, nowe linie zostaną przekonwertowane na przecinki.

entityType
query

GeographicEntityType

Określa poziom filtrowania wykonywanego w lokalizacjach geograficznych. Zawęża wyszukiwanie określonych typów jednostek geograficznych, np. zwraca tylko gminy. Wynikowa odpowiedź będzie zawierać identyfikator geografii, a także dopasowany typ jednostki. Jeśli podasz więcej niż jedną jednostkę jako listę rozdzielaną przecinkami, punkt końcowy zwróci "najmniejszą dostępną jednostkę". Zwrócony identyfikator geometrii może służyć do uzyskiwania geometrii tej lokalizacji geograficznej za pomocą interfejsu API Uzyskiwanie wielokąta wyszukiwania. Następujące parametry są ignorowane, gdy parametr entityType jest ustawiony:

  • nagłówek
  • liczba
  • returnRoadUse
  • returnSpeedLimit
  • roadUse
  • returnMatchType
heading
query

integer

minimum: -360
maximum: 360

Kierunek pojazdu w stopniach, do podróży wzdłuż segmentu drogi. 0 to Północ, 90 to Wschód i tak dalej, wartości wahają się od -360 do 360. Precyzja może obejmować maksymalnie jedno miejsce dziesiętne

language
query

string

Język, w którym powinny być zwracane wyniki wyszukiwania. Powinien być jednym z obsługiwanych tagów języka IETF, bez uwzględniania wielkości liter. Jeśli dane w określonym języku nie są dostępne dla określonego pola, używany jest język domyślny.

Aby uzyskać szczegółowe informacje, zobacz Obsługiwane języki.

number
query

string

Numer ulicy jako ciąg. Jeśli liczba jest wysyłana wraz z żądaniem, odpowiedź może zawierać bok ulicy (w lewo/w prawo), a także położenie przesunięcia dla tej liczby

radius
query

integer

Promień w metrach dla wyników, które mają być ograniczone do zdefiniowanego obszaru

returnMatchType
query

boolean

Dołącz informacje o typie dopasowania geokodera osiągniętego w odpowiedzi.

returnRoadUse
query

boolean

Boolowski. Aby włączyć powrót tablicy użycia dróg dla odwrotnych geokodów na poziomie ulicy

returnSpeedLimit
query

boolean

Boolowski. Aby włączyć powrót limitu prędkości zaksięgowania

roadUse
query

RoadUseType[]

Aby ograniczyć odwrotne kody geograficzne do określonego typu użycia dróg. Tablica użycia dróg dla odwrotnych kodów geograficznych może być co najmniej jedna z funkcji LimitedAccess, Arterial, Terminal, Ramp, Rotary, LocalStreet

view
query

LocalizedMapView

Parametr View (nazywany również parametrem "region użytkownika") umożliwia wyświetlanie poprawnych map dla określonego kraju/regionu dla regionów spornych geopolitycznie. Różne kraje/regiony mają różne widoki takich regionów, a parametr View umożliwia aplikacji zgodność z widokiem wymaganym przez kraj/region, który będzie obsługiwać aplikacja. Domyślnie parametr Widok jest ustawiony na wartość "Unified", nawet jeśli nie zdefiniowano go w żądaniu. Twoim zadaniem jest określenie lokalizacji użytkowników, a następnie poprawne ustawienie parametru Wyświetl dla tej lokalizacji. Alternatywnie możesz ustawić opcję "View=Auto", która zwróci dane mapy na podstawie adresu IP żądania. Parametr View w usłudze Azure Maps musi być używany zgodnie z obowiązującymi przepisami, w tym z przepisami dotyczącymi mapowania kraju/regionu, w którym udostępniane są mapy, obrazy i inne dane oraz zawartość innych firm, do których masz uprawnienia dostępu za pośrednictwem usługi Azure Maps. Przykład: view=IN.

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 zabezpieczeń Microsoft Entra ID. Reprezentuje unikatowy identyfikator konta usługi Azure Maps i można go pobrać z interfejsu API konta płaszczyzny zarządzania usługi Azure Maps. Aby użyć zabezpieczeń identyfikatora Entra firmy Microsoft w usłudze Azure Maps, zobacz następujące artykuły , aby uzyskać wskazówki.

Odpowiedzi

Nazwa Typ Opis
200 OK

ReverseSearchAddressResult

OK

Other Status Codes

ErrorResponse

Wystąpił nieoczekiwany błąd.

Zabezpieczenia

AADToken

Są to przepływy Microsoft Entra OAuth 2.0. Po połączeniu z dostępem opartym na rolach platformy Azure kontroli może służyć do kontrolowania dostępu do interfejsów API REST usługi Azure Maps. Mechanizmy kontroli dostępu opartej na rolach platformy Azure służą do wyznaczania dostępu do co najmniej jednego konta zasobu usługi Azure Maps lub zasobów podrzędnych. 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.

Uwaga

  • Ta definicja zabezpieczeń wymaga użycia nagłówka x-ms-client-id w celu wskazania, do którego zasobu usługi Azure Maps aplikacja żąda dostępu. Można to uzyskać za pomocą interfejsu API zarządzania Maps.
  • Authorization URL jest specyficzna dla wystąpienia chmury publicznej platformy Azure. Suwerenne chmury mają unikatowe adresy URL autoryzacji i konfiguracje identyfikatorów Entra firmy Microsoft.
  • 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 Microsoft identity platform overview.

Typ: oauth2
Flow: implicit
Adres URL autoryzacji: https://login.microsoftonline.com/common/oauth2/authorize

Zakresy

Nazwa Opis
https://atlas.microsoft.com/.default 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: query

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

Searches addresses for coordinates 37.337,-121.89

Przykładowe żądanie

GET https://atlas.microsoft.com/search/address/reverse/json?api-version=1.0&query=37.337,-121.89

Przykładowa odpowiedź

{
  "summary": {
    "queryTime": 5,
    "numResults": 1
  },
  "addresses": [
    {
      "address": {
        "streetNumber": "31",
        "routeNumbers": [],
        "streetName": "N 2nd St",
        "streetNameAndNumber": "31 N 2nd St",
        "countryCode": "US",
        "countrySubdivisionCode": "CA",
        "countrySubdivisionName": "California",
        "municipality": "San Jose",
        "postalCode": "95113",
        "country": "United States of America",
        "countryCodeISO3": "USA",
        "freeformAddress": "31 N 2nd St, San Jose CA 95113",
        "extendedPostalCode": "951131217"
      },
      "position": "37.337090,-121.889820"
    }
  ]
}

Definicje

Nazwa Opis
Address

Adres wyniku

BoundingBoxCompassNotation

Pole ograniczenia lokalizacji.

Entity

Źródło typu jednostki pola ograniczenia. W przypadku odwrotnego geokodowania jest to zawsze równe pozycji.

ErrorAdditionalInfo

Dodatkowe informacje o błędzie zarządzania zasobami.

ErrorDetail

Szczegóły błędu.

ErrorResponse

Odpowiedź na błąd

GeographicEntityType

Typ jednostki Geografia. Prezentuj tylko wtedy, gdy zażądano parametru entityType i jest dostępny.

LatLongPairAbbreviated

Lokalizacja reprezentowana jako szerokość geograficzna i długość geograficzna przy użyciu krótkich nazw "lat" & "lon".

LocalizedMapView

Parametr View (nazywany również parametrem "region użytkownika") umożliwia wyświetlanie poprawnych map dla określonego kraju/regionu dla regionów spornych geopolitycznie. Różne kraje/regiony mają różne widoki takich regionów, a parametr View umożliwia aplikacji zgodność z widokiem wymaganym przez kraj/region, który będzie obsługiwać aplikacja. Domyślnie parametr Widok jest ustawiony na wartość "Unified", nawet jeśli nie zdefiniowano go w żądaniu. Twoim zadaniem jest określenie lokalizacji użytkowników, a następnie poprawne ustawienie parametru Wyświetl dla tej lokalizacji. Alternatywnie możesz ustawić opcję "View=Auto", która zwróci dane mapy na podstawie adresu IP żądania. Parametr View w usłudze Azure Maps musi być używany zgodnie z obowiązującymi przepisami, w tym z przepisami dotyczącymi mapowania kraju/regionu, w którym udostępniane są mapy, obrazy i inne dane oraz zawartość innych firm, do których masz uprawnienia dostępu za pośrednictwem usługi Azure Maps. Przykład: view=IN.

Aby uzyskać szczegółowe informacje, zobacz Obsługiwane widoki, aby uzyskać szczegółowe informacje i wyświetlić dostępne widoki.

MatchType

Typy dopasowania dla operacji wyszukiwania odwrotnego adresu.

QueryType

Zwracany typ zapytania: W POBLIŻU lub NON_NEAR.

ResponseFormat

Żądany format odpowiedzi. Wartość może być json lub xml.

ReverseSearchAddressResult

Ten obiekt jest zwracany z pomyślnego wywołania odwrotnego adresu wyszukiwania

ReverseSearchAddressResultItem

Obiekt result dla odpowiedzi odwrotnej adresu wyszukiwania

RoadUseType

Opisuje możliwe zastosowania drogi.

SearchSummary

Obiekt podsumowania odpowiedzi interfejsu API wyszukiwania.

Address

Adres wyniku

Nazwa Typ Opis
boundingBox

BoundingBoxCompassNotation

Pole ograniczenia lokalizacji.

buildingNumber

string

Numer budynku na ulicy. PRZESTARZAŁE, zamiast tego użyj streetNumber.

country

string

nazwa kraju/regionu

countryCode

string

Kraj (Uwaga: jest to dwuliterowy kod, a nie nazwa kraju/regionu).

countryCodeISO3

string

Kod kraju ISO alfa-3

countrySecondarySubdivision

string

Powiat

countrySubdivision

string

Stan lub prowincja

countrySubdivisionCode

string

countrySubdivisionCode prefiksowany przez countryCode ( countryCode-countrySubdivisionCode ) i łącznik tworzy kod ISO 3166-2. Przykłady: TX dla Teksasu, SCT dla Szkocji i ON dla Ontario.

countrySubdivisionName

string

Pełna nazwa pierwszego poziomu hierarchii administracyjnej kraju/regionu. To pole jest wyświetlane tylko w przypadku, gdy countrySubdivision jest prezentowany w skróconej formie. Obsługiwane tylko w przypadku Stanów Zjednoczonych, Kanady i Wielkiej Brytanii.

countryTertiarySubdivision

string

Nazwany obszar

crossStreet

string

Nazwa ulicy, która jest przekraczana.

extendedPostalCode

string

Rozszerzony kod pocztowy (dostępność zależy od regionu).

freeformAddress

string

Wiersz adresu sformatowany zgodnie z regułami formatowania kraju/regionu wynikowego pochodzenia lub w przypadku kraju/regionu pełna nazwa kraju/regionu.

localName

string

Składnik adresu reprezentujący nazwę obszaru geograficznego lub lokalności, który grupuje wiele obiektów adresowalnych na potrzeby adresowania, bez jednostki administracyjnej. To pole służy do kompilowania właściwości freeformAddress. localName reprezentuje gminę pocztową. W zależności od lokalizacji localName jest powszechnie znaną nazwą miasta lub miasta. W przypadku powszechnie znanej nazwy miasta lub miasta należy użyć localName zamiast municipality.

municipality

string

Miasto/ Miasto
Uwaga: municipality reprezentuje gminę mieszkalną. W zależności od lokalizacji wartość municipality może różnić się od powszechnie znanej nazwy miasta lub miasta. W przypadku powszechnie znanej nazwy miasta lub miasta zaleca się, aby wartość localName była używana zamiast wartości municipality.

municipalitySubdivision

string

Sub/Super City

neighbourhood

string

Sąsiedztwo to geograficznie zlokalizowany obszar w mieście lub mieście z charakterystycznymi cechami i interakcjami społecznymi między mieszkańcami.

postalCode

string

Kod pocztowy/kod pocztowy

routeNumbers

string[]

Kody używane do jednoznacznej identyfikacji ulicy

street

string

Nazwa ulicy. PRZESTARZAŁE, zamiast tego użyj streetName.

streetName

string

Nazwa ulicy.

streetNameAndNumber

string

Nazwa ulicy i numer.

streetNumber

string

Numer budynku na ulicy.

BoundingBoxCompassNotation

Pole ograniczenia lokalizacji.

Nazwa Typ Opis
entity

Entity

Źródło typu jednostki pola ograniczenia. W przypadku odwrotnego geokodowania jest to zawsze równe pozycji.

northEast

string

Szerokość geograficzna północno-wschodnia,współrzędna geograficzna pola ograniczenia jako rozdzielane przecinkami zmiennoprzecinkowe

southWest

string

Szerokość geograficzna południowo-zachodnia,współrzędna geograficzna pola ograniczenia jako rozdzielane przecinkami zmiennoprzecinkowe

Entity

Źródło typu jednostki pola ograniczenia. W przypadku odwrotnego geokodowania jest to zawsze równe pozycji.

Wartość Opis
position

Pozycja jednostki

ErrorAdditionalInfo

Dodatkowe informacje o błędzie zarządzania zasobami.

Nazwa Typ Opis
info

object

Dodatkowe informacje.

type

string

Dodatkowy typ informacji.

ErrorDetail

Szczegóły błędu.

Nazwa Typ Opis
additionalInfo

ErrorAdditionalInfo[]

Dodatkowe informacje o błędzie.

code

string

Kod błędu.

details

ErrorDetail[]

Szczegóły błędu.

message

string

Komunikat o błędzie.

target

string

Element docelowy błędu.

ErrorResponse

Odpowiedź na błąd

Nazwa Typ Opis
error

ErrorDetail

Obiekt błędu.

GeographicEntityType

Typ jednostki Geografia. Prezentuj tylko wtedy, gdy zażądano parametru entityType i jest dostępny.

Wartość Opis
Country

nazwa kraju/regionu

CountrySecondarySubdivision

Powiat

CountrySubdivision

Stan lub prowincja

CountryTertiarySubdivision

Nazwany obszar

Municipality

Miasto/ Miasto

MunicipalitySubdivision

Sub/Super City

Neighbourhood

Sąsiedztwo

PostalCodeArea

Kod pocztowy/kod pocztowy

LatLongPairAbbreviated

Lokalizacja reprezentowana jako szerokość geograficzna i długość geograficzna przy użyciu krótkich nazw "lat" & "lon".

Nazwa Typ Opis
lat

number (double)

Właściwość Szerokość geograficzna

lon

number (double)

Właściwość Długość geograficzna

LocalizedMapView

Parametr View (nazywany również parametrem "region użytkownika") umożliwia wyświetlanie poprawnych map dla określonego kraju/regionu dla regionów spornych geopolitycznie. Różne kraje/regiony mają różne widoki takich regionów, a parametr View umożliwia aplikacji zgodność z widokiem wymaganym przez kraj/region, który będzie obsługiwać aplikacja. Domyślnie parametr Widok jest ustawiony na wartość "Unified", nawet jeśli nie zdefiniowano go w żądaniu. Twoim zadaniem jest określenie lokalizacji użytkowników, a następnie poprawne ustawienie parametru Wyświetl dla tej lokalizacji. Alternatywnie możesz ustawić opcję "View=Auto", która zwróci dane mapy na podstawie adresu IP żądania. Parametr View w usłudze Azure Maps musi być używany zgodnie z obowiązującymi przepisami, w tym z przepisami dotyczącymi mapowania kraju/regionu, w którym udostępniane są mapy, obrazy i inne dane oraz zawartość innych firm, do których masz uprawnienia dostępu za pośrednictwem usługi Azure Maps. Przykład: view=IN.

Aby uzyskać szczegółowe informacje, zobacz Obsługiwane widoki, aby uzyskać szczegółowe informacje i wyświetlić dostępne widoki.

Wartość Opis
AE

Zjednoczone Emiraty Arabskie (widok arabski)

AR

Argentyna (Widok argentyński)

Auto

Zwróć dane mapy na podstawie adresu IP żądania.

BH

Bahrajn (widok arabski)

IN

Indie (Widok indyjski)

IQ

Irak (widok arabski)

JO

Jordania (widok arabski)

KW

Kuwejt (widok arabski)

LB

Liban (widok arabski)

MA

Maroko (widok marokański)

OM

Oman (widok arabski)

PK

Pakistan (Pakistani View)

PS

Autonomia Palestyńska (widok arabski)

QA

Katar (widok arabski)

SA

Arabia Saudyjska (widok arabski)

SY

Syria (widok arabski)

Unified

Ujednolicony widok (inne)

YE

Jemen (widok arabski)

MatchType

Typy dopasowania dla operacji wyszukiwania odwrotnego adresu.

Wartość Opis
AddressPoint
HouseNumberRange
Street

QueryType

Zwracany typ zapytania: W POBLIŻU lub NON_NEAR.

Wartość Opis
NEARBY

Wyszukiwanie zostało wykonane wokół określonej szerokości geograficznej i długości geograficznej ze zdefiniowanym promieniem

NON_NEAR

Wyszukiwanie zostało wykonane globalnie, bez stronniczo do określonej szerokości geograficznej i długości geograficznej i bez zdefiniowanego promienia

ResponseFormat

Żądany format odpowiedzi. Wartość może być json lub xml.

Wartość Opis
json

format wymiany danych notacji obiektów JavaScript

xml

rozszerzalnego języka znaczników

ReverseSearchAddressResult

Ten obiekt jest zwracany z pomyślnego wywołania odwrotnego adresu wyszukiwania

Nazwa Typ Opis
addresses

ReverseSearchAddressResultItem[]

Tablica adresów

summary

SearchSummary

Obiekt podsumowania odpowiedzi odwrotnej adresu wyszukiwania

ReverseSearchAddressResultItem

Obiekt result dla odpowiedzi odwrotnej adresu wyszukiwania

Nazwa Typ Opis
address

Address

Adres wyniku

matchType

MatchType

Informacje o typie dopasowania.

Jeden z:

  • AdresPoint
  • HouseNumberRange
  • Ulica
position

string

Pozycja właściwości w postaci "{latitude},{longitude}"

roadUse

RoadUseType[]

Opisuje możliwe zastosowania drogi.

RoadUseType

Opisuje możliwe zastosowania drogi.

Wartość Opis
Arterial
LimitedAccess
LocalStreet
Ramp
Rotary
Terminal

SearchSummary

Obiekt podsumowania odpowiedzi interfejsu API wyszukiwania.

Nazwa Typ Opis
fuzzyLevel

integer

Maksymalny poziom rozmyte wymagany do dostarczenia wyników.

geoBias

LatLongPairAbbreviated

Wskazanie, kiedy wewnętrzna wyszukiwarka zastosowała stronniczość geoprzestrzenną, aby poprawić klasyfikację wyników. W niektórych metodach może to mieć wpływ na ustawienie parametrów lat i lon, jeśli są dostępne. W innych przypadkach jest to wyłącznie wewnętrzne.

limit

integer

Maksymalna liczba odpowiedzi, które zostaną zwrócone

numResults

integer

Liczba wyników w odpowiedzi.

offset

integer

Przesunięcie początkowe zwróconych wyników w pełnym zestawie wyników.

query

string

Parametr zapytania, który został użyty do wygenerowania tych wyników wyszukiwania.

queryTime

integer

Czas spędzony na rozwiązywaniu zapytania w milisekundach.

queryType

QueryType

Zwracany typ zapytania: W POBLIŻU lub NON_NEAR.

totalResults

integer

Całkowita liczba znalezionych wyników.