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 ListplaceFields = 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)
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()
: unList
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 invecegetAddress()
, 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()
: ilOpeningHours
del luogo. RichiamaOpeningHours.getWeekdayText()
per restituire un elenco di stringhe che rappresentano l'orario di apertura e di chiusura per ogni giorno della settimana. ChiamaOpeningHours.getPeriods()
per restituire un elenco di oggettiperiod
con informazioni più dettagliate equivalenti ai dati forniti dagetWeekdayText()
.L'oggetto
Place
contiene anche il metodogetCurrentOpeningHours()
che restituisce l'orario di apertura di un luogo nei prossimi sette giorni egetSecondaryOpeningHours()
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 siaPlace.Field.UTC_OFFSET
chePlace.Field.OPENING_HOURS
. Per ottenere risultati precisi, richiedi i campiPlace.Field.BUSINESS_STATUS
ePlace.Field.UTC_OFFSET
nella richiesta di luogo originale. Se non viene richiesto, si presume che l'attività sia operativa. Guarda questo video su come utilizzareisOpen
con i dettagli del luogo.
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") } }
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. - 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.
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.