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

Termin geokodowanie odnosi się ogólnie do tłumaczenia zrozumiałego dla człowieka adres w lokalizacji na mapie. Ten proces tłumaczenie lokalizacji na mapie na adres czytelny dla człowieka to tzw. odwrotne geokodowanie.

Odwrotne żądania geokodowania

Wymagane parametry

  • latlng – szerokość i długość geograficzną. czyli najbliższą lokalizację, łatwy do odczytania przez człowieka.
  • key – klucz interfejsu API Twojej aplikacji. Ten klucz identyfikuje Twojej aplikacji na potrzeby zarządzania limitami. Dowiedz się, jak uzyskaj klucz.

Parametry opcjonalne

Są to parametry opcjonalne, które możesz umieścić odwrotnie żądanie geokodowania:

  • language – język, w którym mają być wyświetlane 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 domyślnego języka domeny, z której wysłano żądanie.
    • Geokoder stara się podać adres, który łatwy do odczytania zarówno przez użytkownika, jak i lokalnie. Aby osiągnąć ten cel, zwraca adresy ulic w języku lokalnym po transliteracji na skryptach odczytanych przez użytkownika w razie potrzeby, obserwując preferowany język. Wszystkie inne adresy są zwracane w preferowanym języku. Wszystkie elementy adresu są zwracane w tym samym języku, który jest wybierany na podstawie pierwszego elementu.
    • Jeśli nazwa nie jest dostępna w preferowanym języku, geokoder użyje jak najbliższe znaczeniem.
  • region – kod regionu podany jako 2-znakowa wartość ccTLD („domena najwyższego poziomu”). Może on też wpływać na to, na podstawie obowiązującego prawa.
  • result_type – filtr obejmujący co najmniej jeden typ adresu, oddzielone pionową kreską (|). Jeśli parametr zawiera wiele wartości adresy, 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 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 większe przecięcie, zwykle składające się z dwóch dróg głównych.
    • political oznacza podmiot polityczny. Zwykle ten typ wskazuje poligon administracji cywilnej.
    • country oznacza krajowy podmiot polityczny i jest zwykle jest to najwyższy typ kolejności zwracany przez Geocoder.
    • administrative_area_level_1 wskazuje podmiot prawny 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 parametr administracyjny_area_level_1 krótkie nazwy będą dokładnie odpowiadać podziałom zgodnym z normą ISO 3166-2 oraz innymi powszechnymi publikowane listy; Nie jest to jednak gwarantowane, ponieważ wyniki geokodowania na podstawie różnych sygnałów i danych o lokalizacji.
    • administrative_area_level_2 oznacza jednostkę prawną drugiego rzędu na poziomie niższym niż kraj. W Stanach Zjednoczonych są to hrabstwa. Nie wszystkie kraje mają te poziomy administracyjne.
    • administrative_area_level_3 oznacza rodzaj cywilny 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 czwarty poziom podmiotu cywilnego poniżej poziomu kraju. Ten typ wskazuje mniejszy podział administracyjny. Nie wszystkie kraje mają te poziomy administracyjne.
    • administrative_area_level_5 wskazuje jednostkę prawną piątego rzędu poniżej poziomu kraju. Ten typ wskazuje mniejszy podział administracyjny. Nie we wszystkich krajach obowiązują te poziomy administracyjne.
    • administrative_area_level_6 oznacza cywilny 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 miasto lub miejscowość podmiotu zabezpieczeń.
    • sublocality oznacza jednostkę cywilną pierwszego rzędu poniżej lokalizacji. W przypadku niektórych lokalizacji może być używany jeden z dodatkowych typów: sublocality_level_1 do sublocality_level_5. Każdy poziom podrejonu jest podmiotem cywilnym. Im większa liczba, tym mniejszy obszar geograficzny.
    • neighborhood oznacza nazwany dzielnicę
    • premise wskazuje nazwane lokalizację, zwykle budynek lub zespół budynków o takiej samej nazwie
    • subpremise oznacza element pierwszego rzędu pod nazwanym lokalizacji, zwykle pojedynczego budynku w obrębie zespołu budynków imię i nazwisko
    • plus_code oznacza zakodowane odniesienie do lokalizacji, pochodne od 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). Więcej informacji znajdziesz na stronie https://plus.codes.
    • postal_code oznacza kod pocztowy używany do adresowania. na terenie tego kraju.
    • natural_feature wskazuje charakterystyczny element przyrodniczy.
    • airport oznacza lotnisko.
    • park oznacza park o nazwie.
    • point_of_interest wskazuje 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 obejmujący co najmniej jeden typ lokalizacji, oddzielone pionową kreską (|). Jeśli parametr zawiera wiele wartości typ lokalizacji, interfejs API zwróci wszystkie adresy pasujące do dowolnego z tych typów. Uwaga na temat przetwarzania: parametr location_type nie ograniczyć wyszukiwanie 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 z dokładnością do adresu ulicy.
    • Funkcja "RANGE_INTERPOLATED" zwraca tylko adresy, które odzwierciedlają przybliżoną (zwykle na drodze) interpolację między dwoma zawężone punkty (np. skrzyżowania). Interpolowany zakres zazwyczaj wskazuje, że kody geoadresowe dachów są niedostępne dla adresu ulicznego.
    • "GEOMETRIC_CENTER" zwraca tylko dane geometryczne środki lokalizacji, takie jak linia łamana (na przykład ulica) lub wielokąt (region).
    • Funkcja "APPROXIMATE" zwraca tylko adresy, które są w sposób przybliżony.
  • extra_computations – użyj tego parametru, aby określić parametr następujące dodatkowe funkcje w odpowiedzi: . Aby włączyć wiele z tych funkcji w tym samym żądaniu do interfejsu API, dołącz parametr extra_computations w żądaniu dla każdej funkcji, np.: 
    extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES

Jeśli podane są filtry result_type i location_type, 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

Następujące zapytanie zawiera wartość szerokości/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 następujący 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 geokodownik zwrócił więcej niż 1 wynik. Wyniki w usłudze "formatted_address" to nie tylko adresy pocztowe, w jakikolwiek sposób określić położenie geograficzne. Podczas geokodowania punktu w mieście Chicago może on zostać oznaczony jako adres ulicy, miasto (Chicago), stan (Illinois) lub kraj (Stany Zjednoczone). Wszystkie są „adresami” do geokodera. Odwrotny geokodownik zwraca dowolny z tych typów jako prawidłowe wyniki.

Geokodowanie odwrotne umożliwia dopasowanie jednostek politycznych (krajów, miast, dzielnic), adresów ulic i kodów pocztowych.

Pełną listę wartości funkcji formatted_address zwróconych przez poprzednie zapytanie zostało wyświetlone 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ółowego adresu ulicy do mniej szczegółowych jednostek administracyjnych, takich jak dzielnice, miasta, powiaty i stany. W tym przypadku bardziej dokładny adres jest zwykle najbardziej widocznym wynikiem. Jeśli chcesz dopasować określony typ Więcej informacji znajdziesz w sekcji Ograniczenia wyniki według typu. Z tego powodu lokalizacja wyników w stosunku do siebie może się różnić.

Odwrotne geokodowanie filtrowane według typu

W tym przykładzie zwracane adresy są filtrowane tak, aby uwzględnić 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 działają tylko w przypadku odwrotne geokodowanie.

Odwrotne geokodowanie odpowiedzi

Format odwrotnej odpowiedzi geokodowania jest taki sam jak danych geokodowania . Zobacz odpowiedzi geokodowania. Poniżej znajdują się kody stanu możliwe w przypadku odwrotnej odpowiedzi geokodowania.

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 i dowiedzieć się, dlaczego odwrotne geokodowanie nie działa. "status" może zawierać następujące wartości:

  • "OK" oznacza, że nie wystąpiły żadne błędy i co najmniej jeden .
  • "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 otrzymał latlng w odległej lokalizacji.
  • "OVER_QUERY_LIMIT" oznacza, że przekroczono limit miejsca na dane.
  • "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" zwykle oznacza jedno z tych:
    • Zapytanie (address, components lub latlng).
    • Nieprawidłowa wartość result_type lub location_type została danej wartości.
  • "UNKNOWN_ERROR" oznacza, że nie udało się zrealizować żądania z powodu błędu serwera. Żądanie może się powieść, jeśli spróbujesz ponownie.

Kody plus odwrotne geokodowanie

Pole plus_code w odpowiedzi Geocoding zawiera kod plus, który najlepiej określa w przybliżeniu długość i szerokość geograficzną danego zapytania. Dodatkowo tablica wyników JSON w większości przypadków zawiera pełne geokodowanie wynik o typie plus_code i adresie zawierającym plus w kodzie. Odległość między zdekodowanym kodem plus a punktem żądania wynosi musi być poniżej 10 metrów.