Place Details

Seleziona la piattaforma: Android iOS JavaScript Servizio web

Places SDK per Android fornisce alla tua app informazioni dettagliate sui luoghi, tra cui nome e indirizzo, l'area geografica località specificata come coordinate di latitudine/longitudine, il tipo di luogo (ad esempio come discoteca, negozio di animali, museo e altro ancora. Per accedere a queste informazioni per un luogo specifico, puoi utilizzare l'ID luogo, un identificatore stabile che identifica un luogo.

Dettagli del luogo

La Place fornisce informazioni su un luogo specifico. Puoi ottenere Place nei modi seguenti:

Quando richiedi un luogo, devi specificare i dati del luogo da restituire. Per farlo, trasmetti un elenco di Place.Field che specificano i dati da restituire. Questo elenco è una considerazione importante perché influisce sulla costo per ogni richiesta.

Poiché i risultati dei dati sui luoghi non possono essere vuoti, vengono visualizzati solo i risultati dei luoghi con dati restituito (ad esempio, se un luogo richiesto non ha foto, photos non sarà presente nel risultato).

L'esempio seguente trasmette un elenco di tre Valori di 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<Place.Field> placeFields = Arrays.asList(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS);

Accesso ai campi dati dell'oggetto Place

Dopo aver ottenuto l'oggetto Place, utilizza i metodi dell'oggetto per accedere all'oggetto 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 di alcuni dei metodi disponibili. Per un elenco completo di tutti i metodi, consulta Place Riferimento API.

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

  • getOpeningHours() - Il OpeningHours del luogo. Chiama OpeningHours.getWeekdayText() per restituire un elenco di stringhe che rappresentano gli orari di apertura e chiusura di ogni giorno di durante la settimana. Chiama OpeningHours.getPeriods() per restituire un elenco di period oggetti con informazioni più dettagliate, equivalenti ai dati forniti da getWeekdayText().

    L'oggetto Place contiene anche getCurrentOpeningHours() che restituisce l'orario di apertura di un luogo nei sette giorni successivi e getSecondaryOpeningHours() che restituisce l'orario secondario di apertura di un luogo nei sette giorni successivi.

  • isOpen(): un valore booleano che indica se il luogo è attualmente aperti. Se non viene specificata alcuna ora, il valore predefinito è ora. isOpen verrà restituito solo se Place.Field.UTC_OFFSET e Place.Field.OPENING_HOURS sono disponibili. Per garantire l'accuratezza risultati, richiedi Place.Field.BUSINESS_STATUS e Place.Field.UTC_OFFSET campi nella richiesta di luogo originale. Se non richiesto, si presume che l'attività sia operativa. Guarda questo video per scoprire come utilizzare isOpen con Place Details.

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();

Ottieni un luogo tramite ID

Un ID luogo è un identificatore testuale che identifica in modo univoco un luogo. Nella Places SDK per Android, puoi recuperare l'ID di un luogo chiamando Place.getId() La Servizio Place Autocomplete restituisce anche un ID luogo per ogni luogo che corrisponde alla query di ricerca e filtrare. Puoi memorizzare l'ID luogo e utilizzarlo per recuperare il Place di nuovo in seguito.

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

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

L'esempio di codice seguente mostra la chiamata di fetchPlace() a ottieni i dettagli per il 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.
    }
});

Ottieni stato di apertura

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

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

  • Un Place o una stringa che specifica un ID luogo.
  • Un valore di tempo facoltativo che specifica il tempo in millisecondi da 1970-01-01T00:00:00Z. Se non viene specificata alcuna ora, il valore predefinito è ora.

Questo metodo richiede la presenza 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 vengono forniti nell'oggetto Place o se passi un ID luogo, il metodo utilizza PlacesClient.fetchPlace() per recuperarle. Per ulteriori informazioni sulla creazione di un oggetto Place con i campi necessari, consulta Dettagli sul luogo.

L'esempio seguente determina se un luogo è attualmente aperto. In questo esempio, passi solo l'ID luogo per 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());
// ...

Il prossimo esempio mostra la chiamata a isOpen() in cui 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, comprese recensioni sui luoghi, deve mostrare anche eventuali attribuzioni. Per ulteriori informazioni, vedi attribuzioni.

Scopri di più sugli ID luogo

L'ID luogo utilizzato in Places SDK per Android è lo stesso come utilizzato nell'API Places. Ogni ID luogo può fare riferimento a un solo luogo, ma un singolo luogo può averne più di di un ID luogo. Esistono altre circostanze che possono indurre un luogo a ottenere un nuovo ID luogo. Ad esempio, questo può accadere se un'attività passa a una nuova in ogni località.

Quando richiedi un luogo specificando un ID luogo, hai la certezza che riceverai sempre lo stesso punto nella risposta (se il luogo esiste già). Tieni presente, tuttavia, che la risposta potrebbe contenere un ID luogo che diverso da quello indicato nella tua richiesta.

Per ulteriori informazioni, consulta panoramica di Place ID.