Żą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 długości i szerokości geograficznej określające lokalizację, w której chcesz znaleźć najbliższy, czytelny dla człowieka adres.
  • key – klucz interfejsu 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ć zwracane 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 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 zostanie wysłane żą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 czytelnej dla użytkownika w odpowiednim języku. Pozostałe adresy są zwracane w preferowanym języku. Wszystkie 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 stosuje najbliższe dopasowanie.
  • region – kod regionu określony jako dwuznakowa wartość domeny ccTLD („domeny najwyższego poziomu”). Ten parametr może też wpływać na wyniki na podstawie obowiązujących przepisów.
  • result_type – filtr zawierający co najmniej 1 typ adresu rozdzielony pionową kreską (|). Jeśli parametr zawiera kilka typów adresów, interfejs API zwróci wszystkie adresy pasujące do dowolnego z nich. 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 potem odrzuca te, które nie pasują do określonych typów adresów. Obsługiwane są następujące wartości:
    • street_address wskazuje dokładny adres.
    • route oznacza trasę z nazwą (np. „E101”).
    • intersection oznacza główne skrzyżowanie, zwykle dwóch głównych dróg.
    • political oznacza podmiot polityczny. Zwykle ten typ oznacza wielokąt reprezentujący administrację cywilną.
    • country wskazuje krajowy podmiot polityczny i jest zwykle najwyższym typem zamówienia zwracanym przez geokoder.
    • administrative_area_level_1 oznacza podmiot cywilny pierwszego rzędu poniżej poziomu kraju. W Stanach Zjednoczonych te poziomy administracyjne to stany. Nie wszystkie kraje mają te poziomy administracyjne. W większości przypadków krótkie nazwy administracyjne_area_level_1 będą bardzo zgodne z podgrupami w standardzie ISO 3166-2 i innymi rozpowszechnionymi listami. Nie jest to jednak gwarantowane, ponieważ wyniki geokodowania opierają się na różnych sygnałach i danych o lokalizacji.
    • administrative_area_level_2 oznacza jednostkę prawną drugiego rzędu na poziomie niższym niż kraj. W Stanach Zjednoczonych te poziomy 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ą taki poziom administracyjny.
    • administrative_area_level_5 oznacza podmiot cywilny 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 oznacza niewielką jednostkę cywilną. Nie wszystkie kraje mają te poziomy administracyjne.
    • colloquial_area wskazuje powszechnie używaną nazwę alternatywną podmiotu.
    • locality oznacza podmiot polityczny z własnym miastem lub miastem.
    • sublocality oznacza jednostkę cywilną pierwszego rzędu pod rejonem. W przypadku niektórych lokalizacji może być wymagany jeden z dodatkowych typów: sublocality_level_1 do sublocality_level_5. Każdy poziom podrejonu jest podmiotem cywilnym. Większe liczby oznaczają mniejszy obszar geograficzny.
    • neighborhood wskazuje nazwany dzielnicę.
    • premise wskazuje nazwę lokalizacji, zwykle budynku lub grupy budynków o wspólnej nazwie.
    • subpremise oznacza adresowany obiekt znajdujący się poniżej poziomu nieruchomości, np. mieszkanie, lokal czy apartament.
    • plus_code oznacza zakodowane odniesienie do lokalizacji na podstawie 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). Szczegółowe informacje znajdziesz na stronie https://plus.codes.
    • postal_code oznacza kod pocztowy używany do adresowania przesyłek pocztowych na terenie danego kraju.
    • natural_feature oznacza ważny obiekt naturalny.
    • airport oznacza lotnisko.
    • park oznacza park o nazwie.
    • point_of_interest oznacza 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 składający się z co najmniej jednego typu lokalizacji rozdzielony pionową kreską (|). Jeśli parametr zawiera kilka typów lokalizacji, interfejs API zwraca wszystkie adresy pasujące do dowolnego z tych typów. Uwaga na temat przetwarzania: parametr location_type nie ogranicza wyszukiwania do określonych 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 tym samym żądaniu do interfejsu API, umieść w żądaniu każdą funkcję parametr extra_computations, na przykład: 
    extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES

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 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 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> ...

Zwróć uwagę, że odwrotny geokoder zwrócił więcej niż jeden wynik. Wyniki wyszukiwania "formatted_address" to nie tylko adresy pocztowe, ale też dowolny sposób na określenie lokalizacji geograficznej. Na przykład podczas geokodowania punktu w mieście Chicago punkt ten może być oznaczony jako adres, 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.

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 szczegółowego adresu do bardziej szczegółowych jednostek politycznych, takich jak dzielnice, miasta, hrabstwa i województwa. W tym przypadku bardziej dokładny adres jest zwykle najbardziej widocznym wynikiem. Jeśli chcesz dopasować wyniki do określonego typu adresu, przeczytaj poniższą sekcję o ograniczaniu wyników według typu. Z tego powodu lokalizacje wyników w stosunku do siebie mogą się różnić.

Odwrotne geokodowanie według typu

Poniższy przykład filtruje zwrócone adresy, aby uwzględnić tylko te, których typ lokalizacji to ROOFTOP i adres 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 geokodowania

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 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 został przekazany przez latlng w lokalizacji zdalnej.
  • "OVER_QUERY_LIMIT" oznacza, że przekroczysz swój limit.
  • "REQUEST_DENIED" oznacza, że żądanie zostało odrzucone. 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. Jeśli spróbujesz jeszcze raz, żądanie może zostać zrealizowane.

Kody plus odwrotne geokodowanie

Pole plus_code w odpowiedzi Geocoding zawiera kod plus, który najlepiej określa szerokość i długość geograficzną wyszukiwanego hasła. 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 zdekodowanym kodem plus a punktem żądania musi być mniejsza niż 10 metrów.