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 reprezentujesz za pomocą współrzędnych 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ółowego adresu ulicy 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 types parametru.

Żądanie odwrotnego geokodowania

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

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

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

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

Ustrukturyzowany format jest zwykle używany podczas przetwarzania komponentów lokalizacji przechwyconych w formularzu HTML.

Wszystkie inne parametry przekaż jako parametry adresu URL lub, w przypadku parametrów takich jak klucz API czy maska pola, w nagłówkach w ramach żądania GET. Na przykład:

Przekazywanie nieustrukturyzowanego ciągu znaków lokalizacji

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

https://geocode.googleapis.com/v4/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/v4/geocode/location/37.4225508,-122.0846338"

Przekazywanie ustrukturyzowanej lokalizacji

Ustrukturyzowaną lokalizację określ 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/v4/geocode/location?location.latitude=37.4225508&location.longitude=-122.0846338&key=API_KEY

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

Geocoding API w wersji 4 obsługuje OAuth 2.0 do uwierzytelniania. Aby używać OAuth z Geocoding API, token OAuth musi mieć przypisany prawidłowy 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żyć ogólnego zakresu https://www.googleapis.com/auth/cloud-platform w przypadku wszystkich metod 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 Używanie OAuth.

Odpowiedź odwrotnego geokodowania

Odwrotne geokodowanie zwraca GeocodeLocationResponse obiekt, który zawiera:

  • tablicę results obiektów GeocodeResult reprezentujących miejsce.

    Odpowiedzi Geocoding API zawierają types tablice w 2 głównych miejscach w obrębie 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 tabelach A i B w artykule Typy 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 typów adresów i typów komponentów adresu używanej przez Places API.

    Odwrotny geokoder zwraca więcej niż 1 wynik w tablicy results. Wyniki to nie tylko adresy pocztowe, ale też dowolny sposób geograficznego nazwania lokalizacji. Na przykład podczas geokodowania punktu w Chicago, geokodowany punkt może być oznaczony jako adres ulicy, miasto (Chicago), stan (Illinois) lub kraj (Stany Zjednoczone). Dla geokodera wszystkie te elementy są „adresami”. Odwrotny geokoder zwraca dowolny z tych typów jako prawidłowy wynik.

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

    Uwaga: interfejs API nie zawsze zwraca kody plus.

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, 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 listę obsługiwanych języków, więc może ona nie być wyczerpująca.
    • Jeśli nie podasz parametru languageCode, interfejs API domyślnie użyje języka angielskiego (en). Jeśli podasz nieprawidłowy kod języka, interfejs API zwróci błąd INVALID_ARGUMENT.
    • Interfejs API dokłada wszelkich starań, aby podać adres ulicy, który będzie czytelny zarówno dla użytkownika, jak i dla mieszkańców. W tym celu zwraca adresy ulic w języku lokalnym, w razie potrzeby transliterowane na skrypt czytelny dla użytkownika, z uwzględnieniem preferowanego języka. Wszystkie inne adresy są zwracane w preferowanym języku. 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ść ich zwracania. Geokoder inaczej interpretuje skróty 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 2-znakowa wartość 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 wyprzedzającego, ten parametr może wpływać na wyniki usługi, ale nie ogranicza ich w pełni do określonego regionu. Podczas geokodowania lokalizacji lub miejsca, czyli odwrotnego geokodowania lub geokodowania miejsca, ten parametr może służyć do formatowania adresu. We wszystkich przypadkach ten parametr może wpływać na wyniki na podstawie obowiązujących przepisów.

  • szczegóły

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

    Parametr granularity nie ogranicza wyszukiwania do określonych stopni szczegółowości lokalizacji. Raczej, granularity działa jako filtr po wyszukiwaniu. Interfejs API pobiera wszystkie wyniki dla określonego location, a następnie odrzuca te wyniki które nie pasują do określonych stopni 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 parametrów. 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 oddzielne parametry zapytania. Możliwe wartości pochodzą z tabeli typów adresów i typów komponentów adresu na stronie Typy miejsc (nowe). Jeśli określisz 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. Raczej, types działa jako filtr po wyszukiwaniu. Interfejs API pobiera wszystkie wyniki dla określonej lokalizacji, a następnie odrzuca te wyniki 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 używając nagłówka HTTP X-Goog-FieldMask. Na przykład poniższe żądanie 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ź: 
    {
  "results": [
    {
      "placeId": "ChIJHRNUiQK6j4ARJ__Hrbt6qsE"
    },
    {
      "placeId": "ChIJj38IfwK6j4ARNcyPDnEGa9g"
    },
    {
      "placeId": "ChIJ1yjFJ1-7j4ARG_RVqFD1h7k"
    },
    {
      "placeId": "ChIJ09H2YwK6j4ARoF7qfCBxhB8"
    },
    ...
  ]
}

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