Geokodowanie miejsca

Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

Geokodowanie miejsca umożliwia pobranie adresu na podstawie identyfikatora miejsca.

Identyfikatory miejsc jednoznacznie identyfikują miejsce w bazie danych Miejsc Google i w Mapach Google. Pobieraj identyfikatory miejsc, gdy geokodujesz adres. Identyfikator miejsca możesz też pobrać z wielu innych interfejsów API, takich jak Szczegóły miejsca (nowy), Wyszukiwanie tekstowe (nowy) i Wyszukiwanie w pobliżu (nowy).

Żądania geokodowania miejsca

Żądanie geokodowania miejsca to żądanie HTTP GET w formacie:

https://geocode.googleapis.com/v4beta/geocode/places/PLACE_ID

Gdzie PLACE_ID zawiera identyfikator miejsca lokalizacji, która Cię interesuje.

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

https://geocode.googleapis.com/v4beta/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw?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/v4beta/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw"

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, token OAuth musi mieć przypisany odpowiedni zakres. Geocoding API obsługuje te zakresy do geokodowania miejsc:

  • 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.place – Używaj tylko z parametrem GeocodePlace do geokodowania miejsc.

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 OAuth.

Odpowiedzi dotyczące geokodowania miejsc

Geokodowanie miejsca zwraca obiektGeocodeResult, który reprezentuje miejsce odpowiadające identyfikatorowi miejsca.

Pełny obiekt JSON ma postać:

{
  "place": "//places.googleapis.com/places/ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "placeId": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "location": {
    "latitude": 37.4220541,
    "longitude": -122.08532419999999
  },
  "granularity": "ROOFTOP",
  "viewport": {
    "low": {
      "latitude": 37.4209489697085,
      "longitude": -122.08846930000001
    },
    "high": {
      "latitude": 37.4236469302915,
      "longitude": -122.0829156
    }
  },
  "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
  "postalAddress": {
    "regionCode": "US",
    "languageCode": "en",
    "postalCode": "94043",
    "administrativeArea": "CA",
    "locality": "Mountain View",
    "addressLines": [
      "1600 Amphitheatre Pkwy"
    ]
  },
  "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"
  ]
}

Wymagane parametry

  • place – identyfikator miejsca, dla którego chcesz uzyskać adres w formacie czytelnym dla człowieka. Identyfikator miejsca to unikalny identyfikator, którego można używać z innymi interfejsami API Google. Możesz na przykład użyć placeID zwróconego przez Roads API, aby uzyskać adres przyciągniętego punktu. Więcej informacji o identyfikatorach miejsc znajdziesz w sekcji Identyfikatory miejsc.

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 w określonym regionie, ale nie może ich całkowicie ograniczać. Podczas geokodowania lokalizacji lub miejsca, odwrotnego geokodowania 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.