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

Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

Termin geokodowanie odnosi się zwykle do przekształcania adresu w formie czytelnej dla człowieka w lokalizację na mapie. Proces odwrotny, czyli przekształcanie lokalizacji na mapie w adres czytelny dla człowieka, jest nazywany odwrotnym geokodowaniem.

Żądania odwrotnego geokodowania

Wymagane parametry

  • latlng – współrzędne geograficzne określające lokalizację, dla której chcesz uzyskać najbliższy adres w formacie czytelnym dla człowieka.
  • 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 geokodowania zwrotnego:

  • 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 parametr language nie zostanie podany, geokoder spróbuje użyć preferowanego języka określonego w nagłówku Accept-Language lub języka natywnego domeny, z której wysłano żą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 w języku lokalnym, a w razie potrzeby transliteruje je na pismo czytelne dla użytkownika, uwzględniając preferowany język. Wszystkie pozostałe adresy są zwracane w preferowanym języku. Wszystkie komponenty adresu są zwracane w tym samym języku, który jest wybierany na podstawie pierwszego komponentu.
    • Jeśli nazwa nie jest dostępna w preferowanym języku, geokoder użyje najbliższego dopasowania.
  • region – kod regionu określony jako dwuznakowa wartość ccTLD („domena najwyższego poziomu”). W zależności od obowiązujących przepisów parametr ten może też wpływać na wyniki.
  • result_type – filtr zawierający co najmniej 1 typ adresu oddzielony znakiem potoku (|). 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. Zamiast tego symbol result_type działa jako filtr po wyszukiwaniu: interfejs API pobiera wszystkie wyniki dla określonego parametru latlng, a następnie odrzuca te wyniki, które nie pasują do określonych typów adresów. Obsługiwane są te wartości:

    Typy adresów i typy komponentów adresu

    Tablica types w treści GeocodeResult w odpowiedzi wskazuje typ adresu. Przykłady typów adresów to adres ulicy, kraj lub jednostka polityczna. Tablica types w polu AddressComponents treści GeocodeResult wskazuje typ każdej części adresu. Mogą to być np. numer ulicy lub kraj.

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

    Obsługiwane są te typy, które są zwracane w tablicach typu adresu i typu komponentu adresu:

    Typ adresu Opis
    street_address dokładny adres.
    route Nazwa trasy (np. „US 101”).
    intersection Główne skrzyżowanie, zwykle dwóch głównych dróg.
    political podmiot polityczny; Zwykle ten typ wskazuje wielokąt przedstawiający jakąś jednostkę administracji cywilnej.
    country Narodowy podmiot polityczny, zwykle typ najwyższego rzędu 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 mają te poziomy administracyjne. W większości przypadków administrative_area_level_1krótkie nazwy będą ściśle odpowiadać podziałom ISO 3166-2 i innym powszechnie rozpowszechnianym listom, ale nie jest to gwarantowane, 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 mają te poziomy administracyjne.
    administrative_area_level_3 Jednostka administracyjna trzeciego rzędu poniżej poziomu kraju. Ten typ wskazuje na mniejszą jednostkę podziału administracyjnego. Nie wszystkie kraje mają te poziomy administracyjne.
    administrative_area_level_4 Jednostka administracyjna czwartego rzędu poniżej poziomu kraju. Ten typ wskazuje na mniejszą jednostkę podziału administracyjnego. Nie wszystkie kraje mają te poziomy administracyjne.
    administrative_area_level_5 Jednostka administracyjna piątego rzędu poniżej poziomu kraju. Ten typ wskazuje na mniejszą jednostkę podziału administracyjnego. Nie wszystkie kraje mają te poziomy administracyjne.
    administrative_area_level_6 Jednostka administracyjna szóstego rzędu poniżej poziomu kraju. Ten typ wskazuje na mniejszą jednostkę podziału administracyjnego. Nie wszystkie kraje mają te poziomy administracyjne.
    administrative_area_level_7 Jednostka administracyjna siódmego rzędu poniżej poziomu kraju. Ten typ wskazuje na mniejszą jednostkę podziału administracyjnego. Nie wszystkie kraje mają te poziomy administracyjne.
    colloquial_area Powszechnie używana nazwa alternatywna elementu.
    locality podmiot polityczny w postaci miasta lub miejscowości;
    sublocality Jednostka administracyjna pierwszego rzędu poniżej miejscowości. W przypadku niektórych lokalizacji może być wyświetlany jeden z dodatkowych typów: sublocality_level_1–sublocality_level_5. Każdy poziom podlokalizacji 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 Adresowalny obiekt poniżej poziomu lokalu, np. mieszkanie, lokal lub apartament.
    plus_code Zakodowany odnośnik do lokalizacji, który jest wyznaczany na podstawie szerokości i długości geograficznej. Kody Plus Code mogą zastępować adresy w miejscach, w których nie istnieją (gdzie budynki nie mają numerów lub ulice nie mają nazw). Więcej informacji znajdziesz na https://plus.codes.
    postal_code Kod pocztowy używany do adresowania przesyłek pocztowych na terenie danego kraju.
    natural_feature wyraźny obiekt naturalny,
    airport lotnisko,
    park Nazwany park.
    point_of_interest Nazwane ciekawe miejsce. Zazwyczaj są to znane lokalne obiekty, które nie pasują do żadnej innej kategorii, np. „Empire State Building” lub „Wieża Eiffla”.

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

  • location_type – filtr zawierający co najmniej 1 rodzaj lokalizacji, rozdzielony znakiem potoku (|). Jeśli parametr zawiera kilka rodzajów lokalizacji, interfejs API zwraca wszystkie adresy pasujące do dowolnego z tych rodzajów. Uwaga dotycząca przetwarzania: parametr location_type nie ogranicza wyszukiwania do określonych typów lokalizacji. Zamiast tego parametr location_type działa jako filtr po wyszukiwaniu: interfejs API pobiera wszystkie wyniki dla określonego parametru latlng, a następnie odrzuca te wyniki, które nie pasują do określonych typów lokalizacji. Obsługiwane są te wartości:
    • "ROOFTOP" zwraca tylko adresy, w przypadku których Google ma informacje o lokalizacji o dokładności do adresu ulicy.
    • "RANGE_INTERPOLATED" zwraca tylko adresy, które odzwierciedlają przybliżone położenie (zwykle na drodze) interpolowane między 2 dokładnymi punktami (np. skrzyżowaniami). Interpolowany zakres zwykle oznacza, że dla adresu ulicy nie są dostępne geokody dachu.
    • "GEOMETRIC_CENTER" zwraca tylko geometryczne środki lokalizacji, takich jak linia łamana (np. ulica) lub wielokąt (region).
    • "APPROXIMATE" zwraca tylko adresy, które są przybliżone.
  • extra_computations – użyj tego parametru, aby określić te dodatkowe funkcje w odpowiedzi: Aby włączyć kilka z tych funkcji w tym samym żądaniu interfejsu API, w żądaniu uwzględnij parametr extra_computations dla każdej funkcji, np.: 
    extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES

Jeśli oba filtry result_type i location_type są obecne, interfejs API zwraca tylko te wyniki, które pasują do obu wartości result_type i 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 w 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> ...

Pamiętaj, że geokoder zwrotny zwrócił więcej niż 1 wynik. "formatted_address" Wyniki to nie tylko adresy pocztowe, ale też wszelkie sposoby geograficznego określania lokalizacji. Na przykład podczas geokodowania punktu w Chicago może on być oznaczony jako adres ulicy, miasto (Chicago), stan (Illinois) lub kraj (Stany Zjednoczone). Wszystkie są dla geokodera „adresami”. Geokoder zwrotny zwraca dowolny z tych typów jako prawidłowy wynik.

Geokoder odwrotny dopasowuje jednostki administracyjne (kraje, prowincje, miasta i dzielnice), adresy ulic i kody pocztowe.

Pełna lista wartości formatted_address zwróconych przez poprzednie zapytanie jest widoczna 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 ulic po mniej szczegółowe jednostki administracyjne, takie jak dzielnice, miasta, hrabstwa i stany. Najdokł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 położenie wyników względem siebie może się różnić.

Odwrotne geokodowanie filtrowane według typu

W tym przykładzie odfiltrowano zwrócone adresy, 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ą ważne tylko w przypadku geokodowania zwrotnego.

Odpowiedzi odwrotnego geokodowania

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

Kody stanu odwrotnego geokodowania

Pole "status" w obiekcie odpowiedzi Geocoding zawiera stan żądania i może zawierać informacje do debugowania, które pomogą Ci ustalić, dlaczego geokodowanie zwrotne nie działa. Pole "status" może zawierać te wartości:

  • "OK" oznacza, że nie wystąpiły żadne błędy i zwrócono co najmniej jeden adres.
  • "ZERO_RESULTS" oznacza, że geokodowanie zwrotne zakończyło się powodzeniem, ale nie zwróciło żadnych wyników. Może się tak zdarzyć, jeśli geokoder otrzymał latlng w odległej lokalizacji.
  • "OVER_QUERY_LIMIT" oznacza, że przekraczasz limit.
  • "REQUEST_DENIED" oznacza, że prośba została odrzucona. Może to być spowodowane tym, że żądanie zawiera parametr result_type lub location_type, ale nie zawiera klucza interfejsu API.
  • "INVALID_REQUEST" zwykle oznacza jedną z tych sytuacji:
    • Brak zapytania (address, components lub latlng).
    • Podano nieprawidłowy element 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 interfejsu Geocoding API zawiera kod plus, który najlepiej przybliża podaną 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 kod plus. Odległość między zdekodowanym kodem plus a punktem żądania jest gwarantowana i wynosi mniej niż 10 metrów.