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

Termin geokodowanie zwykle oznacza tłumaczenie adresu zrozumiałego dla człowieka na lokalizację na mapie. Odwrotny proces, czyli tłumaczenie lokalizacji z mapy na zrozumiały dla człowieka adres, to odwrotne geokodowanie.

Żądania odwrotnego geokodowania

Wymagane parametry

  • latlng – współrzędne szerokości i długości geograficznej określające lokalizację, w której przypadku chcesz znaleźć najbliższy, czytelny 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żna uwzględnić w żądaniu odwrotnego geokodowania:

  • language – język, w którym wyświetlane są 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 nie zostanie podany language, geokoder spróbuje użyć preferowanego języka określonego w nagłówku Accept-Language lub języka ojczystego domeny, z której wysyłane jest żądanie.
    • Geokoder dokłada wszelkich starań, aby podać czytelny adres zarówno dla użytkownika, jak i lokalnego. W tym celu zwraca adresy w języku lokalnym, transliterację na skrypt w razie potrzeby zrozumiały dla użytkownika i zachowując preferowany język. Pozostałe 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 jest niedostępna w preferowanym języku, geokoder użyje najbliższego odpowiednika.
  • region – kod regionu, podany jako dwuznakowa wartość ccTLD („domena najwyższego poziomu”). Parametr może też wpływać na wyniki na podstawie obowiązującego prawa.
  • result_type – filtr obejmujący co najmniej 1 typ adresu rozdzielone pionową kreską (|). Jeśli parametr zawiera kilka typów adresów, interfejs API zwraca wszystkie adresy pasujące do dowolnego z tych typów. Uwaga na temat przetwarzania: parametr result_type nie restrict wyszukiwania do określonych typów adresów. result_type działa raczej jak filtr po wyszukiwaniu: interfejs API pobiera wszystkie wyniki dla określonego elementu latlng, a potem odrzuca wyniki, 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. „E701”).
    • intersection oznacza główne skrzyżowanie, które obejmuje zwykle 2 główne drogi.
    • political oznacza podmiot polityczny. Ten typ oznacza zwykle wielokąt związany z administracją cywilną.
    • country oznacza krajowy podmiot polityczny i zwykle jest najwyższym typem porządku zwracanym przez Geocoder.
    • administrative_area_level_1 oznacza podmiot cywilny pierwszego rzędu poniżej poziomu kraju. W Stanach Zjednoczonych te poziomy administracyjne są stanami. Nie we wszystkich krajach obowiązują te poziomy administracyjne. W większości przypadków krótkie nazwy są zbliżone do nazw z normą ISO 3166-2 i innych często rozpowszechnianych list. Nie możemy tego jednak zagwarantować, ponieważ wyniki geokodowania opierają się na różnych sygnałach i danych o lokalizacji.
    • administrative_area_level_2 oznacza podmiot cywilny drugiego rzędu poniżej poziomu kraju. W Stanach Zjednoczonych te poziomy administracyjne są hrabstwami. Nie we wszystkich krajach obowiązują te poziomy administracyjne.
    • administrative_area_level_3 oznacza podmiot cywilny trzeciego rzędu 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ą nazwę alternatywną jednostki.
    • locality oznacza miejskie podmioty polityczne.
    • sublocality wskazuje podmiot cywilny pierwszego rzędu poniżej rejonu. W przypadku niektórych lokalizacji może zostać wyświetlony 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 oznacza element pierwszego rzędu pod nazwaną lokalizacją, zwykle pojedynczy budynek należący do zespołu budynków o wspólnej nazwie
    • plus_code oznacza zakodowane odniesienie do lokalizacji na podstawie szerokości i długości geograficznej. Kody plus mogą zastąpić adresy ulic w miejscach, w których one nie istnieją (gdzie budynki nie są ponumerowane lub ulice nie mają nazw). 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 wskazuje ważny obiekt naturalny.
    • airport oznacza lotnisko.
    • park wskazuje park nazwany.
    • point_of_interest wskazuje nazwane miejsce. Takie ważne miejsca to zwykle doskonałe lokalne jednostki, których nie da się łatwo przypisać do innych kategorii, takich jak „Empire State Building” czy „wieża Eiffla”.
  • location_type – filtr obejmujący co najmniej 1 typ lokalizacji rozdzielonych pionową kreską (|). Jeśli parametr zawiera wiele typów lokalizacji, interfejs API zwraca wszystkie adresy pasujące do dowolnego z tych typów. Uwaga na temat przetwarzania: parametr location_type restrict wyszukiwania do określonych typów lokalizacji. Zamiast tego location_type działa 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 wartości:
    • "ROOFTOP" zwraca tylko te adresy, w przypadku których Google dysponuje informacjami o lokalizacji z dokładną dokładnością do adresu.
    • "RANGE_INTERPOLATED" zwraca tylko adresy, które odzwierciedlają przybliżenie (zwykle na drodze) interpolowane między 2 precyzyjnymi punktami (np. skrzyżowaniami). Zakres interpolowany zazwyczaj oznacza, że geokody dachów na dachach są niedostępne w przypadku adresów.
    • "GEOMETRIC_CENTER" zwraca tylko centra geometryczne lokalizacji, takie jak linia łamana (np. ulica) lub wielokąt (region).
    • "APPROXIMATE" zwraca tylko adresy sklasyfikowane jako przybliżone.

Jeśli obecne są zarówno filtry result_type, jak i location_type, interfejs API zwróci tylko te wyniki, które pasują zarówno do wartości result_type, jak i z wartości 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 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

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

Odwrotny geokoder dopasowuje podmioty 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 szczegółowych adresów pocztowych po mniej szczegółowe podmioty polityczne, takie jak dzielnice, miasta, hrabstwa i stany. Bardziej dokładny adres jest zwykle najbardziej widocznym wynikiem, jak w tym przypadku. Jeśli chcesz dopasować wyniki do konkretnego typu adresu, zapoznaj się z sekcją poniżej o ograniczaniu 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 pokazuje filtrowanie zwróconych adresów, tak aby uwzględniały tylko adresy o typie lokalizacji ROOFTOP i typie 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 można stosować tylko do odwrotnego geokodowania.

Odpowiedzi na odwrotne geokodowanie

Format odpowiedzi wykorzystującej odwrotne geokodowanie jest taki sam jak odpowiedzi geokodowania. Zobacz odpowiedzi na geokodowanie. Poniżej znajdziesz kody stanu możliwe w odpowiedzi na odwrotne geokodowanie.

Odwrotne kody stanu geokodowania

Pole "status" w obiekcie odpowiedzi Geocoding 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" 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 przekazał 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" zazwyczaj oznacza 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 zostać zrealizowane.

Odwrotne geokodowanie Plus Code

Pole plus_code w odpowiedzi na żądanie geokodowania 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 typu plus_code i adres zawierający kod plus. Gwarantowana jest, że odległość między zdekodowanym kodem plus a punktem żądania nie przekracza 10 metrów.