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

Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

Termin geokodowanie ogólnie odnosi się do przekształcania adresu zrozumiałego dla człowieka na lokalizację na mapie. Proces odwrotny, czyli przekształcanie lokalizacji na mapie w adres zrozumiały dla człowieka, nazywa się odwrotnym geokodowaniem.

Żądania odwrotnego geokodowania

Wymagane parametry

  • latlng – współrzędne szerokości i długości geograficznej określające lokalizację, dla której chcesz uzyskać najbliższy adres zrozumiały dla człowieka.
  • key – klucz interfejsu API aplikacji. Ten klucz identyfikuje Twoją 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ć wyczerpująca.
    • Jeśli nie podasz parametru language, geokoder spróbuje użyć preferowanego języka określonego w nagłówku Accept-Language lub języka ojczystego domeny, z której wysłano żądanie.
    • Geokoder stara się podać adres, który jest czytelny zarówno dla użytkownika, jak i dla mieszkańców. Aby osiągnąć ten cel, zwraca adresy pocztowe w języku lokalnym, w razie potrzeby transliterowane na pismo czytelne 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 jest wybierany z pierwszego komponentu.
    • Jeśli nazwa nie jest dostępna w preferowanym języku, geokoder używa najbliższego dopasowania.
  • region – kod regionu określony jako dwuznakowa wartość ccTLD („domena najwyższego poziomu”). Parametr może też wpływać na wyniki zgodnie z obowiązującymi przepisami.
  • result_type – filtr obejmujący co najmniej 1 typ adresu, rozdzielone znakiem pionowej kreski (|). Jeśli parametr zawiera kilka typów adresów, interfejs API zwraca wszystkie adresy, które pasują do dowolnego z tych typów. Uwaga dotycząca przetwarzania: parametr result_type nie ogranicza wyszukiwania do określonych typów adresów. Parametr result_type działa raczej jako filtr po wyszukiwaniu: interfejs API pobiera wszystkie wyniki dla określonego parametru latlng, a następnie odrzuca te, które nie pasują do określonych typów adresów. Obsługiwane są te wartości:

    Typy adresów i typów komponentów adresów

    Tablica types w treści GeocodeResult w odpowiedzi wskazuje typ adresu. Przykłady typów adresów: adres pocztowy, kraj lub podmiot polityczny. Tablica types w polu AddressComponents obiektu GeocodeResult wskazuje typ każdej części adresu. Przykłady: numer domu lub kraj.

    Adresy mogą mieć wiele typów. Typy można traktować jako „tagi”. Na przykład wiele miast jest oznaczonych typami political i locality.

    Obsługiwane są te typy, które są zwracane zarówno w tablicach typów adresów, jak i tablicach typów komponentów adresów:

    Typ adresu Opis
    street_address dokładny adres,
    route nazwana trasa (np. „US 101”).
    intersection Główne skrzyżowanie, zwykle 2 głównych dróg.
    political Podmiot polityczny. Zwykle ten typ wskazuje wielokąt jakiejś administracji cywilnej.
    country Narodowy podmiot polityczny, zwykle najwyższy poziom zwracany przez geokoder.
    administrative_area_level_1 Jednostka administracyjna pierwszego rzędu poniżej poziomu kraju. W Stanach Zjednoczonych są to stany. Nie wszystkie kraje używają tych poziomów administracyjnych. W większości przypadków krótkie nazwy administrative_area_level_1 będą ściśle odpowiadać podregionom ISO 3166-2 i innym powszechnie używanym listom. Nie możemy jednak tego zagwarantować, ponieważ nasze wyniki geokodowania są oparte na różnych sygnałach i danych o lokalizacji.
    administrative_area_level_2 Jednostka administracyjna drugiego rzędu poniżej poziomu kraju. W Stanach Zjednoczonych są to hrabstwa. Nie wszystkie kraje używają tych poziomów administracyjnych.
    administrative_area_level_3 Jednostka administracyjna trzeciego rzędu poniżej poziomu kraju. Ten typ wskazuje mniejszą jednostkę administracyjną. Nie wszystkie kraje używają tych poziomów administracyjnych.
    administrative_area_level_4 Jednostka administracyjna czwartego rzędu poniżej poziomu kraju. Ten typ wskazuje mniejszą jednostkę administracyjną. Nie wszystkie kraje używają tych poziomów administracyjnych.
    administrative_area_level_5 Jednostka administracyjna piątego rzędu poniżej poziomu kraju. Ten typ wskazuje mniejszą jednostkę administracyjną. Nie wszystkie kraje używają tych poziomów administracyjnych.
    administrative_area_level_6 Jednostka administracyjna 6 rzędu poniżej poziomu kraju. Ten typ wskazuje mniejszą jednostkę administracyjną. Nie wszystkie kraje używają tych poziomów administracyjnych.
    administrative_area_level_7 Jednostka administracyjna 7 rzędu poniżej poziomu kraju. Ten typ wskazuje mniejszą jednostkę administracyjną. Nie wszystkie kraje używają tych poziomów administracyjnych.
    colloquial_area Powszechnie używana alternatywna nazwa podmiotu.
    locality podmiot polityczny miasta lub miejscowości;
    sublocality Jednostka administracyjna pierwszego rzędu poniżej poziomu miejscowości. W przypadku niektórych lokalizacji możesz otrzymać jeden z dodatkowych typów: od sublocality_level_1 do sublocality_level_5. Każdy poziom dzielnicy jest jednostką administracyjną. Im większa liczba, tym mniejszy obszar geograficzny.
    neighborhood nazwana okolica,
    premise Nazwana lokalizacja, zwykle budynek lub zespół budynków o wspólnej nazwie.
    subpremise Element podlegający adresowaniu poniżej poziomu budynku, np. mieszkanie, lokal lub apartament.
    plus_code Zakodowane odniesienie do lokalizacji, uzyskane na podstawie szerokości i długości geograficznej. Plus codes mogą zastępować adresy ulic tam, gdzie ich nie ma (gdzie budynki nie są ponumerowane lub ulice nie mają nazw). Więcej informacji znajdziesz na stronie https://plus.codes.
    postal_code Kod pocztowy używany do adresowania przesyłek pocztowych na terenie danego kraju.
    natural_feature Wyrazisty obiekt naturalny.
    airport Lotnisko.
    park park z nazwą,
    point_of_interest nazwane ciekawe miejsce, Zwykle są to znane lokalne obiekty, które nie pasują do żadnej innej kategorii, np. „Pałac Kultury i Nauki” czy „Wieża Eiffla”.

    Pusta lista typów oznacza, że nie ma znanych typów dla danego komponentu adresu (np. Lieu-dit we Francji).

  • location_type – filtr obejmujący co najmniej 1 typ lokalizacji, rozdzielone znakiem pionowej kreski (|). Jeśli parametr zawiera wiele typów lokalizacji, interfejs API zwraca wszystkie adresy, które pasują do dowolnego z tych typów. Uwaga dotycząca 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 następnie 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 z dokładnością do adresu ulicy.
    • "RANGE_INTERPOLATED" zwraca tylko adresy, które odzwierciedlają przybliżoną lokalizację (zwykle na drodze) interpolowaną między 2 dokładnymi punktami (np. skrzyżowaniami). Zakres interpolowany zwykle oznacza, że kody geograficzne dachu są niedostępne dla adresu.
    • "GEOMETRIC_CENTER" zwraca tylko geometryczne środki lokalizacji, takie jak linia łamana (np. ulica) lub wielokąt (region).
    • "APPROXIMATE" zwraca tylko adresy, które są oznaczone 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, uwzględnij w żądaniu parametr extra_computations dla każdej funkcji, na przykład: 
    extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES

Jeśli występują oba filtry (result_type i location_type), interfejs API zwraca tylko te wyniki, które pasują do wartości result_type i location_type. Jeśli żadna z wartości filtra nie jest akceptowalna, interfejs API zwraca błąd 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 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 odwrotne geokodowanie zwróciło więcej niż 1 wynik. Wyniki "formatted_address" to nie tylko adresy pocztowe, ale też dowolne nazwy geograficzne lokalizacji. Na przykład podczas geokodowania punktu w Chicago może on zostać oznaczony jako adres, miasto (Chicago), stan (Illinois) lub kraj (Stany Zjednoczone). Wszystkie te elementy są „adresami” dla geokodera. Odwrotny geokoder zwraca dowolny z tych typów jako prawidłowe wyniki.

Odwrotne geokodowanie 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ółowych adresów ulic po mniej szczegółowe jednostki polityczne, takie jak dzielnice, miasta, hrabstwa i stany. Dokładniejszy adres jest zwykle najbardziej widocznym wynikiem, tak jak w tym przypadku. Jeśli chcesz dopasować konkretny typ adresu, zapoznaj się z sekcją poniżej dotyczącą ograniczania wyników według typu. Z tego powodu lokalizacja wyników względem siebie może się różnić.

Odwrotne geokodowanie filtrowane według typu

W tym przykładzie zwracane adresy są filtrowane tak, aby uwzględniać 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ą prawidłowe tylko w przypadku odwrotnego geokodowania.

Odpowiedzi odwrotnego geokodowania

Format odpowiedzi odwrotnego geokodowania jest taki sam jak format odpowiedzi geokodowania. Zobacz Odpowiedzi geokodowania. Poniżej znajdziesz kody stanu, które mogą pojawić się w odpowiedzi na odwrotne geokodowanie.

Kody stanu odwrotnego geokodowania

Pole "status" w obiekcie odpowiedzi geokodowania 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" wskazuje, ż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 do geokodera przekazano latlng w odległej lokalizacji.
  • "OVER_QUERY_LIMIT" oznacza, że przekroczono limit.
  • "REQUEST_DENIED" oznacza, że prośba została odrzucona. Możliwe, że żądanie zawiera parametr result_type lub location_type, ale nie zawiera klucza interfejsu API.
  • "INVALID_REQUEST" zwykle oznacza jedną z tych sytuacji:
    • Brakuje zapytania (address, components lub latlng).
    • Podano nieprawidłowy parametr 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ść.

Odwrotne geokodowanie kodów Plus Code

Pole plus_code w odpowiedzi geokodowania zawiera kod Plus Code, który najlepiej przybliża zapytanie o szerokość i długość geograficzną. Dodatkowo tablica wyników JSON w większości przypadków zawiera pełny wynik geokodowania z typem plus_code i adresem zawierającym plus code. Odległość między zdekodowanym kodem Plus Code a punktem żądania nie przekracza 10 metrów.