ID posizione

Seleziona la piattaforma: Android iOS JavaScript Servizio web

Gli ID luogo identificano in modo univoco un luogo nel database di Google Places e su Google Maps. Gli ID luogo sono accettati nelle richieste alle seguenti API di Google Maps:

  • Recupero di un indirizzo per un ID luogo nel servizio web dell'API Geocoding e nel servizio Geocoding, API Maps JavaScript.
  • Specificare i punti di arrivo, di destinazione e intermedi nel servizio web dell'API Directions e nel servizio Directions, l'API Maps JavaScript.
  • Specificare origini e destinazioni nel servizio web dell'API Distance Matrix e nel servizio Distance Matrix, l'API Maps JavaScript.
  • Recupero dei dettagli del luogo nel servizio web dell'API Places, SDK Places per Android, SDK Places per iOS e libreria Places.
  • Utilizzare i parametri dell'ID luogo nell'API Maps Embed.
  • Recupero delle query di ricerca negli URL di Maps.
  • Visualizzazione dei limiti di velocità nell'API Roads.
  • Trovare e applicare uno stile ai poligoni dei confini nello stile basato sui dati per i confini.

Trovare l'ID di un luogo specifico

Cerchi l'ID di un luogo specifico? Utilizza lo strumento di ricerca degli ID luogo di seguito per cercare un luogo e recuperarne l'ID:

In alternativa, puoi visualizzare lo strumento di ricerca degli ID luogo con il codice nella documentazione dell'API Maps JavaScript.

Panoramica

Un ID luogo è un identificatore di testo che identifica in modo univoco un luogo. La lunghezza dell'identificatore può variare (non esiste una lunghezza massima per gli ID luogo). Esempi:

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

Gli ID luogo sono disponibili per la maggior parte delle sedi, ad esempio attività, punti di riferimento, parchi e incroci. È possibile che uno stesso luogo o una stessa sede abbiano più ID luogo diversi. Gli ID luogo possono cambiare nel tempo.

Puoi utilizzare lo stesso ID luogo nell'API Places e in varie API di Google Maps Platform. Ad esempio, potete utilizzare lo stesso ID luogo per fare riferimento a un luogo nell'API Places, nell'API Maps JavaScript, nell'API Geocoding, nell'API Maps Embed e nell'API Roads.

Recuperare i dettagli del luogo utilizzando l'ID luogo

Gli ID luogo sono esenti dalle restrizioni di memorizzazione nella cache indicate nella Sezione 3.2.3(b) dei Termini di servizio di Google Maps Platform. Dopo aver identificato l'ID luogo per un luogo, puoi riutilizzarlo la volta successiva che lo cerchi. Per maggiori informazioni, consulta la sezione Salvare gli ID luogo per utilizzarli in un secondo momento di seguito.

Un modo comune per utilizzare gli ID luogo è cercare un luogo (ad esempio, tramite l'API Places o la libreria Places nell'API Maps JavaScript), quindi utilizzare l'ID luogo restituito per recuperarne i dettagli. Puoi memorizzare l'ID luogo e utilizzarlo per recuperare gli stessi dettagli in un secondo momento. Scopri di più su come salvare gli ID luogo di seguito.

Esempio di utilizzo dell'SDK Places per Android

Nell'SDK Places per Android, puoi recuperare l'ID di un luogo chiamando Place.getId(). Il servizio Place Autocomplete restituisce anche un ID luogo per ogni luogo che corrisponde alla query di ricerca e al filtro forniti. Utilizza l'ID luogo per recuperare di nuovo l'oggetto Place in un secondo momento.

Per ottenere un luogo tramite ID, chiama PlacesClient.fetchPlace(), passando un FetchPlaceRequest.

L'API restituisce FetchPlaceResponse in Task. FetchPlaceResponse contiene un oggetto Place corrispondente all'ID luogo fornito.

L'esempio di codice riportato di seguito mostra la chiamata a fetchPlace() per ricevere i dettagli del luogo specificato.

Java


// Define a Place ID.
final String placeId = "INSERT_PLACE_ID_HERE";

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

// 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();
    Log.i(TAG, "Place found: " + place.getName());
}).addOnFailureListener((exception) -> {
    if (exception instanceof ApiException) {
        final ApiException apiException = (ApiException) exception;
        Log.e(TAG, "Place not found: " + exception.getMessage());
        final int statusCode = apiException.getStatusCode();
        // TODO: Handle error with given status code.
    }
});

      

Kotlin


// Define a Place ID.
val placeId = "INSERT_PLACE_ID_HERE"

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

// 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
        Log.i(PlaceDetailsActivity.TAG, "Place found: ${place.name}")
    }.addOnFailureListener { exception: Exception ->
        if (exception is ApiException) {
            Log.e(TAG, "Place not found: ${exception.message}")
            val statusCode = exception.statusCode
            TODO("Handle error with given status code")
        }
    }

      

Salvare gli ID luogo per utilizzarli in un secondo momento

Gli ID luogo sono esenti dalle limitazioni relative alla memorizzazione nella cache indicate nella Sezione 3.2.3(b) dei Termini di servizio di Google Maps Platform. Puoi quindi memorizzare i valori degli ID luogo per utilizzarli in un secondo momento.

Aggiornamento degli ID dei luoghi memorizzati in corso

Ti consigliamo di aggiornare gli ID luogo se hanno più di 12 mesi. Puoi aggiornare gli ID luogo senza costi effettuando una richiesta Dettagli luogo, specificando solo il campo Place.Field.ID nel parametro fields. Questa chiamata attiverà lo SKU Places Places - ID Refresh SKU. Tuttavia, questa richiesta potrebbe restituire anche un codice di stato NOT_FOUND. Una strategia è archiviare la richiesta originale che ha restituito ogni ID luogo. Se un ID luogo non è più valido, puoi emettere nuovamente la richiesta per ottenere nuovi risultati. Questi risultati possono includere o meno il luogo originale. La richiesta è addebitabile.

Codici di errore durante l'utilizzo degli ID luogo

Il codice di stato INVALID_REQUEST indica che l'ID luogo specificato non è valido. INVALID_REQUEST può essere restituito quando l'ID luogo è stato troncato o modificato in altro modo e non è più corretto.

Il codice di stato NOT_FOUND indica che l'ID luogo specificato è obsoleto. L'ID luogo può diventare obsoleto se un'attività chiude o si sposta in una nuova sede. Gli ID dei luoghi possono cambiare a causa di aggiornamenti su larga scala nel database di Google Maps. In questi casi, un luogo potrebbe ricevere un nuovo ID luogo e il vecchio ID restituisce una risposta NOT_FOUND.

In particolare, alcuni tipi di ID luogo a volte possono causare una risposta NOT_FOUND oppure l'API potrebbe restituire un ID luogo diverso nella risposta. Questi tipi di ID luogo includono:

  • Indirizzi che non esistono in Google Maps come indirizzi precisi, ma vengono dedotti da un intervallo di indirizzi.
  • Segmenti di un percorso lungo, in cui la richiesta specifica anche una città o una località.
  • Incroci.
  • Luoghi con un componente dell'indirizzo di tipo subpremise.

Questi ID hanno spesso la forma di una lunga stringa (non esiste una lunghezza massima per gli ID luogo). Ad esempio:

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