Żądanie odwrotnego geokodowania (wyszukiwanie adresu) i odpowiedź

Termin geokodowanie odnosi się zazwyczaj do przekształcania adresu w postać czytelną dla człowieka na mapie. Proces odwrotny, czyli przekształcanie lokalizacji na mapie w czytelny dla człowieka adres, jest nazywany odwrotnym geokodowaniem.

żądania odwrotnego geokodowania,

Wymagane parametry

  • latlng – współrzędne geograficzne szerokości i długości określające lokalizację, dla której chcesz uzyskać adres zrozumiały dla człowieka.
  • key – klucz API Twojej aplikacji. Ten klucz identyfikuje Twoją aplikację na potrzeby zarządzania limitem. Dowiedz się, jak uzyskać klucz.

Parametry opcjonalne

Oto opcjonalne parametry, które możesz uwzględnić w żądaniu odwrotnego geokodowania:

  • language – język, w którym mają być wyświetlane wyniki.
    • Zobacz listę obsługiwanych języków. Google często aktualizuje listę obsługiwanych języków, więc może ona nie być kompletna.
    • Jeśli parametr language nie zostanie podany, geokoder spróbuje użyć preferowanego języka określonego w nagłówku Accept-Language lub domyślnego języka domeny, z której wysłano żądanie.
    • Geokoder dokłada wszelkich starań, aby podać adres ulicy, który jest czytelny zarówno dla użytkownika, jak i dla mieszkańców. Aby to osiągnąć, zwraca adresy ulicy w języku lokalnym, transliterowane do postaci zrozumiałej dla użytkownika w odpowiednim języku. Wszystkie inne adresy są zwracane w preferowanym języku. Wszystkie elementy adresu są zwracane w tym samym języku, który jest wybierany na podstawie pierwszego elementu.
    • Jeśli nazwa nie jest dostępna w preferowanym języku, geokoder stosuje najbliższe dopasowanie.
  • region – kod regionu podany jako 2-znakowa wartość ccTLD („domena najwyższego poziomu”). Parametr może też wpływać na wyniki w oparciu o obowiązujące przepisy.
  • result_type – filtr obejmujący co najmniej 1 typ adresu, oddzielony znakiem pionowym (|). Jeśli parametr zawiera wiele typów adresów, interfejs API zwraca wszystkie adresy pasujące do dowolnego z tych typów. Uwaga dotycząca przetwarzania: parametr result_type nie ogranicza wyszukiwania do określonych typów adresów. Zamiast tego result_type działa jako filtr po wyszukiwaniu: interfejs API pobiera wszystkie wyniki dla określonego latlng, a następnie odrzuca te, które nie pasują do określonych typów adresów. Obsługiwane są następujące wartości:
    • street_address oznacza dokładny adres.
    • route wskazuje nazwaną trasę (np. „US 101”).
    • intersection wskazuje główne skrzyżowanie, zwykle 2 głównych dróg.
    • political oznacza podmiot polityczny. Zwykle ten typ wskazuje poligon administracji cywilnej.
    • country wskazuje podmiot polityczny o zasięgu krajowym i jest zwykle najwyższym typem zwracanym przez geokoder.
    • administrative_area_level_1 wskazuje podmiot prawny pierwszego rzędu poniżej poziomu kraju. W Stanach Zjednoczonych są to stany. Nie wszystkie kraje mają te poziomy administracyjne. W większości przypadków krótkie nazwy administrative_area_level_1 będą bardzo zbliżone do podziałów ISO 3166-2 i innych powszechnie używanych list. Nie jest to jednak gwarantowane, ponieważ nasze wyniki geokodowania opierają się na różnych sygnałach i danych dotyczących lokalizacji.
    • administrative_area_level_2 oznacza jednostkę prawną drugiego rzędu na poziomie niższym niż kraj. W Stanach Zjednoczonych te jednostki administracyjne to hrabstwa. Nie wszystkie kraje mają te poziomy administracyjne.
    • administrative_area_level_3 oznacza podmiot prawny trzeciego rzędu poniżej poziomu kraju. Ten typ wskazuje mniejszy podział administracyjny. Nie wszystkie kraje mają te poziomy administracyjne.
    • administrative_area_level_4 oznacza podmiot prawny czwartego rzędu poniżej poziomu kraju. Ten typ wskazuje mniejszy podział administracyjny. Nie wszystkie kraje mają te poziomy administracyjne.
    • administrative_area_level_5 wskazuje podmiot prawny piątego rzędu poniżej poziomu kraju. Ten typ wskazuje mniejszy podział administracyjny. Nie wszystkie kraje mają te poziomy administracyjne.
    • administrative_area_level_6 wskazuje podmiot prawny szóstego rzędu poniżej poziomu kraju. Ten typ wskazuje mniejszy podział administracyjny. Nie wszystkie kraje mają te poziomy administracyjne.
    • administrative_area_level_7 wskazuje podmiot prawny siódmego rzędu poniżej poziomu kraju. Ten typ wskazuje mniejszy podział administracyjny. Nie wszystkie kraje mają te poziomy administracyjne.
    • colloquial_area wskazuje powszechnie używaną nazwę alternatywną podmiotu.
    • locality oznacza zarejestrowany podmiot polityczny miasta.
    • sublocality wskazuje jednostkę administracyjną pierwszego rzędu poniżej lokalizacji. W przypadku niektórych lokalizacji może być wymagany jeden z dodatkowych typów: sublocality_level_1 do sublocality_level_5. Każdy poziom podregionu jest jednostką administracyjną. Im większa liczba, tym mniejszy obszar geograficzny.
    • neighborhood oznacza nazwę dzielnicy.
    • premise wskazuje nazwę lokalizacji, zwykle budynku lub grupy budynków o wspólnej nazwie.
    • subpremise wskazuje element, który można zidentyfikować na poziomie niższym niż budynek, na przykład mieszkanie, lokal lub apartament.
    • plus_code oznacza zakodowany identyfikator lokalizacji, który jest wyprowadzony z szerokości i długości geograficznej. Kody Plus Code mogą zastępować adresy ulicy w miejscach, w których ich nie ma (gdzie budynki nie mają numerów lub ulice nie mają nazw). Więcej informacji znajdziesz na stronie https://plus.codes.
    • postal_code oznacza kod pocztowy używany do adresowania przesyłek pocztowych na terenie danego kraju.
    • natural_feature wskazuje charakterystyczny element przyrodniczy.
    • airport oznacza lotnisko.
    • park oznacza park o nazwie.
    • point_of_interest wskazuje nazwane miejsce docelowe. Zwykle są to znane obiekty lokalne, które nie pasują do żadnej innej kategorii, np. „Empire State Building” czy „Wieża Eiffla”.
  • location_type – filtr obejmujący co najmniej 1 typ lokalizacji, oddzielony znakiem pionowym (|). Jeśli parametr zawiera wiele typów lokalizacji, interfejs API zwraca wszystkie adresy pasujące do dowolnego z tych typów. Uwaga dotycząca przetwarzania: parametr location_type nie ogranicza wyszukiwania do podanych typów lokalizacji. Zamiast tego location_type działa jako filtr po wyszukiwaniu: interfejs API pobiera wszystkie wyniki dla określonego latlng, a potem odrzuca te, które nie pasują do określonych typów lokalizacji. Obsługiwane są te wartości:
    • "ROOFTOP" zwraca tylko adresy, dla których Google ma informacje o lokalizacji dokładne do poziomu adresu ulicy.
    • "RANGE_INTERPOLATED" zwraca tylko adresy, które odzwierciedlają przybliżenie (zwykle na drodze) interpolowane między 2 dokładnymi punktami (np. skrzyżowaniami). Interpolowany zakres zazwyczaj wskazuje, że kody geoadresowe dachów są niedostępne dla adresu ulicznego.
    • "GEOMETRIC_CENTER" zwraca tylko geometryczne środki lokalizacji, takie jak linia łamana (np. ulica) lub wielokąt (region).
    • Funkcja "APPROXIMATE" zwraca tylko adresy opisane jako przybliżone.
  • extra_computations – użyj tego parametru, aby określić w odpowiedzi te dodatkowe funkcje: Aby włączyć kilka z tych funkcji w ramach tego samego żądania interfejsu API, dodaj parametr extra_computations w żądaniu dla każdej funkcji, na przykład: 
    extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES

Jeśli podane są filtry result_type i location_type, interfejs API zwraca tylko te wyniki, które pasują do obu wartości result_type i location_type. Jeśli żadna z wartości filtra nie jest akceptowalna, interfejs API zwraca ZERO_RESULTS.

Przykład odwrotnego geokodowania

To zapytanie zawiera wartość szerokości geograficznej/długości geograficznej lokalizacji w Brooklynie:

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&key=YOUR_API_KEY

Powyższe zapytanie zwraca taki wynik:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "277",
               "short_name" : "277",
               "types" : [ "street_number" ]
            },
            {
               "long_name" : "Bedford Avenue",
               "short_name" : "Bedford Ave",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Williamsburg",
               "short_name" : "Williamsburg",
               "types" : [ "neighborhood", "political" ]
            },
            {
               "long_name" : "Brooklyn",
               "short_name" : "Brooklyn",
               "types" : [ "sublocality", "political" ]
            },
            {
               "long_name" : "Kings",
               "short_name" : "Kings",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "New York",
               "short_name" : "NY",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "11211",
               "short_name" : "11211",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA",
         "geometry" : {
            "location" : {
               "lat" : 40.714232,
               "lng" : -73.9612889
            },
            "location_type" : "ROOFTOP",
            "viewport" : {
               "northeast" : {
                  "lat" : 40.7155809802915,
                  "lng" : -73.9599399197085
               },
               "southwest" : {
                  "lat" : 40.7128830197085,
                  "lng" : -73.96263788029151
               }
            }
         },
         "place_id" : "ChIJd8BlQ2BZwokRAFUEcm_qrcA",
         "types" : [ "street_address" ]
      },

  ... Additional <code>results[]</code> ...

Pamiętaj, że odwrotny geokodownik zwrócił więcej niż 1 wynik. Wyniki "formatted_address" to nie tylko adresy pocztowe, ale dowolny sposób na określenie położenia geograficznego. Podczas geokodowania punktu w mieście Chicago może on zostać oznaczony jako adres ulicy, miasto (Chicago), stan (Illinois) lub kraj (Stany Zjednoczone). Dla geokodera wszystkie te dane są „adresami”. Odwrotny geokodownik zwraca dowolny z tych typów jako prawidłowe wyniki.

Geokodowanie odwrotne umożliwia dopasowanie jednostek politycznych (krajów, miast, dzielnic), adresów ulic i kodów pocztowych.

Poniżej znajdziesz pełną listę wartości formatted_address zwróconych przez poprzednie zapytanie.

{
   "plus_code" : {
      "compound_code" : "P27Q+MCM New York, NY, USA",
      "global_code" : "87G8P27Q+MCM"
   },
   "results" : [
      {
         "formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "street_address" ]
      },
      {
         "formatted_address" : "279 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "premise" ]
      },
      {
         "formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "establishment", "point_of_interest" ]
      },
      {
         "formatted_address" : "291-275 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "route" ]
      },
      {
         "formatted_address" : "P27Q+MC New York, NY, USA",
         ...
         "types" : [ "plus_code" ]
      },
      {
         "formatted_address" : "South Williamsburg, Brooklyn, NY, USA",
         ...
         "types" : [ "neighborhood", "political" ]
      },
      {
         "formatted_address" : "Brooklyn, NY 11211, USA",
         ...
         "types" : [ "postal_code" ]
      },
      {
         "formatted_address" : "Williamsburg, Brooklyn, NY, USA",
         ...
         "types" : [ "neighborhood", "political" ]
      },
      {
         "formatted_address" : "Kings County, Brooklyn, NY, USA",
         ...
         "types" : [ "administrative_area_level_2", "political" ]
      },
      {
         "formatted_address" : "Brooklyn, NY, USA",
         ...
         "types" : [ "political", "sublocality", "sublocality_level_1" ]
      },
      {
         "formatted_address" : "New York, NY, USA",
         ...
         "types" : [ "locality", "political" ]
      },
      {
         "formatted_address" : "New York, USA",
         ...
         "types" : [ "administrative_area_level_1", "political" ]
      },
      {
         "formatted_address" : "United States",
         ...
         "types" : [ "country", "political" ]
      }
   ],
   "status" : "OK"
}

Ten interfejs API zwraca różne typy adresów, od najbardziej szczegółowego adresu ulicy do mniej szczegółowych jednostek administracyjnych, takich jak dzielnice, miasta, powiaty i stany. W tym przypadku bardziej dokładny adres jest zwykle najbardziej widocznym wynikiem. Jeśli chcesz dopasować określony typ adresu, zapoznaj się z sekcją poniżej dotyczącą ograniczania wyników według typu. Z tego powodu ich lokalizacja może się różnić.

Odwrotne geokodowanie według typu

W tym przykładzie zwracane adresy są filtrowane tak, aby uwzględnić tylko te, które mają typ lokalizacji ROOFTOP i typ adresu street_address.

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452
&location_type=ROOFTOP&result_type=street_address&key=YOUR_API_KEY

Uwaga: te filtry są ważne tylko w przypadku odwrotnego geokodowania.

Odwrotne geokodowanie odpowiedzi

Format odpowiedzi z odwrotnego geokodowania jest taki sam jak w przypadku odpowiedzi z geokodowania. Zobacz odpowiedzi geokodowania. Poniżej znajdują się kody stanu, które mogą wystąpić w odpowiedzi na odwrotne geokodowanie.

Kody stanu odwrotnego geokodowania

Pole "status" w obiekcie odpowiedzi geokodowania zawiera stan żądania i może zawierać informacje debugowania, które pomogą Ci ustalić, dlaczego odwrotne geokodowanie nie działa. Pole "status" może zawierać te wartości:

  • "OK" oznacza, że nie wystąpiły żadne błędy i zwrócono co najmniej 1 adres.
  • "ZERO_RESULTS" oznacza, że odwrotne geokodowanie zakończyło się powodzeniem, ale nie zwróciło żadnych wyników. Może się tak zdarzyć, jeśli geokoder otrzymał latlng w odległej lokalizacji.
  • "OVER_QUERY_LIMIT" oznacza, że przekroczysz swój limit.
  • "REQUEST_DENIED" oznacza, że prośba została odrzucona. Prawdopodobnie dlatego, że żądanie zawiera parametr result_type lub location_type, ale nie zawiera klucza interfejsu API.
  • "INVALID_REQUEST" zazwyczaj oznacza jedno z tych zdarzeń:
    • Brak zapytania (address, components lub latlng).
    • Podano nieprawidłową wartość result_type lub location_type.
  • "UNKNOWN_ERROR" oznacza, że nie udało się zrealizować żądania z powodu błędu serwera. Żądanie może się powieść, jeśli spróbujesz ponownie.

Odwrotne geokodowanie kodów Plus Code

Pole plus_code w odpowiedzi na zapytanie o geokodowanie zawiera kod plus, który najlepiej przybliża się do zapytanej szerokości i długości geograficznej. Ponadto tablica wyników JSON w większości przypadków zawiera pełny wynik geokodowania z typem plus_code i adresem zawierającym kod pocztowy. Odległość między odkodowanym kodem plusa a punktem żądania jest gwarantowana na mniej niż 10 metrów.