Odwrotne żądanie geokodowania (wyszukiwanie adresu) i odpowiedź

Określenie geokodowanie zazwyczaj oznacza tłumaczenie adresu czytelnego dla człowieka na lokalizację na mapie. W przeciwnym razie proces tłumaczenia lokalizacji na mapie jest przekształcany w adres czytelny dla człowieka. Jest to tzw. odwrotne geokodowanie.

Odwrotne żądania geokodowania

Wymagane parametry

  • latlng – szerokość i długość geograficzna określająca lokalizację, której ma dotyczyć najbliższy adres.
  • key – klucz interfejsu API aplikacji. Ten klucz określa Twoją aplikację na potrzeby zarządzania limitem. Dowiedz się, jak uzyskać klucz.

Parametry opcjonalne

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

  • language – język, w którym będą zwracane wyniki.
    • Zobacz listę obsługiwanych języków. Google często aktualizuje obsługiwane języki, więc ta lista może nie być wyczerpująca.
    • Jeśli nie zostanie podany parametr language, geokoder spróbuje użyć preferowanego języka określonego w nagłówku Accept-Language lub języka natywnego domeny, z której zostało wysłane żądanie.
    • Geokoder stara się podać adres pocztowy, który będzie czytelny dla użytkowników i użytkowników lokalnych. Aby osiągnąć ten cel, funkcja ta zwraca adresy pocztowe w języku lokalnym, a w razie potrzeby transliterację do skryptu zrozumiałego dla użytkownika z uwzględnieniem preferowanego języka. Wszystkie pozostałe adresy są zwracane w preferowanym języku. Wszystkie komponenty adresu są zwracane w tym samym języku, który został wybrany z pierwszego komponentu.
    • Jeśli nazwa jest niedostępna w wybranym języku, geokoder używa najbliższego dopasowania.
  • region – kod regionu podany jako ccTLD („domena najwyższego poziomu”). Ten parametr może też wpływać na wyniki w zależności od obowiązującego prawa.
  • result_type – filtr o co najmniej jednym typie adresu rozdzielonym pionową kreską (|). 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. result_type działa jednak jak filtr po wyszukiwaniu: interfejs API pobiera wszystkie wyniki dotyczące określonego argumentu latlng, a następnie odrzuca wyniki, które nie pasują do określonego typu adresów. Obsługiwane są te wartości:
    • street_address wskazuje dokładny adres.
    • route oznacza nazwą trasę (np. „PL 101”).
    • intersection wskazuje główne skrzyżowanie, złożone zwykle z 2 głównych dróg.
    • political oznacza podmiot polityczny. Ten typ oznacza zwykle wielokąt administracji cywilnej.
    • country wskazuje krajową instytucję polityczną i jest zwykle najwyższym typem zamówienia zwracanym przez geokoder.
    • administrative_area_level_1 wskazuje na pierwszy poziom jednostki cywilnej niższy niż kraj. W Stanach Zjednoczonych są to stany administracyjne. Nie wszystkie kraje mają ten poziom administracyjny. W większości przypadków krótkie nazwy administracyjne_area_level_1 są bardzo zbliżone do podziałów ISO 3166-2 i innych szeroko rozpowszechnianych list. Nie gwarantujemy jednak, że wyniki geokodowania będą oparte na różnych sygnałach i danych o lokalizacji.
    • administrative_area_level_2 wskazuje na kolejne kraje poziom cywilny drugiego rzędu. W Stanach Zjednoczonych są to hrabstwa. Nie wszystkie kraje mają ten poziom administracyjny.
    • administrative_area_level_3 wskazuje podmiot cywilny trzeciego poziomu poniżej poziomu krajowego. Wskazuje on drobny podział cywilny. Nie we wszystkich krajach obowiązują te poziomy administracyjne.
    • administrative_area_level_4 wskazuje na 4. porządek cywilny poniżej poziomu krajowego. Wskazuje on drobny podział cywilny. Nie we wszystkich krajach obowiązują te poziomy administracyjne.
    • administrative_area_level_5 wskazuje jednostkę cywilną o piątej kolejności poniżej poziomu krajowego. Wskazuje on drobny podział cywilny. Nie we wszystkich krajach obowiązują te poziomy administracyjne.
    • administrative_area_level_6 wskazuje na poziomie kraju szósty podmiot cywilny. Wskazuje on drobny podział cywilny. Nie we wszystkich krajach obowiązują te poziomy administracyjne.
    • administrative_area_level_7 wskazuje podmiot cywilny 7 poziomu poniżej kraju. Wskazuje on drobny podział cywilny. Nie we wszystkich krajach obowiązują te poziomy administracyjne.
    • colloquial_area wskazuje powszechnie używaną alternatywną nazwę elementu.
    • locality wskazuje spółkę państwową, która jest częścią miasta.
    • sublocality oznacza podmiot cywilny pierwszego stopnia znajdujący się niżej w okolicy. W przypadku niektórych lokalizacji może pojawić się dodatkowy typ: od sublocality_level_1 do sublocality_level_5. Każdy poziom podrejonu to podmiot cywilny. Większe liczby oznaczają mniejszy obszar geograficzny.
    • neighborhood wskazuje na nazwaną dzielnicę
    • premise wskazuje nazwane miejsce, zwykle budynek lub zbiór budynków o wspólnej nazwie
    • subpremise wskazuje encję pierwszego stopnia poniżej nazwanej lokalizacji. Zazwyczaj jest to pojedynczy budynek w kolekcji budynków o takiej samej nazwie.
    • plus_code wskazuje zakodowane odwołanie do lokalizacji pobrane na podstawie szerokości i długości geograficznej. Kodów Plus Code można używać zamiast adresów pocztowych w miejscach, w których nie istnieją (gdy budynki nie są numerowane lub nie mają nazw ulic). Szczegółowe informacje znajdziesz na https://plus.codes.
    • postal_code to kod pocztowy, który jest używany do obsługi poczty w danym kraju.
    • natural_feature wskazuje charakterystyczną cechę naturalną.
    • airport oznacza lotnisko.
    • park wskazuje nazwany park.
    • point_of_interest wskazuje na wybrane miejsce. Są to zwykle ważne lokalne obiekty, które nie pasują do żadnej kategorii, np. „Empire State Building” lub „Eiffel Tower”.
  • location_type – filtr z co najmniej 1 typem lokalizacji rozdzielonym pionową kreską (|). Jeśli parametr zawiera wiele typów lokalizacji, interfejs API zwróci wszystkie adresy odpowiadające każdemu z nich. Uwaga o przetwarzaniu: parametr location_type nie ogranicza wyszukiwania do określonych typów lokalizacji. location_type działa jak filtr po wyszukiwaniu: interfejs API pobiera wszystkie wyniki z określonej zmiennej latlng, a następnie odrzuca wyniki, które nie są zgodne z określonymi typami lokalizacji. Dostępne wartości:
    • "ROOFTOP" zwraca tylko te adresy, dla których informacje o lokalizacji są dokładne, a nawet dokładność adresu.
    • "RANGE_INTERPOLATED" zwraca tylko adresy, które odzwierciedlają przybliżone (zwykle na drodze) interpolowane między 2 dokładnymi punktami (np. skrzyżowaniami). Zakres interpolowany zasadniczo oznacza, że dane geograficzne z dachu nie są dostępne dla adresu ulicy.
    • "GEOMETRIC_CENTER" zwraca tylko geometryczne centra lokalizacji, np. linię łamaną (np. ulicę) lub wielokąt (region).
    • "APPROXIMATE" zwraca tylko te adresy, które są przybliżone.

Jeśli używasz filtrów result_type i location_type, interfejs API zwraca tylko te wyniki, które pasują zarówno do result_type, jak i do location_type. Jeśli żadna z wartości filtra nie jest akceptowalna, interfejs API zwraca wartość ZERO_RESULTS.

Przykład odwrotnego geokodowania

To zapytanie zawiera szerokość i długość geograficzną lokalizacji na Brooklynie:

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

To zapytanie zwróci ten 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> ...

Zwróć uwagę, że odwrotny geokoder zwrócił więcej niż 1 wynik. Wyniki "formatted_address" to nie tylko adresy pocztowe, ale każdy sposób na podanie lokalizacji geograficznej. Na przykład geokodowanie punktów w Chicago może być określane jako adres, jako miasto (Chicago), jako województwo (Illinois) lub jako kraj (Stany Zjednoczone). Wszystkie są „adresami” geokodera. Odwrotny geokoder zwraca każdy z tych typów jako prawidłowe wyniki.

Odwrotny geokoder pasuje do jednostek politycznych (krajów, prowincji, miast i dzielnic), adresów oraz kodów pocztowych.

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

{
   "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ółowych adresów po mniej konkretne podmioty polityczne, takie jak dzielnice, miasta, hrabstwa i stany. Najdokładniejszy jest to najbardziej dokładny wynik, jak w tym przypadku. Jeśli chcesz dopasować typ adresu, zapoznaj się z sekcją poniżej dotyczącą ograniczania wyników według typu. Z tego powodu lokalizacja wyników w odniesieniu do siebie może się różnić.

Odwrotne geokodowanie według typu

Poniższy przykład pokazuje filtrowanie zwróconych adresów, aby uwzględnić tylko adresy ROOFTOP i 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 działają tylko w przypadku odwrotnego geokodowania.

Odwrotne odpowiedzi geokodowane

Format odwrotnej geokodowania jest taki sam jak odpowiedź Geocode. Zobacz Odpowiedzi geograficzne. Poniżej znajdziesz kody stanu możliwe do odpowiedzi w odwrotnej geokodowaniu.

Odwrotne kody stanu geokodowania

Pole "status" w obiekcie odpowiedzi Geocode zawiera stan żądania i może zawierać informacje na potrzeby 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 został zwrócony co najmniej 1 adres.
  • "ZERO_RESULTS" wskazuje, że odwrotne geokodowanie zakończyło się powodzeniem, ale nie zwróciło żadnych wyników. Może się tak zdarzyć, jeśli geokoder przesłał latlng w lokalizacji zdalnej.
  • "OVER_QUERY_LIMIT" oznacza, że został przekroczony Twój limit.
  • "REQUEST_DENIED" oznacza, że żądanie zostało odrzucone. Prawdopodobnie żądanie zawiera parametr result_type lub location_type, ale nie zawiera klucza interfejsu API.
  • "INVALID_REQUEST" zwykle wskazuje jedną z tych wartości:
    • Brak zapytania (address, components lub latlng).
    • Podano nieprawidłowy result_type lub location_type.
  • "UNKNOWN_ERROR" oznacza, że nie udało się przetworzyć żądania z powodu błędu serwera. Prośba może się udać, jeśli spróbujesz ponownie.

Odwrotne geokodowanie plus kody

Pole plus_code w odpowiedzi Geocode zawiera kod plus, który najlepiej określa szerokość i długość geograficzną, których dotyczy zapytanie. Oprócz tego tablica wyników JSON w większości przypadków zawiera pełny wynik geokodowania z typem plus_code i adresem zawierającym kod plus. Odległość między zdekodowanym kodem plus a punktem żądania musi być mniejsza niż 10 metrów.