Odwróć geokodowanie lokalizacji

Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

Odwrotne geokodowanie przekształca lokalizację na mapie w adres czytelny dla człowieka. Lokalizację na mapie reprezentujesz za pomocą współrzędnych geograficznych (szerokości i długości geograficznej).

Gdy wykonujesz odwrotne geokodowanie lokalizacji, odpowiedź zawiera:

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. Najdokładniejszy adres jest zwykle pierwszym wynikiem. Jeśli chcesz dopasować określony typ adresu, użyj parametru types.

Żądanie odwrotnego geokodowania

Żądanie odwrotnego geokodowania to żądanie HTTP GET. Lokalizację możesz podać jako nieustrukturyzowany ciąg znaków:

https://geocode.googleapis.com/v4beta/geocode/location/LATITUDE,LONGITUDE

lub jako strukturalny zestaw współrzędnych geograficznych reprezentowanych przez parametry zapytania:

https://geocode.googleapis.com/v4beta/geocode/location?location.latitude=LATITUDE&location.longitude=LONGITUDE

Format strukturalny jest zwykle używany podczas przetwarzania komponentów lokalizacji zarejestrowanych w formularzu HTML.

Wszystkie pozostałe parametry przekazuj jako parametry adresu URL lub w nagłówkach jako część żądania GET (w przypadku parametrów takich jak klucz interfejsu API czy maska pola). Na przykład:

Przekazywanie nieustrukturyzowanego ciągu znaków lokalizacji

Nieustrukturyzowana lokalizacja to lokalizacja sformatowana jako ciąg znaków oddzielonych przecinkami, zawierający współrzędne szerokości i długości geograficznej:

https://geocode.googleapis.com/v4beta/geocode/location/37.4225508,-122.0846338?key=API_KEY

lub w poleceniu curl:

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4beta/geocode/location/37.4225508,-122.0846338"

Przekazywanie lokalizacji strukturalnej

Określ lokalizację strukturalną za pomocą parametru zapytania location typu LatLng. Obiekt LatLng umożliwia określenie szerokości i długości geograficznej jako oddzielnych parametrów zapytania:

https://geocode.googleapis.com/v4beta/geocode/location?location.latitude=37.4225508&location.longitude=-122.0846338&key=API_KEY

Wysyłanie żądania za pomocą protokołu OAuth

Interfejs Geocoding API w wersji 4 obsługuje OAuth 2.0 na potrzeby uwierzytelniania. Aby używać protokołu OAuth z interfejsem Geocoding API, tokenowi OAuth musi być przypisany odpowiedni zakres. Interfejs Geocoding API obsługuje te zakresy do użycia z odwrotnym geokodowaniem:

  • https://www.googleapis.com/auth/maps-platform.geocode – używaj ze wszystkimi punktami końcowymi Geocoding API.
  • https://www.googleapis.com/auth/maps-platform.geocode.location – używaj tylko z parametrem GeocodeLocation do odwrotnego geokodowania.

Możesz też użyć ogólnego https://www.googleapis.com/auth/cloud-platformzakresu dla wszystkich punktów końcowych interfejsu Geocoding API. Ten zakres jest przydatny podczas programowania, ale nie w środowisku produkcyjnym, ponieważ jest to zakres ogólny, który umożliwia dostęp do wszystkich punktów końcowych.

Więcej informacji i przykładów znajdziesz w artykule Korzystanie z protokołu OAuth.

Odpowiedź na odwrotne geokodowanie

Odwrotne geokodowanie zwraca obiekt GeocodeLocationResponse, który zawiera:

  • Tablica results obiektów GeocodeResult, która reprezentuje miejsce.

    Geokoder zwrotny zwraca więcej niż 1 wynik w tablicy results. Wyniki to nie tylko adresy pocztowe, ale też wszelkie inne 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 te elementy są dla geokodera „adresami”. Geokoder zwrotny zwraca dowolny z tych typów jako prawidłowy wynik.

  • Pole plusCode typu PlusCode zawiera kod Plus Code, który najlepiej przybliża szerokość i długość geograficzną w żądaniu. Dodatkowo każdy element tablicy results zawiera kod plus. Odległość między zdekodowanym kodem plus a punktem żądania jest mniejsza niż 10 metrów.

Pełny obiekt JSON ma postać:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJV-FZF7i7j4ARo4ZOUoecZFU",
      "placeId": "ChIJV-FZF7i7j4ARo4ZOUoecZFU",
      "location": {
        "latitude": 37.422588300000008,
        "longitude": -122.0846489
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.421239319708512,
          "longitude": -122.0859978802915
        },
        "high": {
          "latitude": 37.423937280291511,
          "longitude": -122.08329991970851
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "addressComponents": [
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Mountain View",
          "shortText": "Mountain View",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Santa Clara County",
          "shortText": "Santa Clara County",
          "types": [
            "administrative_area_level_2",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "California",
          "shortText": "CA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "United States",
          "shortText": "US",
          "types": [
            "country",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "94043",
          "shortText": "94043",
          "types": [
            "postal_code"
          ]
        }
      ],
      "types": [
        "street_address"
      ],
      "plusCode": {
        "globalCode": "849VCW83+PM",
        "compoundCode": "CW83+PM Mountain View, CA, USA"
      }
    },
    {
      "place": "//places.googleapis.com/places/ChIJj61dQgK6j4AR4GeTYWZsKWw",
      "placeId": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
      "location": {
        "latitude": 37.4220541,
        "longitude": -122.08532419999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.4207051197085,
          "longitude": -122.08667318029148
        },
        "high": {
          "latitude": 37.423403080291493,
          "longitude": -122.08397521970851
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "addressComponents": [
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Mountain View",
          "shortText": "Mountain View",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Santa Clara County",
          "shortText": "Santa Clara County",
          "types": [
            "administrative_area_level_2",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "California",
          "shortText": "CA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "United States",
          "shortText": "US",
          "types": [
            "country",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "94043",
          "shortText": "94043",
          "types": [
            "postal_code"
          ]
        }
      ],
      "types": [
        "establishment",
        "point_of_interest"
      ],
      "plusCode": {
        "globalCode": "849VCWC7+RV",
        "compoundCode": "CWC7+RV Mountain View, CA, USA"
      }
    },
   ...
  ],
  "plusCode": {
    "globalCode": "849VCWF8+24H",
    "compoundCode": "CWF8+24H Mountain View, CA, USA"
  }
}

Wymagane parametry

  • lokalizacja

    Współrzędne szerokości i długości geograficznej określające miejsce, w którym chcesz uzyskać najbliższy adres w formacie czytelnym dla człowieka.

Parametry opcjonalne

  • languageCode

    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 nie podasz wartości languageCode, interfejs API domyślnie użyje wartości en. Jeśli podasz nieprawidłowy kod języka, interfejs API zwróci błąd INVALID_ARGUMENT.
    • Interfejs API stara się podać adres ulicy, który jest czytelny zarówno dla użytkownika, jak i 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, interfejs API użyje najbliższego dopasowania.
    • Preferowany język ma niewielki wpływ na zestaw wyników, które interfejs API wybiera do zwrócenia, oraz na kolejność, w jakiej są one zwracane. Geokoder interpretuje skróty w różny sposób w zależności od języka, np. skróty typów ulic lub synonimy, które mogą być prawidłowe w jednym języku, ale nie w innym.

  • regionCode

    Kod regionu jako wartość dwuznakowego kodu CLDR. Nie ma wartości domyślnej. Większość kodów CLDR jest identyczna z kodami ISO 3166-1.

    Podczas geokodowania adresu, czyli geokodowania do przodu, ten parametr może wpływać na wyniki usługi, ale nie może ich w pełni ograniczać do określonego regionu. Podczas geokodowania lokalizacji lub miejsca, geokodowania odwrotnego lub geokodowania miejsca ten parametr może służyć do formatowania adresu. W każdym przypadku ten parametr może wpływać na wyniki na podstawie obowiązujących przepisów.

  • szczegółowość,

    Co najmniej jeden poziom szczegółowości lokalizacji określony jako oddzielne parametry zapytania zgodnie z definicją w Granularity. Jeśli podasz kilka parametrów granularity, interfejs API zwróci wszystkie adresy, które pasują do dowolnego poziomu szczegółowości.

    Parametr granularity nie ogranicza wyszukiwania do określonych poziomów szczegółowości lokalizacji. Zamiast tego granularity działa jako filtr po wyszukiwaniu. Interfejs API pobiera wszystkie wyniki dla określonego parametru location, a następnie odrzuca te wyniki, które nie pasują do określonych poziomów szczegółowości lokalizacji.

    Jeśli określisz zarówno types, jak i granularity, interfejs API zwróci tylko te wyniki, które pasują do obu tych warunków. Na przykład:

    https://geocode.googleapis.com/v4beta/geocode/location/37.4225508,-122.0846338?granularity=ROOFTOP&granularity=GEOMETRIC_CENTER&key=API_KEY

  • typy

    Co najmniej 1 typ adresu określony jako osobny parametr zapytania. Jeśli podasz kilka parametrów types, interfejs API zwróci wszystkie adresy, które pasują do dowolnego z tych typów.

    Parametr types nie ogranicza wyszukiwania do określonych typów adresów. Zamiast tego types działa jako filtr po wyszukiwaniu. Interfejs API pobiera wszystkie wyniki dla określonej lokalizacji, a następnie odrzuca te, które nie pasują do określonych typów adresów.

    Jeśli określisz zarówno types, jak i granularity, interfejs API zwróci tylko te wyniki, które pasują do obu tych warunków. Na przykład:

    https://geocode.googleapis.com/v4beta/geocode/location/37.4225508,-122.0846338?types=administrative_area_level_2&types=locality&key=API_KEY

    Obsługiwane są te wartości:

    Typy adresów i rodzaje 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 najwyższy typ 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_1 kró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 mniejszy podział administracyjny. Nie wszystkie kraje mają te poziomy administracyjne.
    administrative_area_level_4 Jednostka administracyjna czwartego rzędu poniżej poziomu kraju. Ten typ wskazuje mniejszy podział administracyjny. Nie wszystkie kraje mają te poziomy administracyjne.
    administrative_area_level_5 Jednostka administracyjna 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 Jednostka administracyjna 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 Jednostka administracyjna siódmego rzędu poniżej poziomu kraju. Ten typ wskazuje mniejszy podział administracyjny. 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 poziomu 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, a 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 ważne 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).