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

Termin kodowanie geograficzne oznacza przekształcenie zrozumiałego dla człowieka adresu na lokalizację na mapie. Odwrotny proces, czyli tłumaczenie lokalizacji na mapie na adres zrozumiały dla człowieka, to odwrotne geokodowanie.

Odwrotne żądania geokodowania

Wymagane parametry

  • latlng – współrzędne szerokości i długości geograficznej wskazujące lokalizację, dla której chcesz znaleźć najbliższy, zrozumiały dla człowieka adres.
  • key – klucz interfejsu API aplikacji. Ten klucz identyfikuje aplikację na potrzeby zarządzania limitami. 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ć 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ć pełna.
    • Jeśli language nie zostanie podany, geokoder spróbuje użyć preferowanego języka określonego w nagłówku Accept-Language lub języka ojczystego domeny, z której wysłane jest żądanie.
    • Geokoder dokłada wszelkich starań, aby podać czytelny adres zarówno dla użytkownika, jak i lokalnego. W tym celu funkcja zwraca adresy w języku lokalnym, transliterację do skryptu zrozumiałego dla użytkownika (w razie potrzeby) z uwzględnieniem preferowanego języka. Wszystkie inne adresy są zwracane w preferowanym języku. Komponenty adresu są zwracane w tym samym języku, który jest wybierany z pierwszego komponentu.
    • Jeśli nazwa nie jest dostępna w preferowanym języku, geokoder użyje najbliższego dopasowania.
  • region – kod regionu, podany jako dwuznakowa wartość domeny ccTLD („domena najwyższego poziomu”). Parametr może też wpływać na wyniki zgodnie z obowiązującym prawem.
  • result_type – filtr obejmujący co najmniej 1 typ adresu rozdzielony pionową kreską (|). Jeśli parametr zawiera kilka typów adresów, interfejs API zwraca wszystkie adresy pasujące do dowolnego z nich. Uwaga na temat przetwarzania: parametr result_type restrict wyszukiwania do określonych typów adresów. result_type działa raczej jak filtr po wyszukiwaniu: interfejs API pobiera wszystkie wyniki związane z określonym parametrem latlng, a potem odrzuca te, które nie pasują do określonych typów adresów. Obsługiwane są te wartości:
    • street_address wskazuje dokładny adres.
    • route wskazuje nazwaną trasę (np. „US 101”).
    • intersection to główne skrzyżowanie, które obejmuje zwykle 2 główne drogi.
    • political oznacza podmiot polityczny. Zwykle ten typ oznacza wielokąt związany z administracją cywilną.
    • country wskazuje krajowy podmiot polityczny i zazwyczaj jest to najwyższy typ kolejności zwracany przez geokodera.
    • administrative_area_level_1 oznacza podmiot cywilny pierwszego rzędu poniżej poziomu kraju. W Stanach Zjednoczonych te poziomy administracyjne to stany. Nie we wszystkich krajach obowiązują te poziomy administracyjne. W większości przypadków krótkie nazwy admin_area_level_1 są ściśle dopasowane do podziałów według normy ISO 3166-2 i innych często rozpowszechnianych list. Nie możemy jednak zagwarantować, że wyniki z kodowania geograficznego są uzależnione od różnych sygnałów i danych o lokalizacji.
    • administrative_area_level_2 oznacza podmiot cywilny drugiego rzędu poniżej poziomu kraju. W Stanach Zjednoczonych te poziomy administracyjne to hrabstwa. Nie we wszystkich krajach obowiązują te poziomy administracyjne.
    • administrative_area_level_3 oznacza podmiot cywilny trzeciego poziomu poniżej poziomu kraju. Ten typ oznacza niewielki podział cywilny. Nie we wszystkich krajach obowiązują te poziomy administracyjne.
    • administrative_area_level_4 oznacza podmiot cywilny czwartego rzędu poniżej poziomu kraju. Ten typ oznacza niewielki podział cywilny. Nie we wszystkich krajach obowiązują te poziomy administracyjne.
    • administrative_area_level_5 oznacza podmiot cywilny piątego rzędu poniżej poziomu kraju. Ten typ oznacza niewielki podział cywilny. Nie we wszystkich krajach obowiązują te poziomy administracyjne.
    • administrative_area_level_6 oznacza podmiot cywilny szóstego rzędu poniżej poziomu kraju. Ten typ oznacza niewielki podział cywilny. Nie we wszystkich krajach obowiązują te poziomy administracyjne.
    • administrative_area_level_7 oznacza podmiot cywilny siódmego rzędu poniżej poziomu kraju. Ten typ oznacza niewielki podział cywilny. Nie we wszystkich krajach obowiązują te poziomy administracyjne.
    • colloquial_area wskazuje często używaną alternatywną nazwę encji.
    • locality oznacza miasto lub miejscowość, w której on działa.
    • sublocality wskazuje podmiot cywilny pierwszego rzędu poniżej danego rejonu. W przypadku niektórych lokalizacji może pojawić się jeden z dodatkowych typów: od sublocality_level_1 do sublocality_level_5. Każdy poziom podrejonu jest podmiotem cywilnym. Większe liczby oznaczają mniejszy obszar geograficzny.
    • neighborhood wskazuje nazwę okolicy
    • premise oznacza nazwaną lokalizację, zwykle budynek lub zespół budynków o wspólnej nazwie
    • subpremise wskazuje element pierwszego rzędu poniżej nazwanej lokalizacji, zwykle pojedynczy budynek w zbiorze budynków o wspólnej nazwie
    • plus_code to zakodowane odwołanie do lokalizacji pobrane na podstawie szerokości i długości geograficznej. Kody Plus Code mogą zastąpić adresy w miejscach, gdzie nie istnieją (gdzie budynki nie są numerowane lub nie mają nazw ulic). Więcej informacji znajdziesz na stronie https://plus.codes.
    • postal_code wskazuje kod pocztowy używany w danym kraju do adresowania przesyłek pocztowych.
    • natural_feature oznacza ważny obiekt naturalny.
    • airport wskazuje lotnisko.
    • park wskazuje park nazwany.
    • point_of_interest wskazuje nazwane miejsce. Są to zwykle ważne lokalne jednostki, których nie da się łatwo umieścić w innych kategoriach, np. „Empire State Building” lub „wieża Eiffla”.
  • location_type – filtr obejmujący co najmniej 1 typ lokalizacji rozdzielony pionową kreską (|). Jeśli parametr zawiera wiele typów lokalizacji, interfejs API zwraca wszystkie adresy pasujące do dowolnego z nich. Uwaga na temat przetwarzania: parametr location_type restrict wyszukiwania do określonych typów lokalizacji. location_type działa raczej jak filtr po wyszukiwaniu: interfejs API pobiera wszystkie wyniki dla określonego elementu latlng, a potem odrzuca te, które nie pasują do określonych typów lokalizacji. Obsługiwane są te wartości:
    • Funkcja "ROOFTOP" zwraca tylko te adresy, dla których Google ma informacje o lokalizacji z dokładnością do dokładnego adresu.
    • "RANGE_INTERPOLATED" zwraca tylko adresy zgodne z przybliżeniem (zwykle na drodze) z interpolacją między 2 precyzyjnymi punktami (np. skrzyżowaniami). Zakres interpolowany zazwyczaj oznacza, że geokody dachów nie są dostępne dla danego adresu.
    • Funkcja "GEOMETRIC_CENTER" zwraca tylko centra geometryczne lokalizacji, np. linię łamaną (na przykład ulicę) lub wielokąt (region).
    • Funkcja "APPROXIMATE" zwraca tylko adresy, które są opisane jako przybliżone.

Jeśli obecne są zarówno filtry result_type, jak i location_type, interfejs API zwróci tylko wyniki, które pasują zarówno do wartości result_type, jak i z wartości location_type. Jeśli żadna z wartości filtrów nie jest akceptowana, interfejs API zwraca wartość ZERO_RESULTS.

Przykład odwrotnego geokodowania

To zapytanie zawiera wartość szerokości i długości geograficznej lokalizacji na Brooklynie:

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

To 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 geokoder zwrócił więcej niż jeden wynik. Wyniki wyszukiwania "formatted_address" obejmują nie tylko adresy pocztowe, ale także wszelkie informacje o lokalizacji geograficznej. Na przykład podczas geokodowania punktu w mieście Chicago punkt geokodowany można oznaczyć jako adres, miasto (Chicago), stan (Illinois) lub kraj (Stany Zjednoczone). Wszystkie są „adresami” dla geokodera. Odwrotny geokoder zwraca dowolny z tych typów jako prawidłowe wyniki.

Odwrotny geokoder dopasowuje jednostki polityczne (kraje, prowincje, miasta i dzielnice), adresy i kody pocztowe.

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 precyzyjnego adresu pocztowego do mniej szczegółowych podmiotów politycznych, takich jak dzielnice, miasta, hrabstwa i stany. W tym przypadku najbardziej widoczny jest zazwyczaj dokładny adres. Jeśli chcesz dopasować określony typ adresu, zapoznaj się z sekcją poniżej, w której opisano ograniczanie wyników według typu. Z tego powodu położenie wyników może się różnić.

Odwrotne geokodowanie odfiltrowane według typu

Poniższy przykład filtruje zwrócone adresy, aby uwzględniały tylko te z typem lokalizacji ROOFTOP i typem 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: tych filtrów można używać tylko przy odwrotnym geokodowaniu.

Odwrotne odpowiedzi geokodowania

Format odpowiedzi odwrotnej geokodowania jest taki sam jak odpowiedzi na polecenie geokodowania. Więcej informacji znajdziesz w sekcji Odpowiedzi geokodowania. Poniżej znajdziesz kody stanu możliwe w odpowiedzi na odwrotne geokodowanie.

Odwracanie kodów stanu geokodowania

Pole "status" w obiekcie odpowiedzi Geocoding 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 że został zwrócony co najmniej 1 adres.
  • "ZERO_RESULTS" oznacza, że odwrotne geokodowanie się udało, ale nie zwróciło żadnych wyników. Może się tak zdarzyć, jeśli geokoder otrzymał latlng w lokalizacji zdalnej.
  • "OVER_QUERY_LIMIT" oznacza, że przekraczasz 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" oznacza zazwyczaj jedną z tych wartości:
    • Brak zapytania (address, components lub latlng).
    • Podano nieprawidłową wartość result_type lub location_type.
  • "UNKNOWN_ERROR" oznacza, że nie udało się przetworzyć żądania z powodu błędu serwera. Jeśli spróbujesz ponownie, żądanie może się powieść.

Odwrócone kody Plus Code

Pole plus_code w odpowiedzi na dane geokodowanie zawiera kod plus, który najlepiej określa szerokość i długość geograficzną zapytania. Dodatkowo 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.