Place Details

Seleziona la piattaforma: Android iOS JavaScript Servizio web

L'SDK Places per Android fornisce alla tua app informazioni dettagliate sui luoghi, tra cui nome e indirizzo, la posizione geografica specificata come coordinate di latitudine/longitudine, il tipo di luogo (come il night club, il negozio di animali e il museo). Per accedere a queste informazioni relative a 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 acquisire un oggetto Place nei seguenti modi:

• Chiamare PlacesClient.findCurrentPlace() – Consulta la guida per ottenere la posizione attuale.
• Chiama il numero PlacesClient.fetchPlace() - Consulta la guida per ottenere un luogo tramite ID.

Quando richiedi un luogo, devi specificare quali dati del luogo restituire. A questo scopo, trasmetti un elenco di valori Place.Field specificando i dati da restituire. Questo elenco è una considerazione importante perché influisce sul costo per ogni richiesta.

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

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

Java

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

Kotlin

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

Nota: mentre PlacesClient.fetchPlace() supporta tutti i dettagli del luogo, PlacesClient.findCurrentPlace() supporta solo un sottoinsieme di dettagli del luogo. Per l'elenco dei campi NON supportati da findCurrentPlace(), consulta la pagina sul supporto dei campi dell'SDK Places per Android.

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

• getAddress(): l'indirizzo del luogo, in formato leggibile.
• getAddressComponents(): un List di componenti di indirizzo per questo luogo. Questi componenti hanno lo scopo di estrarre informazioni strutturate sull'indirizzo di un luogo, ad esempio trovare la città in cui si trova. Non utilizzare questi componenti per la formattazione dell'indirizzo; chiama invece getAddress(), che fornisce un indirizzo in formato localizzato.
• getId(): l'identificatore testuale della sede. Leggi ulteriori informazioni 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 OpeningHours del luogo. Richiama OpeningHours.getWeekdayText() per restituire un elenco di stringhe che rappresentano l'orario di apertura e di chiusura per ogni giorno della settimana. Chiama 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 come domenica a mezzanotte e closeEvent è null.

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

• isOpen(): un valore booleano che indica se il luogo è attualmente aperto. Se non viene specificato alcun orario, il valore predefinito è ora. isOpen verrà restituito solo se sono disponibili sia Place.Field.UTC_OFFSET che Place.Field.OPENING_HOURS. Per ottenere risultati precisi, richiedi i campi Place.Field.BUSINESS_STATUS e Place.Field.UTC_OFFSET nella richiesta di luogo originale. Se non viene richiesto, si presume che l'attività sia operativa. Guarda questo video su come utilizzare isOpen con i dettagli del luogo.

  Nota: questo metodo è deprecato. Utilizza invece PlacesClient.isOpen(IsOpenRequest request). Per saperne di più, vedi Stato aperto.

Alcuni semplici esempi:

Java

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

      

Kotlin

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

      

Ottieni un luogo tramite ID

Un ID luogo è un identificatore di testo 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 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")
        }
    }

      

Puoi utilizzare un annullamentoToken per tentare di annullare una richiesta a una qualsiasi delle classi di richiesta (ad esempio FetchPlaceRequest). L'annullamento avviene secondo il criterio del "best effort". Quando viene 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 ti potrebbe comunque essere addebitato il costo della richiesta anche se non viene restituita alcuna risposta.

Ottieni stato aperto

Il metodo PlacesClient.isOpen(IsOpenRequest request) restituisce un oggetto IsOpenResponse che indica se il luogo è attualmente aperto in base all'ora specificata 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 l'ora in millisecondi da 1970-01-01T00:00:00Z. Se non viene specificato alcun orario, il valore predefinito è ora.

Questo metodo richiede l'esistenza dei seguenti campi nell'oggetto Place:

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

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

Nota: lo SKU di dati di base di Places viene addebitato alle chiamate al numero fetchPlace() per Place.Field.UTC_OFFSET e Place.Field.BUSINESS_STATUS. Lo SKU di dati di contatto 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, trasmetti l'ID luogo solo a 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());
// ...

      

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
}
// ...

      

L'esempio seguente mostra la chiamata a isOpen() in cui passi un oggetto Place. L'oggetto Place deve contenere un ID luogo valido:

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

      

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
    }
    // ...
}
// ...

      

Attribuzioni display nell'app

Quando nella tua app vengono visualizzate informazioni sul luogo, l'app deve mostrare anche le attribuzioni. Consulta la documentazione sulle attribuzione.

Scopri di più sugli ID luogo

L'ID luogo utilizzato nell'SDK Places per Android è lo stesso identificatore usato nell'API Places. Ogni ID luogo può fare riferimento a un solo luogo, ma un singolo luogo può avere più un ID luogo. Esistono altri casi in cui un luogo potrebbe ricevere un nuovo ID luogo. Ad esempio, questo può accadere se un'attività viene trasferita in una nuova sede.

Quando richiedi un luogo specificando un ID luogo, puoi avere 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 ulteriori informazioni, consulta la panoramica sull'ID luogo.