Dettagli del luogo (legacy)

Sviluppatori dello Spazio economico europeo (SEE)

Se il tuo indirizzo di fatturazione si trova nello Spazio economico europeo, a partire dall'8 luglio 2025, i Termini di servizio di Google Maps Platform per il SEE si applicheranno al tuo utilizzo dei servizi. La funzionalità varia in base alla regione. Scopri di più.

Questo prodotto è in stato legacy. A partire da ottobre 2026, l'API Places (legacy) non potrà più essere abilitata per i nuovi progetti Google Cloud. I progetti esistenti rimangono completamente supportati. Per nuove funzionalità e prestazioni migliorate, esegui la migrazione all'API Places (nuova).

Places SDK for Android (Legacy) fornisce alla tua app informazioni dettagliate sui luoghi, tra cui 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 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 ottenere un oggetto Place chiamando PlacesClient.fetchPlace(). Consulta la guida su come ottenere un luogo in base all'ID.

Quando richiedi un luogo, devi specificare quali dati del luogo restituire. Per farlo, passa un elenco di valori Place.Field che specificano i dati da restituire. Questo elenco è un fattore importante da considerare perché influisce sul costo di ogni richiesta.

Poiché i risultati dei dati sui luoghi non possono essere vuoti, vengono restituiti solo i risultati dei luoghi con 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.DISPLAY_NAME, Place.Field.RATING)

Java

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

Accedi ai campi di 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 null. Di seguito sono riportati alcuni esempi dei metodi disponibili.

Per un elenco completo di tutti i metodi, consulta il riferimento API Place.

• getAddress(): l'indirizzo del luogo in un formato leggibile.
• getAddressComponents(): un 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 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 OpeningHours del luogo. Chiama OpeningHours.getWeekdayText() per restituire un elenco di stringhe che rappresentano gli orari di apertura e 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 sette giorni successivi, e getSecondaryOpeningHours(), che restituisce l'orario di apertura secondario 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 è l'ora corrente. 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 viene richiesto, si presume che l'attività sia operativa. Guarda questo video per scoprire come utilizzare isOpen con Place Details.

  Nota: questo metodo è stato ritirato. Utilizza invece PlacesClient.isOpen(IsOpenRequest request). Per saperne di più, consulta Recupera lo stato di apertura.

Ecco alcuni esempi:

Kotlin

        val name = place.displayName
        val address = place.formattedAddress
        val location = place.location

      

Java

                    final CharSequence name = place.getDisplayName();
                    final CharSequence address = place.getFormattedAddress();
                    final LatLng location = place.getLocation();

      

Ottieni un luogo in base all'ID

Un ID luogo è un identificatore testuale che identifica in modo univoco un luogo. In Places SDK for 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 memorizzare l'ID luogo e utilizzarlo per recuperare l'oggetto Place in un secondo momento.

Per recuperare un luogo in base all'ID, chiama PlacesClient.fetchPlace(), passando un FetchPlaceRequest.

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

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

Kotlin

// Define a Place ID.
val placeId = PlaceIdProvider.getRandomPlaceId()

// Specify the fields to return.
val placeFields = listOf(
    Place.Field.ID,
    Place.Field.DISPLAY_NAME,
    Place.Field.FORMATTED_ADDRESS,
    Place.Field.LOCATION,
)

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

        val name = place.displayName
        val address = place.formattedAddress
        val location = place.location

        binding.placeName.text = name
        binding.placeAddress.text = address
        if (location != null) {
            binding.placeLocation.text = getString(
                R.string.place_location,
                location.latitude,
                location.longitude,
            )
        } else {
            binding.placeLocation.text = null
        }
        Log.i(TAG, "Place found: ${place.displayName}")
    }.addOnFailureListener { exception: Exception ->
        if (exception is ApiException) {
            val message = getString(R.string.place_not_found, exception.message)
            binding.placeName.text = message
            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 = PlaceIdProvider.getRandomPlaceId();

// Specify the fields to return.
final List<Place.Field> placeFields =
        Arrays.asList(
                Place.Field.ID,
                Place.Field.DISPLAY_NAME,
                Place.Field.FORMATTED_ADDRESS,
                Place.Field.LOCATION);

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

                    final CharSequence name = place.getDisplayName();
                    final CharSequence address = place.getFormattedAddress();
                    final LatLng location = place.getLocation();

                    binding.placeName.setText(name);
                    binding.placeAddress.setText(address);
                    if (location != null) {
                        binding.placeLocation.setText(
                                getString(
                                        R.string.place_location,
                                        location.latitude,
                                        location.longitude));
                    } else {
                        binding.placeLocation.setText(null);
                    }

                    Log.i(TAG, "Place found: " + place.getDisplayName());
                })
        .addOnFailureListener(
                (exception) -> {
                    if (exception instanceof ApiException apiException) {
                        final String message =
                                getString(
                                        R.string.place_not_found,
                                        apiException.getMessage());
                        binding.placeName.setText(message);
                        Log.e(TAG, "Place not found: " + exception.getMessage());
                        final int statusCode = apiException.getStatusCode();
                        // TODO: Handle error with given status code.
                    }
                });

      

Nota: per ulteriori informazioni sull'inizializzazione di PlacesClient, consulta Inizializza il client API Places.

Puoi utilizzare un CancellationToken per tentare di annullare una richiesta a una qualsiasi delle classi 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 che una determinata richiesta venga annullata e l'addebito per la richiesta potrebbe comunque essere applicato anche se non viene restituita alcuna risposta.

Ottenere 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 accetta un singolo argomento di tipo IsOpenRequest che contiene:

• Un oggetto Place o una stringa che specifica un ID luogo.
  Place
• Un valore di ora facoltativo che specifica l'ora in millisecondi dal giorno 01/01/1970T00:00:00Z. Se non viene specificato alcun orario, il valore predefinito è l'ora corrente.

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 saperne di più sulla creazione dell'oggetto Place con i campi necessari, consulta Place Details.

Nota: lo SKU Dati di base di Places viene addebitato per le chiamate a fetchPlace() per Place.Field.UTC_OFFSET e Place.Field.BUSINESS_STATUS. Lo SKU 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, passi solo l'ID luogo a isOpen():

Kotlin

val isOpenCalendar: Calendar = Calendar.getInstance()
val placeId = PlaceIdProvider.getRandomPlaceId()

val request: IsOpenRequest = try {
    IsOpenRequest.newInstance(placeId, isOpenCalendar.timeInMillis)
} catch (e: IllegalArgumentException) {
    Log.e("PlaceIsOpen", "Error: " + e.message)
    return
}
val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(request)
isOpenTask.addOnSuccessListener { response ->
    val isOpen = response.isOpen ?: false
    binding.isOpenByIdResult.text = getString(R.string.is_open_by_id, isOpen.toString())
    Log.d("PlaceIsOpen", "Is open by ID: $isOpen")
}
// ...

      

Java

@NonNull Calendar isOpenCalendar = Calendar.getInstance();
String placeId = PlaceIdProvider.getRandomPlaceId();
IsOpenRequest isOpenRequest;

try {
    isOpenRequest = IsOpenRequest.newInstance(placeId, isOpenCalendar.getTimeInMillis());
} catch (IllegalArgumentException e) {
    Log.e("PlaceIsOpen", "Error: " + e.getMessage());
    return;
}

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

placeTask.addOnSuccessListener(
        (response) -> {
            final boolean isOpen = Boolean.TRUE.equals(response.isOpen());
            binding.isOpenByIdResult.setText(
                    getString(R.string.is_open_by_id, String.valueOf(isOpen)));
            Log.d("PlaceIsOpen", "Is open by ID: " + isOpen);
        });
placeTask.addOnFailureListener(
        (exception) -> {
            binding.isOpenByIdResult.setText(
                    getString(R.string.is_open_by_id, "Error: " + exception.getMessage()));
            Log.e("PlaceIsOpen", "Error: " + exception.getMessage());
        });

      

L'esempio seguente mostra la chiamata di 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 = PlaceIdProvider.getRandomPlaceId()
// 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.DISPLAY_NAME,
)

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) {
        Log.e("PlaceIsOpen", "Error: " + e.message)
        return@addOnSuccessListener
    }
    val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(isOpenRequest)
    isOpenTask.addOnSuccessListener { isOpenResponse ->
        val isOpen = when (isOpenResponse.isOpen) {
            true -> getString(R.string.is_open)
            else -> getString(R.string.is_closed)
        }
        binding.isOpenByObjectResult.text = getString(
            R.string.is_open_by_object,
            place.displayName,
            isOpen,
        )
        Log.d("PlaceIsOpen", "Is open by object: $isOpen")
    }
    // ...
}
// ...

      

Java

@NonNull Calendar isOpenCalendar = Calendar.getInstance();
String placeId = PlaceIdProvider.getRandomPlaceId();
// 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.DISPLAY_NAME));

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) {
                Log.e("PlaceIsOpen", "Error: " + e.getMessage());
                return;
            }
            Task<IsOpenResponse> isOpenTask = placesClient.isOpen(isOpenRequest);

            isOpenTask.addOnSuccessListener(
                    (isOpenResponse) -> {
                        final boolean isOpen = Boolean.TRUE.equals(isOpenResponse.isOpen());
                        binding.isOpenByObjectResult.setText(
                                getString(
                                        R.string.is_open_by_object,
                                        place.getDisplayName(),
                                        String.valueOf(isOpen)));
                        Log.d("PlaceIsOpen", "Is open by object: " + isOpen);
                    });
            isOpenTask.addOnFailureListener(
                    (exception) -> { // also update the result text field
                        binding.isOpenByObjectResult.setText(
                                getString(
                                        R.string.is_open_by_object,
                                        place.getDisplayName(),
                                        "Error: " + exception.getMessage()));
                        Log.e("PlaceIsOpen", "Error: " + exception.getMessage());
                    });
        });
placeTask.addOnFailureListener(
        (exception) -> {
            binding.isOpenByObjectResult.setText("Error: " + exception.getMessage());
            Log.e("PlaceIsOpen", "Error: " + exception.getMessage());

      

Visualizza le attribuzioni nella tua app

Quando l'app mostra informazioni sui luoghi, incluse le recensioni, deve mostrare anche eventuali attribuzioni. Per saperne di più, consulta le attribuzioni.

Scopri di più sugli ID luogo

L'ID luogo utilizzato in Places SDK for Android (Legacy) è lo stesso identificatore utilizzato nell'API Places (Legacy). Ogni ID luogo può fare riferimento a un solo luogo, ma un singolo luogo può avere più di un ID luogo. Esistono altre circostanze che possono comportare l'assegnazione di un nuovo ID luogo a un luogo. Ad esempio, ciò può accadere se un'attività si trasferisce 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). Tieni presente, tuttavia, che la risposta potrebbe contenere un ID luogo diverso da quello della richiesta.

Per saperne di più, consulta la panoramica degli ID luogo.