Place Details

Seleziona la piattaforma: Android iOS JavaScript Servizio web

L'SDK Places per Android fornisce alla tua app informazioni dettagliate sui luoghi, inclusi il nome e l'indirizzo, la posizione geografica specificata come coordinate di latitudine/longitudine, il tipo di luogo (ad esempio discoteca, negozio di animali, museo) e altro ancora. Per accedere a queste informazioni su un luogo specifico, puoi utilizzare l'ID luogo, un identificatore stabile che identifica in modo univoco un luogo.

Dettagli luogo

L'oggetto Place fornisce informazioni su un luogo specifico. Puoi recuperare un oggetto Place nei seguenti modi:

• Chiama il numero PlacesClient.fetchPlace() – Consulta la guida su come ottenere un luogo in base all'ID.
• Chiama il numero PlacesClient.findCurrentPlace() – Consulta la guida per trovare il luogo attuale.
  Mentre PlacesClient.fetchPlace() supporta tutti i campi di dati relativi al luogo, PlacesClient.findCurrentPlace() supporta solo un sottoinsieme di campi di dati relativi al luogo. Per l'elenco dei campi NON supportati da findCurrentPlace(), consulta Supporto dei campi dell'SDK Places per Android.

Quando richiedi un luogo, devi specificare i relativi dati da restituire. Per farlo, passa un elenco di valori di Place.Field per specificare i dati da restituire. Questo elenco è importante da valutare perché influisce sul costo per ogni richiesta.

Poiché i risultati relativi ai dati dei luoghi non possono essere vuoti, vengono restituiti solo i risultati che contengono dati (ad esempio, se un luogo richiesto non ha foto, il campo photos non sarà presente nel risultato).

L'esempio seguente passa un elenco di tre valori Place.Field per specificare i dati restituiti da una richiesta:

Kotlin

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

Java

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

Nota: l'SDK Places per Android e l'SDK Places per Android (nuovo) supportano modelli di prezzi diversi. Ciò significa che il prezzo di una chiamata si basa sui campi richiesti e sulla versione dell'SDK in uso. Per informazioni dettagliate sui prezzi di entrambi gli SDK, consulta la sezione Utilizzo e fatturazione.

Accedere ai campi dati oggetto Place

Dopo aver ottenuto l'oggetto Place, utilizza i metodi dell'oggetto per accedere ai campi di dati specificati nella richiesta. Se il campo non è presente nell'oggetto Place, il metodo correlato restituisce null. Di seguito sono riportati alcuni esempi dei metodi disponibili. Per un elenco completo di tutti i metodi, consulta il riferimento dell'API Place.

• getAddress() - L'indirizzo del luogo, in formato leggibile.
• getAddressComponents() - Un List dei componenti dell'indirizzo per questo luogo. Questi componenti vengono forniti allo scopo di estrarre informazioni strutturate sull'indirizzo di un luogo, ad esempio per trovare la città in cui si trova un luogo. Non utilizzare questi componenti per la formattazione dell'indirizzo; chiama invece getAddress(), che fornisce un indirizzo formattato localizzato.
• getId() - L'identificatore testuale del luogo. Scopri di più sugli ID luogo nel resto di questa pagina.
• getLatLng() - La posizione geografica del luogo, specificata come coordinate di latitudine e longitudine.
• getName() - Il nome del luogo.

• getOpeningHours(): il valore OpeningHours del luogo. Richiama OpeningHours.getWeekdayText() per restituire un elenco di stringhe che rappresentano gli orari di apertura e chiusura di ogni giorno della settimana. Richiama OpeningHours.getPeriods() per restituire un elenco di oggetti period con informazioni più dettagliate equivalenti ai dati forniti da getWeekdayText().

  Nota: se un luogo è sempre aperto, il periodo di tempo è rappresentato da domenica a mezzanotte e closeEvent è null.

  L'oggetto Place contiene anche il metodo getCurrentOpeningHours() che restituisce gli orari di apertura di un luogo nei sette giorni successivi e getSecondaryOpeningHours() che restituisce gli orari di apertura secondari di un luogo nei sette giorni successivi.

• isOpen() - Un valore booleano che indica se il luogo è attualmente aperto. Se non viene specificato alcun orario, il valore predefinito è quello attuale. isOpen verrà restituito solo se sono disponibili sia Place.Field.UTC_OFFSET che Place.Field.OPENING_HOURS. Per garantire risultati accurati, richiedi i campi Place.Field.BUSINESS_STATUS e Place.Field.UTC_OFFSET nella richiesta di luogo originale. Se non richiesto, si presume che l'attività sia operativa. Guarda questo video per scoprire come utilizzare isOpen con Dettagli luogo.

  Nota: questo metodo è obsoleto. Utilizza invece PlacesClient.isOpen(IsOpenRequest request). Per saperne di più, consulta la pagina su come ottenere lo stato di apertura.

Alcuni semplici esempi:

Kotlin

val name = place.name
val address = place.address
val location = place.latLng

      

Java

final CharSequence name = place.getName();
final CharSequence address = place.getAddress();
final LatLng location = place.getLatLng();

      

Accedere ai dati dei luoghi aggiunti nella versione 3.3.0

L'SDK Places per Android versione 3.3.0 aggiunge nuovi dati a Place:

• Tipi di luogo: nuovi valori di tipo associati a un luogo.
• Recensioni: fino a cinque recensioni per un luogo.
• Codice lingua del nome: il codice lingua per il nome di un luogo.

Le sezioni seguenti descrivono come accedere a questi nuovi dati.

Nota: il nuovo SDK supporta solo i nuovi dati Place in Java.

Accedi a nuovi tipi di luoghi

A ogni luogo possono essere associati uno o più valori type. L'SDK Places per la versione 3.3.0 di Android aggiunge molti nuovi valori di tipo. Per l'elenco completo, consulta Tipi di luoghi espansi.

Nell'SDK Places per Android 3.2.0 e versioni precedenti, hai utilizzato il metodo Place.getTypes() per accedere ai valori di tipo associati a un luogo. Place.getTypes() restituisce un elenco di tipi come valori di enumerazione definiti da Place.Types.

Il metodo Place.getTypes() è deprecato a partire dall'SDK Places per Android versione 3.3.0. Anche se puoi continuare a utilizzarlo durante il periodo di deprecazione, devi eseguire la migrazione delle tue app per usare Place.getPlaceTypes().

Il metodo Place.getPlaceTypes() restituisce i valori di tipo sotto forma di elenco di valori stringa. I valori restituiti dipendono dalla tua versione di Places SDK for Android:

• SDK Places per Android (nuovo): restituisce le stringhe definite dalla Tabella A e dalla Tabella B mostrate in Tipi di luogo (Nuova), inclusi tutti i tipi di luogo aggiunti aggiunti nella versione 3.3.0.
• SDK Places per Android: restituisce le enum definite da Place.Types, che non include i nuovi tipi aggiunti nella versione 3.3.0.

Per conoscere le principali differenze tra le due versioni dell'SDK, consulta Scegliere la versione dell'SDK.

Accedi alle recensioni dei luoghi

L'SDK Places per Android (nuovo) aggiunge la classe Review, che contiene una recensione di un luogo. L'oggetto Place può contenere fino a cinque recensioni.

La classe Review può anche contenere un'attribuzione e un'attribuzione dell'autore. Se visualizzi la recensione nella tua app, devi indicare anche eventuali attribuzioni o attribuzioni dell'autore. Per ulteriori informazioni, consulta l'articolo Visualizzare una recensione.

Per completare l'oggetto Place con le recensioni, devi:

1. Abilita il nuovo SDK quando configuri il tuo progetto Google Cloud.
2. Inizializza il nuovo SDK all'interno di un'attività o di un frammento.
3. Includi Place.Field.REVIEWS nell'elenco dei campi della richiesta dei dettagli del luogo.
4. Chiama il numero PlacesClient.fetchPlace(). Il campo delle recensioni non è supportato da PlacesClient.findCurrentPlace().
5. Utilizza il metodo Place.getReviews() per accedere al campo dei dati delle recensioni nell'oggetto Place.

Accedi al codice lingua del nome del luogo

Il metodo Place.getName() esistente restituisce una stringa di testo contenente il nome di un luogo. Per completare l'oggetto Place con il nome del luogo, devi includere Place.Field.NAME nell'elenco dei campi della richiesta di dettagli del luogo.

L'oggetto Place ora contiene il codice lingua per la stringa del nome. Per compilare l'oggetto Place con il codice lingua, devi:

1. Abilita il nuovo SDK quando configuri il tuo progetto Google Cloud.
2. Inizializza il nuovo SDK all'interno di un'attività o di un frammento.
3. Includi Place.Field.NAME nell'elenco dei campi della richiesta. Questo valore configura la risposta in modo da includere sia il nome del luogo sia il codice lingua nell'oggetto Place.
4. Chiama il numero PlacesClient.fetchPlace(). PlacesClient.findCurrentPlace() non supporta il campo del codice lingua.
5. Utilizza il metodo Place.getNameLanguageCode() per accedere al campo del codice lingua nell'oggetto Place.

Impostare il codice regione nella versione 3.3.0

L'SDK Places per Android (nuovo) aggiunge il parametro di richiesta del codice regione a Place Details. Il codice regione viene utilizzato per formattare la risposta, specificato come valore di codice CLDR a due caratteri. Questo parametro può anche avere un effetto di bias sui risultati di ricerca. Non è presente alcun valore predefinito. Devi abilitare il nuovo SDK per impostare il codice regione.

Se il nome del paese nel campo dell'indirizzo nella risposta corrisponde al codice regione, il codice paese viene omesso dall'indirizzo.

La maggior parte dei codici CLDR è identica ai codici ISO 3166-1, con alcune eccezioni degne di nota. Ad esempio, il ccTLD del Regno Unito è "uk " (.co.uk), mentre il codice ISO 3166-1 è"gb " (tecnicamente per l'entità "Regno Unito di Gran Bretagna e Irlanda del Nord"). Il parametro può influire sui risultati in base alla legge vigente.

Ottieni un luogo in base all'ID

Un ID luogo è un identificatore testuale che identifica in modo univoco un luogo. 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. Puoi archiviare l'ID luogo e utilizzarlo per recuperare di nuovo l'oggetto Place in un secondo momento.

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

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

Il seguente esempio di codice mostra la chiamata a fetchPlace() per ottenere i dettagli relativi al luogo specificato.

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")
        }
    }

      

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.
    }
});

      

Puoi utilizzare un CancellationToken per tentare di annullare una richiesta a qualsiasi classe di richiesta (ad esempio, FetchPlaceRequest). L'annullamento viene eseguito secondo il criterio del "best effort". Una volta inviata una richiesta di annullamento, non verrà restituita alcuna risposta. L'emissione di un token di annullamento NON garantisce l'annullamento di una determinata richiesta e potresti comunque ricevere un addebito per la richiesta, anche se non viene restituita una risposta.

Ottieni lo stato di apertura

Il metodo PlacesClient.isOpen(IsOpenRequest request) restituisce un oggetto IsOpenResponse che indica se il luogo è attualmente aperto in base all'orario specificato nella chiamata.

Questo metodo utilizza un singolo argomento di tipo IsOpenRequest che contiene:

• Un oggetto Place o una stringa che specifica un ID luogo.
  Nota: l'oggetto Place deve contenere un ID luogo valido.
• Un valore di tempo facoltativo che specifica il tempo in millisecondi da 1970-01-01T00:00:00Z. Se non viene specificato alcun orario, il valore predefinito è quello attuale.

Questo metodo richiede che nell'oggetto Place esistano i seguenti campi:

• Place.Field.BUSINESS_STATUS
• Place.Field.CURRENT_OPENING_HOURS
• Place.Field.OPENING_HOURS
• Place.Field.UTC_OFFSET

Se questi campi non vengono forniti nell'oggetto Place o se passi un ID luogo, il metodo utilizza PlacesClient.fetchPlace() per recuperarli. Per ulteriori informazioni sulla creazione dell'oggetto Place con i campi necessari, vedi Dettagli luogo.

Nota: lo SKU di dati di base di Places viene addebitato per le chiamate a fetchPlace() per Place.Field.UTC_OFFSET e Place.Field.BUSINESS_STATUS. Lo SKU di Contact Data di Places viene addebitato per le chiamate a fetchPlace() per Place.Field.CURRENT_OPENING_HOURS e Place.Field.OPENING_HOURS.

L'esempio seguente determina se un luogo è attualmente aperto. In questo esempio, passi l'ID luogo solo a isOpen():

Kotlin

val isOpenCalendar: Calendar = Calendar.getInstance()
val placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk"

val request: IsOpenRequest = try {
    IsOpenRequest.newInstance(placeId, isOpenCalendar.timeInMillis)
} catch (e: IllegalArgumentException) {
    e.printStackTrace()
    return
}
val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(request)
isOpenTask.addOnSuccessListener { response ->
    val isOpen = response.isOpen
}
// ...

      

Java

@NonNull
Calendar isOpenCalendar = Calendar.getInstance();
String placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk";
IsOpenRequest isOpenRequest;

try {
    isOpenRequest = IsOpenRequest.newInstance(placeId, isOpenCalendar.getTimeInMillis());
} catch (IllegalArgumentException e) {
    e.printStackTrace();
    return;
}

Task<IsOpenResponse> placeTask = placesClient.isOpen(isOpenRequest);

placeTask.addOnSuccessListener(
        (response) ->
                isOpen = response.isOpen());
// ...

      

L'esempio successivo mostra una chiamata a isOpen() dove passi un oggetto Place. L'oggetto Place deve contenere un ID luogo valido:

Kotlin

val isOpenCalendar: Calendar = Calendar.getInstance()
var place: Place
val placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk"
// Specify the required fields for an isOpen request.
val placeFields: List<Place.Field> = listOf(
    Place.Field.BUSINESS_STATUS,
    Place.Field.CURRENT_OPENING_HOURS,
    Place.Field.ID,
    Place.Field.OPENING_HOURS,
    Place.Field.UTC_OFFSET
)

val placeRequest: FetchPlaceRequest =
    FetchPlaceRequest.newInstance(placeId, placeFields)
val placeTask: Task<FetchPlaceResponse> = placesClient.fetchPlace(placeRequest)
placeTask.addOnSuccessListener { placeResponse ->
    place = placeResponse.place

    val isOpenRequest: IsOpenRequest = try {
        IsOpenRequest.newInstance(place, isOpenCalendar.timeInMillis)
    } catch (e: IllegalArgumentException) {
        e.printStackTrace()
        return@addOnSuccessListener
    }
    val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(isOpenRequest)
    isOpenTask.addOnSuccessListener { isOpenResponse ->
        val isOpen = isOpenResponse.isOpen
    }
    // ...
}
// ...

      

Java

@NonNull
Calendar isOpenCalendar = Calendar.getInstance();
String placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk";
// Specify the required fields for an isOpen request.
List<Place.Field> placeFields = new ArrayList<>(Arrays.asList(
        Place.Field.BUSINESS_STATUS,
        Place.Field.CURRENT_OPENING_HOURS,
        Place.Field.ID,
        Place.Field.OPENING_HOURS,
        Place.Field.UTC_OFFSET
));

FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields);
Task<FetchPlaceResponse> placeTask = placesClient.fetchPlace(request);

placeTask.addOnSuccessListener(
        (placeResponse) -> {
            Place place = placeResponse.getPlace();
            IsOpenRequest isOpenRequest;

            try {
                isOpenRequest = IsOpenRequest.newInstance(place, isOpenCalendar.getTimeInMillis());
            } catch (IllegalArgumentException e) {
                e.printStackTrace();
                return;
            }
            Task<IsOpenResponse> isOpenTask = placesClient.isOpen(isOpenRequest);

            isOpenTask.addOnSuccessListener(
                    (isOpenResponse) -> isOpen = isOpenResponse.isOpen());
            // ...
        });
// ...

      

Attribuzioni display nell'app

Quando l'app mostra informazioni sui luoghi, ad esempio recensioni di luoghi, deve mostrare anche eventuali attribuzioni. Per ulteriori informazioni, consulta la sezione Attribuzioni.

Scopri di più sugli ID luogo

L'ID luogo utilizzato nell'SDK Places per Android è lo stesso identificatore utilizzato nell'API Places. Ogni ID luogo può fare riferimento a un solo luogo, ma un luogo può avere più di un ID luogo. In altre circostanze, è possibile che un luogo ottenga un nuovo ID luogo. Ad esempio, questo può accadere se un'attività si sposta in una nuova sede.

Quando richiedi un luogo specificando un ID luogo, hai la certezza che riceverai sempre lo stesso luogo nella risposta (se il luogo esiste ancora). Tuttavia, tieni presente che la risposta potrebbe contenere un ID luogo diverso da quello indicato nella richiesta.

Per maggiori informazioni, consulta la panoramica di ID luogo.