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 Place Details (New), Text Search (New) i Nearby Search (New).

Żą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 nagłówkach jako część żądania GET (w przypadku parametrów takich jak klucz interfejsu API czy maska pola). 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, tokenowi OAuth musi być 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 obiekt GeocodeResult, 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 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ż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 ogranicza ich całkowicie 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.