Identyfikatory miejsc

Wybierz platformę: Android iOS JavaScript Usługa internetowa

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:

  • Pobieranie adresu na podstawie identyfikatora miejsca w usłudze internetowej interfejsu Geocoding API i w interfejsie Geocoding Service, Maps JavaScript API.
  • Określanie punktu początkowego, docelowego i punktów pośrednich w usłudze internetowej interfejsu Routes API i interfejsu Directions API (starsza wersja) oraz w usłudze wyznaczania trasy, Maps JavaScript API (starsza wersja).
  • Określanie miejsc wylotu i celów w interfejsie Routes API oraz w usłudze internetowej Distance Matrix API (w wersji starszej) i w usłudze Distance Matrix Service, Maps JavaScript API (w wersji starszej).
  • Pobieranie szczegółów miejsca w usłudze internetowej interfejsu API Miejsca, pakiecie SDK Miejsca na Androida, pakiecie SDK Miejsca na iOS i bibliotece Miejsca.
  • 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 w przypadku 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

Typowym sposobem używania identyfikatorów miejsc jest wyszukiwanie miejsca (np. za pomocą interfejsu 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 później, aby pobrać szczegóły tego miejsca. 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 (Nowy) i interfejsu Places API.

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 Places API (New), podając identyfikator miejsca w adresie URL żądania:

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

Places API

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ółów miejsca, 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. Możesz więc zapisać wartości identyfikatorów miejsc na później.

Odświeżanie zapisanych identyfikatorów miejsc

Google zaleca odświeżenie identyfikatorów miejsc, jeśli mają więcej niż 12 miesięcy. Możesz odświeżyć identyfikatory miejsc bezpłatnie, wysyłając prośbę o szczegóły miejsca, podając w parametrze fields tylko pole identyfikatora miejsca.

Places API (nowość)

Na przykład przy użyciu Places API (nowość):

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

Places API

Na przykład, korzystając ze starszego interfejsu Places API:

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.

To żądanie może też zwrócić kod stanu NOT_FOUND. Jedną z możliwości jest zapisanie pierwotnego żądania, które zwróciło identyfikator każdego miejsca. Jeśli identyfikator miejsca stanie się nieprawidłowy, możesz ponownie wysłać to żądanie, aby uzyskać aktualne wyniki. Wyniki mogą zawierać pierwotne miejsce lub nie. Za to żądanie zostanie jednak naliczona opłata.

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

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.

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

W szczególności niektóre typy identyfikatorów miejsc mogą czasami powodować odpowiedź NOT_FOUND lub interfejs API może zwrócić w odpowiedzi inny identyfikator miejsca. 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;
  • Odcinki długiej trasy, w których żądaniu podany jest też 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