Identyfikatory miejsc

Wybierz platformę: Android iOS JavaScript Usługa internetowa
Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

Wprowadzenie

Identyfikatory miejsc jednoznacznie identyfikują miejsce w bazie danych Miejsc Google i w Mapach Google. Identyfikatory miejsc są akceptowane w żądaniach do tych interfejsów Map Google:

  • Pobieranie adresu na podstawie identyfikatora miejsca za pomocą interfejsu Geocoding API i Usługa geokodowania, Maps JavaScript API.
  • Określanie punktu początkowego, docelowego i punktów pośrednich w interfejsach Routes API i Directions API (starsze wersje) oraz Usługa wyznaczania trasy, Maps JavaScript API (starsza wersja).
  • Określanie miejsc początkowych i docelowych w interfejsie Routes API oraz w interfejsie Distance Matrix API (starsza wersja) i w usłudze Distance Matrix Service, Maps JavaScript API (starsza wersja).
  • Pobieranie szczegółów miejsca w interfejsie Places API (nowy), pakiecie Places SDK na Androida (nowy), pakiecie Places SDK na iOS (nowy) i bibliotece Places.
  • Używanie parametrów identyfikatora miejsca w interfejsie Maps Embed API.
  • Pobieranie zapytań w adresach URL Map.
  • Wyświetlanie ograniczeń prędkości w interfejsie Roads API.
  • Znajdowanie i stylizowanie wielokątów granicznych w stylu opartym na danych dla granic.

Znajdowanie identyfikatora konkretnego miejsca

Czy szukasz identyfikatora konkretnego miejsca? Aby wyszukać miejsce i uzyskać jego identyfikator, użyj poniższego narzędzia do wyszukiwania identyfikatorów miejsc:

Możesz też wyświetlić wyszukiwarkę identyfikatorów miejsc, korzystając z jej kodu w dokumentacji interfejsu Maps JavaScript API.

Omówienie

Identyfikator miejsca to tekstowy identyfikator jednoznacznie identyfikujący miejsce. Długość identyfikatora może się różnić (nie ma maksymalnej długości identyfikatorów miejsc). Przykłady:

  • ChIJgUbEo8cfqokR5lP9_Wh_DaM
  • GhIJQWDl0CIeQUARxks3icF8U8A
  • EicxMyBNYXJrZXQgU3QsIFdpbG1pbmd0b24sIE5DIDI4NDAxLCBVU0EiGhIYChQKEgnRTo6ixx-qiRHo_bbmkCm7ZRAN
  • EicxMyBNYXJrZXQgU3QsIFdpbG1pbmd0b24sIE5DIDI4NDAxLCBVU0E
  • IhoSGAoUChIJ0U6OoscfqokR6P225pApu2UQDQ

Identyfikatory miejsc są dostępne w przypadku większości lokalizacji, w tym firm, punktów orientacyjnych, parków i skrzyżowań. To samo miejsce może mieć wiele różnych identyfikatorów miejsc. Identyfikatory miejsc mogą się z czasem zmieniać.

Możesz używać tego samego identyfikatora miejsca w interfejsie Places API i w kilku interfejsach API Google Maps Platform. Możesz na przykład użyć tego samego identyfikatora miejsca do odwołania się do miejsca w Places API, Maps JavaScript API, Geocoding API, Maps Embed API i Roads API.

Pobieranie szczegółów miejsca za pomocą identyfikatora miejsca

Najczęstszym sposobem używania identyfikatorów miejsc jest wyszukiwanie miejsca (np. za pomocą Places API lub biblioteki Places w interfejsie Maps JavaScript API), a następnie używanie zwróconego identyfikatora miejsca do pobierania szczegółów miejsca. Możesz zapisać identyfikator miejsca i użyć go, aby później pobrać te same szczegóły. Poniżej znajdziesz informacje o zapisywaniu identyfikatorów miejsc.

W tych przykładach pokazano, jak poprosić o adres URL ikony w przypadku interfejsu Places API (New) i interfejsu Places API (Legacy).

Places API (nowość)

Za pomocą interfejsu Places API możesz znaleźć identyfikator miejsca, wysyłając żądanie Text Search (New) (wyszukiwanie tekstu – nowość).

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.id,places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'

Odpowiedź zawiera identyfikator miejsca w polu id, jak pokazano poniżej:

{
  "places": [
    {
      "id": "ChIJs5ydyTiuEmsR0fRSlU0C7k0",
      "formattedAddress": "29 King St, Sydney NSW 2000, Australia",
      "displayName": {
        "text": "Peace Harmony",
        "languageCode": "en"
      }
    },
  ...
}

Teraz możesz wysłać żądanie Szczegóły miejsca (nowe), podając identyfikator miejsca w adresie URL żądania:

https://places.googleapis.com/v1/places/ChIJs5ydyTiuEmsR0fRSlU0C7k0?fields=id,displayName&key=API_KEY

Places API (starsza wersja)

Za pomocą interfejsu Places API możesz znaleźć identyfikator miejsca, wysyłając żądanie wyszukiwania miejsca.

Poniżej przykład zapytania o miejsca typu „restauracja” w promieniu 1500 m od punktu w Sydney w Australii, zawierającego słowo „rejs”:

https://maps.googleapis.com/maps/api/place/nearbysearch/json?location=-33.8670522,151.1957362&radius=1500&type=restaurant&keyword=cruise&key=YOUR_API_KEY

Odpowiedź zawiera identyfikator miejsca w polu place_id, jak pokazano w tym fragmencie kodu:

{
  "html_attributions" : [],
  "results" : [
    {
      "geometry" : {
        "location" : {
          "lat" : -33.870775,
          "lng" : 151.199025
        }
      },
      ...
      "place_id" : "ChIJrTLr-GyuEmsRBfy61i59si0",
      ...
    }
  ],
  "status" : "OK"
}

Teraz możesz wysłać żądanie Szczegóły miejsca (starsza wersja), podając identyfikator miejsca w parametrze place_id:

https://maps.googleapis.com/maps/api/place/details/json?place_id=ChIJrTLr-GyuEmsRBfy61i59si0&key=YOUR_API_KEY

Zapisywanie identyfikatorów miejsc na potrzeby późniejszego użycia

Identyfikatory miejsc nie podlegają ograniczeniom dotyczącym przechowywania w pamięci podręcznej określonym w sekcji 3.2.3(b) Warunków korzystania z usługi Google Maps Platform. Dzięki temu możesz przechowywać wartości identyfikatorów miejsc na później.

Odświeżanie zapisanych identyfikatorów miejsc

Identyfikatory miejsc mogą się zmieniać z powodu aktualizacji bazy danych Map Google. Dlatego zalecamy odświeżanie identyfikatorów miejsc, jeśli mają one więcej niż 12 miesięcy. Możesz odświeżyć identyfikatory miejsc bezpłatnie, wysyłając żądanie dotyczące szczegółów miejsca, podając w parametrze fields tylko pole identyfikatora miejsca.

Places API (nowość)

Na przykład w sekcji Szczegóły miejsca (nowa):

https://places.googleapis.com/v1/places/ChIJ05IRjKHxEQ0RJLV_5NLdK2w?fields=id&key=API_KEY

Places API (starsza wersja)

Na przykład w przypadku korzystania z Places API (starsza wersja):

https://maps.googleapis.com/maps/api/place/details/json?place_id=ChIJ05IRjKHxEQ0RJLV_5NLdK2w&fields=place_id&key=API_KEY

To wywołanie powoduje wykonanie operacji Place Detail New Essentials IDs Only lub Places Details - ID Refresh.

Kody błędów podczas używania identyfikatorów miejsc

INVALID_REQUEST

Kod stanu INVALID_REQUEST wskazuje, że podany identyfikator miejsca jest nieprawidłowy. INVALID_REQUEST może zostać zwrócony, gdy identyfikator miejsca został obcięty lub w inny sposób zmodyfikowany i nie jest już prawidłowy.

NOT_FOUND

Kod stanu NOT_FOUND wskazuje, że podany identyfikator miejsca jest nieaktualny. Identyfikator miejsca może stać się nieaktualny, jeśli firma zostanie zamknięta lub przeniesiona do nowej lokalizacji. Identyfikatory miejsc mogą się też zmieniać z powodu aktualizacji bazy danych Map Google. W takich przypadkach miejsce może otrzymać nowy identyfikator miejsca, a stary identyfikator zwróci odpowiedź NOT_FOUND.

Aby odświeżyć wyniki w przypadku nieaktualnego identyfikatora miejsca, zapisz pierwotne żądanie, które zwróciło identyfikator każdego miejsca, i w razie potrzeby ponownie je prześlij. Pamiętaj, że prośba o wydanie karty ponownie jest rozliczana zgodnie z odpowiednim SKU.

Niektóre typy identyfikatorów miejsc mogą czasami powodować odpowiedź NOT_FOUND lub interfejs API może zwrócić inny identyfikator miejsca w odpowiedzi. Te typy identyfikatorów miejsc:

  • adresy ulic, które nie występują w Mapach Google jako dokładne adresy, ale są wywnioskowane na podstawie zakresu adresów;
  • Segmenty długiej trasy, w których żądanie określa również miasto lub miejscowość.
  • skrzyżowania,
  • Miejsca z elementem adresu typu subpremise.

Te identyfikatory często mają postać długiego ciągu znaków (nie ma maksymalnej długości identyfikatorów miejsc). Na przykład:

EpID4LC14LC_4LCo4LCv4LGN4LCo4LCX4LCw4LGNIC0g4LC44LGI4LCm4LGN4LCs4LC-4LCm4LGNIOCwsOCxi-CwoeCxjeCwoeCxgSAmIOCwteCwv-CwqOCwr-CxjSDgsKjgsJfgsLDgsY0g4LCu4LGG4LCv4LC_4LCo4LGNIOCwsOCxi-CwoeCxjeCwoeCxgSwg4LC14LC_4LCo4LCv4LGNIOCwqOCwl-CwsOCxjSDgsJXgsL7gsLLgsKjgsYAsIOCwsuCwleCxjeCwt-CxjeCwruCwv-CwqOCwl-CwsOCxjSDgsJXgsL7gsLLgsKjgsYAsIOCwuOCwsOCxguCwsOCxjSDgsKjgsJfgsLDgsY0g4LC14LGG4LC44LGN4LCf4LGNLCDgsLjgsK_gsYDgsKbgsL7gsKzgsL7gsKbgsY0sIOCwueCxiOCwpuCwsOCwvuCwrOCwvuCwpuCxjSwg4LCk4LGG4LCy4LCC4LCX4LC-4LCjIDUwMDA1OSwg4LCt4LC-4LCw4LCk4LCm4LGH4LC24LCCImYiZAoUChIJ31l5uGWYyzsR9zY2qk9lDiASFAoSCd9ZebhlmMs7Efc2NqpPZQ4gGhQKEglDz61OZpjLOxHgDJCFY-o1qBoUChIJi37TW2-YyzsRr_uv50r7tdEiCg1MwFcKFS_dyy4