Geokodowanie miejsca

Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

Geokodowanie miejsc umożliwia pobieranie adresu na podstawie identyfikatora miejsca.

Identyfikatory miejsc jednoznacznie identyfikują miejsce w bazie danych Miejsc Google i w Mapach Google. Pobieraj identyfikatory miejsc podczas geokodowania adresu. Identyfikator miejsca możesz też pobrać z wielu innych interfejsów API, takich jak informacje o miejscu (nowa wersja), Wyszukaj tekst (nowa wersja), i Wyszukiwanie w pobliżu (nowa wersja).

Żądania geokodowania miejsc

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

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

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

Wszystkie pozostałe 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:

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

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

Geocoding API w wersji 4 obsługuje uwierzytelnianie za pomocą OAuth 2.0. Aby używać OAuth z Geocoding API, token OAuth musi mieć przypisany odpowiedni zakres. Geocoding API obsługuje te zakresy do użycia z geokodowaniem 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 metodą GeocodePlace do geokodowania miejsc.

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.

Odpowiedzi geokodowania miejsc

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

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

  1. GeocodeResult.types: ta tablica wskazuje ogólny typ lub 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 sekcji 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 adresów używanej przez Places API.

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 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ć placeID zwróconego przez Roads API aby uzyskać adres dla 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, dlatego może ona nie być wyczerpująca.
    • Jeśli nie podasz parametru languageCode, interfejs API domyślnie użyje lokalnego języka i skryptu lokalizacji. 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 jest 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 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 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 (geokodowanie wyprzedzające) 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, 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.

  • FieldMask

    Utwórz maskę pola odpowiedzi, aby określić pola, które mają być zwracane 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 poniższe żądanie 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ź: 
    {
  "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA"
}

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