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 (ad esempio, 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 in modo univoco un luogo.
Dettagli del luogo
L'oggetto
Place
fornisce informazioni su un luogo specifico. Puoi recuperare un oggetto
Place
nei seguenti modi:
- Chiama
PlacesClient.fetchPlace()
– Consulta la guida su come ottenere un luogo tramite ID. - Chiama
PlacesClient.findCurrentPlace()
– Consulta la guida per ottenere il luogo attuale.
Quando richiedi un luogo, devi specificare i dati del luogo da restituire. Per farlo, trasmetti un elenco di valori Place.Field che specificano i dati da restituire. Questo elenco è una considerazione importante perché influisce sul costo per ogni richiesta.
Poiché i risultati relativi ai dati dei luoghi non possono essere vuoti, vengono
restituiti solo quelli con dati. Ad esempio, se un luogo richiesto non contiene 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<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 ai
campi di dati specificati nella richiesta. Se il campo non è presente nell'oggetto Place
, il metodo correlato restituisce un valore nullo. Di seguito sono riportati alcuni esempi di alcuni dei metodi disponibili.
Per un elenco completo di tutti i metodi, consulta il riferimento API di Place
.
getAddress()
- L'indirizzo del luogo, in formato leggibile.getAddressComponents()
:List
di 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 degli indirizzi; chiama invecegetAddress()
, 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()
: ilOpeningHours
del luogo. RichiamaOpeningHours.getWeekdayText()
per restituire un elenco di stringhe che rappresentano gli orari di apertura e chiusura per ogni giorno della settimana. RichiamaOpeningHours.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 sette giorni successivi egetSecondaryOpeningHours()
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 specificata alcuna ora, il valore predefinito è ora.isOpen
verrà restituito solo se sono disponibili siaPlace.Field.UTC_OFFSET
chePlace.Field.OPENING_HOURS
. Per garantire risultati accurati, richiedi i campiPlace.Field.BUSINESS_STATUS
ePlace.Field.UTC_OFFSET
nella richiesta di luogo originale. Se non richiesto, si presume che l'attività sia operativa. Guarda questo video per scoprire come utilizzareisOpen
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. In Places SDK 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()
,
trasmettendo un FetchPlaceRequest
.
L'API restituisce un
FetchPlaceResponse
in un
Task
.
L'elemento
FetchPlaceResponse
contiene un oggetto
Place
corrispondente all'ID luogo fornito.
L'esempio di codice seguente mostra la chiamata a fetchPlace()
per
ottenere 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
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 prende 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 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 recuperarli. Per ulteriori informazioni sulla creazione di un oggetto Place con i campi necessari,
consulta Dettagli luogo.
L'esempio seguente determina se un luogo è attualmente aperto. In questo esempio, passi l'ID luogo a isOpen()
solo:
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 la tua app mostra informazioni sui luoghi, comprese le recensioni sui luoghi, deve mostrare anche eventuali attribuzioni. Per ulteriori informazioni, consulta attribuzioni.
Scopri di più sugli ID luogo
L'ID luogo utilizzato in Places SDK per Android è lo stesso utilizzato nell'API Places. Ogni ID luogo può fare riferimento a un solo luogo, ma un singolo luogo può avere più di un ID. In altri casi, un luogo potrebbe ricevere 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). Tieni presente, tuttavia, che la risposta potrebbe contenere un ID luogo diverso da quello indicato nella tua richiesta.
Per ulteriori informazioni, consulta la panoramica di Place ID.