Odwróć geokodowanie lokalizacji

Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

Odwrotne geokodowanie przekształca lokalizację na mapie w adres zrozumiały dla człowieka. Lokalizację na mapie reprezentują współrzędne 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ć konkretny typ adresu, użyj parametru types.

Żądanie odwrotnego geokodowania

Żądanie odwrotnego geokodowania jest żądaniem HTTP GET. Lokalizację możesz podać jako nieuporządkowany ciąg znaków:

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

lub jako uporządkowany zbiór współrzędnych szerokości i długości geograficznej reprezentowanych przez parametry zapytania:

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

Format uporządkowany jest zwykle używany podczas przetwarzania komponentów lokalizacji przechwyconych w formularzu HTML.

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

Przekazywanie nieuporządkowanego ciągu znaków lokalizacji

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

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

Możesz też użyć polecenia curl:

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

Przekazywanie lokalizacji strukturalnej

Określ uporządkowaną lokalizację, używając 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/v4/geocode/location?location.latitude=37.4225508&location.longitude=-122.0846338&key=API_KEY

Używanie protokołu OAuth do wysyłania żądań

Geocoding API w wersji 4 obsługuje uwierzytelnianie OAuth 2.0. Aby używać protokołu OAuth z interfejsem Geocoding API, tokenowi OAuth należy przypisać odpowiedni zakres. Geocoding API obsługuje te zakresy do użycia z odwrotnym geokodowaniem:

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

Możesz też używać ogólnego zakresu https://www.googleapis.com/auth/cloud-platform we wszystkich metodach 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 metod.

Więcej informacji i przykłady znajdziesz w artykule o korzystaniu z protokołu OAuth.

Odpowiedź odwrotnego geokodowania

Odwrotne geokodowanie zwraca obiekt GeocodeLocationResponse, który zawiera:

  • Tablica results obiektów GeocodeResult reprezentujących miejsce.

    Odpowiedzi interfejsu Geocoding API zawierają tablice types w 2 głównych miejscach w GeocodeResult:

    1. GeocodeResult.types: ta tablica wskazuje ogólne typy wyniku. Możliwe wartości pochodzą z typów miejsc używanych przez Places API. Więcej informacji znajdziesz w sekcji Tabele A i B z typami miejsc.
    2. GeocodeResult.addressComponents[].types: każdy komponent adresu ma tablicę types wskazującą typ tej konkretnej części adresu. Te wartości pochodzą z tabeli Typy adresów i komponentów adresowych używanej przez interfejs Places API.

    Odwrotny geokoder zwraca więcej niż 1 wynik w tablicy results. Wyniki to nie tylko adresy pocztowe, ale też dowolne sposoby geograficznego określenia lokalizacji. Na przykład podczas geokodowania punktu w Chicago punkt ten może być oznaczony jako adres, miasto (Chicago), stan (Illinois) lub kraj (Stany Zjednoczone). Wszystkie te elementy są dla geokodera „adresami”. Odwrotny geokoder zwraca dowolny z tych typów jako prawidłowe wyniki.

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

    Uwaga: interfejs API nie zawsze zwraca kody Plus Code.

Kompletny 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, gdzie chcesz znaleźć najbliższy adres zrozumiały 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 obsługiwane języki, więc ta lista może nie być wyczerpująca.
    • Jeśli nie podasz parametru languageCode, interfejs API domyślnie użyje języka i pisma lokalnego. Jeśli podasz nieprawidłowy kod języka, interfejs API zwróci błąd INVALID_ARGUMENT.
    • Interfejs API 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 inne 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żywa najbliższego dopasowania.
    • Preferowany język ma niewielki wpływ na zestaw wyników, które interfejs API zwraca, oraz na kolejność, w jakiej są 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 dwuznakowy kod CLDR. Nie ma wartości domyślnej. Większość kodów CLDR jest identyczna z kodami ISO 3166-1.

    Podczas geokodowania adresu (geokodowanie bezpośrednie) ten parametr może wpływać na wyniki usługi w określonym regionie, ale nie ogranicza ich całkowicie. Podczas geokodowania lokalizacji lub miejsca, odwrotnego geokodowania lub geokodowania miejsca, tego parametru można użyć do sformatowania adresu. We wszystkich przypadkach ten parametr może wpływać na wyniki zgodnie z obowiązującymi przepisami.

  • szczegółowość

    Co najmniej 1 poziom szczegółowości lokalizacji określony jako osobne 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, 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 wartości. Na przykład:

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

  • typy

    Co najmniej 1 typ adresu określony jako osobne parametry zapytania. Możliwe wartości pochodzą z tabeli Typy adresów i typy komponentów adresowych na stronie Typy miejsc (nowe). 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 parametrów. Na przykład:

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

  • FieldMask

    Utwórz maskę pola odpowiedzi, aby określić pola, które mają zostać zwrócone w odpowiedzi. Przekaż maskę pola odpowiedzi do metody, używając parametru adresu URL $fields lub fields albo nagłówka HTTP X-Goog-FieldMask. Na przykład żądanie poniżej zwróci tylko pola placeID odpowiedzi.

    curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: results.placeId' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338"
    Odpowiedź jest taka: 
    {
  "results": [
    {
      "placeId": "ChIJHRNUiQK6j4ARJ__Hrbt6qsE"
    },
    {
      "placeId": "ChIJj38IfwK6j4ARNcyPDnEGa9g"
    },
    {
      "placeId": "ChIJ1yjFJ1-7j4ARG_RVqFD1h7k"
    },
    {
      "placeId": "ChIJ09H2YwK6j4ARoF7qfCBxhB8"
    },
    ...
  ]
}

    Więcej informacji znajdziesz w sekcji Wybieranie pól do zwrócenia.