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. pobierać identyfikatory miejsc podczas geokodowania adresu; Identyfikator miejsca możesz też pobrać z wielu innych interfejsów API, takich jak informacje o miejscu (nowe), Wyszukaj tekst (nowe) i Wyszukiwanie w pobliżu (nowe).

Żądania geokodowania miejsc

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

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

Gdzie PLACE_ID zawiera identyfikator miejsca lokalizacji interesującej użytkownika.

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:

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

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 geokodowania miejsc:

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

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.

Odpowiedzi geokodowania miejsc

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

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.

Kompletny 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 zrozumiały 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ć wartości placeID zwróconej przez Roads API, aby uzyskać adres przyciągniętego punktu. Więcej informacji o identyfikatorach miejsc znajdziesz w artykule 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 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, ten parametr może służyć do formatowania adresu. We wszystkich przypadkach ten parametr może wpływać na wyniki zgodnie z obowiązującymi przepisami.

  • 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 pole formattedAddress odpowiedzi.

    curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: formattedAddress' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    Odpowiedź jest taka: 
    {
  "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA"
}

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