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 przypadku żądań wysyłanych do tych interfejsów API Map Google:

  • Pobieranie adresu dla identyfikatora miejsca w interfejsie Geocoding API i usłudze Geocoding Service w interfejsie Maps JavaScript API.
  • Określanie punktu początkowego, docelowego i pośrednich punktów na trasie w interfejsach Routes API i Directions API (starsza wersja) oraz w usłudze Directions Service, Maps JavaScript API (starsza wersja).
  • Określanie punktów początkowych i docelowych w interfejsach Routes API i Distance Matrix API (starsza wersja) oraz w usłudze Distance Matrix Service, Maps JavaScript API (starsza wersja).
  • Pobieranie informacji o miejscu w interfejsie Places API (nowość), pakiecie SDK Miejsc na Androida (nowość), pakiecie SDK Miejsc na iOS (nowość) i bibliotece Miejsc.
  • Używanie parametrów identyfikatora miejsca w interfejsie Maps Embed API.
  • Pobieranie zapytań z adresów URL w Mapach.
  • wyświetlanie ograniczeń prędkości w interfejsie Roads API;
  • Wyszukiwanie i stylizowanie wielokątów granic w stylu opartym na danych dla granic.

Znajdowanie identyfikatora konkretnego miejsca

Szukasz identyfikatora miejsca konkretnego miejsca? Aby wyszukać miejsce i uzyskać jego identyfikator, skorzystaj z wyszukiwarki identyfikatorów miejsc poniżej:

Możesz też wyświetlić wyszukiwarkę identyfikatorów miejsc wraz z kodem w dokumentacji interfejsu Maps JavaScript API.

Przegląd

Identyfikator miejsca to identyfikator tekstowy, który jednoznacznie identyfikuje miejsce. Długość identyfikatora może być różna (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 lub lokalizacja może mieć kilka różnych identyfikatorów miejsca. Identyfikatory miejsc mogą się z czasem zmieniać.

Ten sam identyfikator miejsca możesz używać w interfejsie Places API i wielu interfejsach API Google Maps Platform. Możesz na przykład użyć tego samego identyfikatora miejsca, aby odwołać się do miejsca w Places API, Maps JavaScript API, Geocoding API, Maps Embed API i Roads API.

Pobieranie informacji o miejscu za pomocą identyfikatora miejsca

Typowym sposobem użycia identyfikatorów miejsc jest wyszukiwanie miejsca za pomocą interfejsu Places API lub biblioteki Miejsc w interfejsie Maps JavaScript API. Następnie użyj zwróconego identyfikatora miejsca, aby pobrać informacje o miejscu. Możesz zapisać identyfikator miejsca i użyć go później, aby pobrać te same informacje o miejscu. Więcej informacji o zapisywaniu identyfikatorów miejsc znajdziesz w dalszej części tego dokumentu.

Przykład użycia pakietu SDK Miejsc na Androida (nowego)

W pakiecie SDK Miejsc na Androida (nowym) możesz pobrać identyfikator miejsca, wywołując metodę Place.getId(). Usługa Autouzupełnianie miejsc (starsza wersja) zwraca też identyfikator miejsca dla każdego miejsca, które pasuje do podanego zapytania i filtra. Użyj identyfikatora miejsca, aby później ponownie pobrać obiekt Place.

Aby uzyskać miejsce według identyfikatora, wywołaj PlacesClient.fetchPlace(), przekazując FetchPlaceRequest.

Interfejs API zwraca wartość FetchPlaceResponse w Task. FetchPlaceResponse zawiera obiekt Place pasujący do podanego identyfikatora miejsca.

Poniższy przykład kodu pokazuje wywoływanie funkcji fetchPlace() w celu uzyskania szczegółowych informacji o określonym miejscu.

Kotlin

// Define a Place ID.
val placeId = PlaceIdProvider.getRandomPlaceId()

// Specify the fields to return.
val placeFields = listOf(
    Place.Field.ID,
    Place.Field.DISPLAY_NAME,
    Place.Field.FORMATTED_ADDRESS,
    Place.Field.LOCATION
)

// Construct a request object, passing the place ID and fields array.
val request = FetchPlaceRequest.newInstance(placeId, placeFields)

placesClient.fetchPlace(request)
    .addOnSuccessListener { response: FetchPlaceResponse ->
        val place = response.place

        val name = place.displayName
        val address = place.formattedAddress
        val location = place.location

        binding.placeName.text = name
        binding.placeAddress.text = address
        if (location != null) {
            binding.placeLocation.text = getString(
                R.string.place_location, location.latitude, location.longitude
            )
        } else {
            binding.placeLocation.text = null
        }
        Log.i(TAG, "Place found: ${place.displayName}")
    }.addOnFailureListener { exception: Exception ->
        if (exception is ApiException) {
            val message = getString(R.string.place_not_found, exception.message)
            binding.placeName.text = message
            Log.e(TAG, "Place not found: ${exception.message}")
            val statusCode = exception.statusCode
            TODO("Handle error with given status code")
        }
    }

Java

// Define a Place ID.
final String placeId = PlaceIdProvider.getRandomPlaceId();

// Specify the fields to return.
final List<Place.Field> placeFields =
        Arrays.asList(
                Place.Field.ID,
                Place.Field.DISPLAY_NAME,
                Place.Field.FORMATTED_ADDRESS,
                Place.Field.LOCATION
        );

// Construct a request object, passing the place ID and fields array.
final FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields);

placesClient.fetchPlace(request).addOnSuccessListener((response) -> {
    Place place = response.getPlace();

    final CharSequence name = place.getDisplayName();
    final CharSequence address = place.getFormattedAddress();
    final LatLng location = place.getLocation();

    binding.placeName.setText(name);
    binding.placeAddress.setText(address);
    if (location != null) {
        binding.placeLocation.setText(
                getString(R.string.place_location, location.latitude, location.longitude)
        );
    } else {
        binding.placeLocation.setText(null);
    }

    Log.i(TAG, "Place found: " + place.getDisplayName());
}).addOnFailureListener((exception) -> {
    if (exception instanceof ApiException apiException) {
        final String message = getString(R.string.place_not_found, apiException.getMessage());
        binding.placeName.setText(message);
        Log.e(TAG, "Place not found: " + exception.getMessage());
        final int statusCode = apiException.getStatusCode();
        // TODO: Handle error with given status code.
    }
});

Zapisywanie identyfikatorów miejsc do późniejszego wykorzystania

Identyfikatory miejsc są wyłączone z ograniczeń dotyczących buforowania określonych w artykule 3.2.3(b) Warunków korzystania z usługi Google Maps Platform. Dzięki temu możesz zapisywać wartości identyfikatorów miejsc do późniejszego wykorzystania.

Odświeżanie zapisanych identyfikatorów miejsc

Identyfikatory miejsc mogą się zmieniać z powodu aktualizacji w bazie danych Map Google, dlatego Google zaleca odświeżanie identyfikatorów miejsc, które mają więcej niż 12 miesięcy. Możesz odświeżyć identyfikatory miejsc bezpłatnie, wysyłając żądanie informacji o miejscu i określając tylko pole Place.Field.ID w parametrze fields.

To wywołanie powoduje użycie kodu SKU informacje o miejscu – odświeżanie identyfikatora.

Kody błędów podczas korzystania z identyfikatorów miejsc

INVALID_REQUEST

Kod stanu INVALID_REQUEST wskazuje, że podany identyfikator miejsca jest nieprawidłowy. INVALID_REQUEST może być zwracany, gdy identyfikator miejsca został skrócony 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 miejsca zwróci odpowiedź NOT_FOUND.

Aby odświeżyć wyniki w przypadku nieaktualnego identyfikatora miejsca, zapisz pierwotne żądanie, które zwróciło każdy identyfikator miejsca, i w razie potrzeby ponownie wyślij żądanie. Pamiętaj, że ponownie przesłana prośba jest rozliczana według odpowiedniego numeru SKU.

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

  • Adresy, które nie istnieją w Mapach Google jako dokładne adresy, ale są wnioskowane na podstawie zakresu adresów.
  • segmenty długiej trasy, w przypadku których w żądaniu podano też miasto lub miejscowość;
  • Skrzyżowania.
  • Miejsca z komponentem adresu typu subpremise.

Identyfikatory te 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