Place Details

Sélectionnez une plate-forme: Android iOS JavaScript Services Web

Le SDK Places pour Android fournit à votre application des informations complètes sur les lieux, y compris leur nom et leur adresse, leur emplacement géographique spécifié sous forme de coordonnées de latitude/longitude, le type de lieu (boîte de nuit, animalerie, musée, etc.), etc. Pour accéder à ces informations pour un lieu spécifique, vous pouvez utiliser l'ID de lieu, qui est un identifiant stable qui identifie un lieu de manière unique.

Détails sur le lieu

L'objet Place fournit des informations sur un lieu spécifique. Vous pouvez obtenir un objet Place de différentes manières:

• Appelez PlacesClient.fetchPlace() : consultez le guide pour obtenir un lieu par ID.
• Appelez PlacesClient.findCurrentPlace() : consultez le guide pour obtenir le lieu actuel.
  Bien que PlacesClient.fetchPlace() soit compatible avec tous les champs de données de lieu, PlacesClient.findCurrentPlace() n'accepte qu'un sous-ensemble de champs de données de lieu. Pour obtenir la liste des champs NON compatibles avec findCurrentPlace(), consultez Compatibilité des champs avec le SDK Places pour Android.

Lorsque vous demandez un lieu, vous devez spécifier les données de lieu à renvoyer. Pour ce faire, transmettez une liste de valeurs Place.Field spécifiant les données à renvoyer. Cette liste est importante, car elle a une incidence sur le coût de chaque requête.

Étant donné que les résultats des données de lieu ne peuvent pas être vides, seuls les résultats de lieu contenant des données sont renvoyés (par exemple, si un lieu demandé ne comporte pas de photos, le champ photos ne sera pas présent dans le résultat).

L'exemple suivant transmet une liste de trois valeurs Place.Field pour spécifier les données renvoyées par une requête:

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 placeFields = Arrays.asList(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS);

Remarque : Les SDK Places pour Android et pour Android (nouveau) acceptent différents modèles de tarification. Cela signifie que le prix d'un appel dépend des champs que vous demandez et de la version du SDK que vous utilisez. Pour obtenir des informations détaillées sur la tarification des deux SDK, consultez Utilisation et facturation.

Accéder aux champs de données d'objets Place

Après avoir obtenu l'objet Place, utilisez ses méthodes pour accéder aux champs de données spécifiés dans la requête. Si le champ n'est pas spécifié dans l'objet Place, la méthode associée renvoie la valeur "null". Vous trouverez ci-dessous des exemples de méthodes disponibles. Pour obtenir la liste complète de toutes les méthodes, consultez la documentation de référence de l'API Place.

• getAddress() : adresse du lieu, dans un format lisible.
• getAddressComponents() : List des composants d'adresse pour ce lieu. Ces composants sont fournis dans le but d'extraire des informations structurées sur l'adresse d'un lieu, par exemple pour trouver la ville dans laquelle se trouve un lieu. N'utilisez pas ces composants pour la mise en forme des adresses. Appelez plutôt getAddress(), qui fournit une adresse formatée localisée.
• getId() : identifiant textuel du lieu. Pour en savoir plus sur les ID de lieu, consultez la suite de cette page.
• getLatLng() : emplacement géographique du lieu, spécifié sous forme de coordonnées de latitude et de longitude.
• getName() : nom du lieu.

• getOpeningHours() : OpeningHours du lieu. Appelez OpeningHours.getWeekdayText() pour renvoyer une liste de chaînes représentant les heures d'ouverture et de fermeture de chaque jour de la semaine. Appelez OpeningHours.getPeriods() pour renvoyer une liste d'objets period avec des informations plus détaillées équivalentes aux données fournies par getWeekdayText().

  Remarque : Si un lieu est toujours ouvert, la période est représentée par le dimanche à minuit, et la valeur closeEvent est nulle.

  L'objet Place contient également la méthode getCurrentOpeningHours(), qui renvoie les heures d'ouverture d'un lieu au cours des sept prochains jours, et getSecondaryOpeningHours() qui renvoie les heures d'ouverture secondaires d'un lieu au cours des sept jours suivants.

• isOpen() : valeur booléenne indiquant si l'établissement est actuellement ouvert. Si aucune heure n'est spécifiée, la valeur par défaut est maintenant. isOpen n'est renvoyé que si Place.Field.UTC_OFFSET et Place.Field.OPENING_HOURS sont disponibles. Pour garantir l'exactitude des résultats, renseignez les champs Place.Field.BUSINESS_STATUS et Place.Field.UTC_OFFSET dans votre requête de lieu d'origine. Si elle n'est pas demandée, il est supposé que l'établissement est opérationnel. Regardez cette vidéo pour découvrir comment utiliser isOpen avec Place Details.

  Remarque : Cette méthode est obsolète. Utilisez plutôt PlacesClient.isOpen(IsOpenRequest request). Pour en savoir plus, consultez Obtenir l'état d'ouverture.

Voici quelques exemples simples :

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

      

Accéder aux données de lieu ajoutées dans la version 3.3.0

Le SDK Places pour Android version 3.3.0 ajoute de nouvelles données à Place:

• Types de lieux: nouvelles valeurs de type associées à un lieu.
• Avis: jusqu'à cinq avis pour un lieu.
• Code de langue du nom: code de langue du nom d'un lieu.

Les sections suivantes décrivent comment accéder à ces nouvelles données.

Remarque : Le nouveau SDK n'est compatible qu'avec les nouvelles données Place en Java.

Accéder à de nouveaux types de lieux

Une ou plusieurs valeurs type peuvent être associées à chaque lieu. Le SDK Places pour Android version 3.3.0 ajoute de nombreuses nouvelles valeurs de type. Pour obtenir la liste complète, consultez Types de lieux étendus.

Dans le SDK Places pour Android 3.2.0 ou version antérieure, vous avez utilisé la méthode Place.getTypes() pour accéder aux valeurs de type associées à un lieu. Place.getTypes() renvoie une liste de types en tant que valeurs d'énumération définies par Place.Types.

La méthode Place.getTypes() est obsolète depuis la version 3.3.0 du SDK Places pour Android. Bien que vous puissiez continuer à l'utiliser pendant la période d'abandon, vous devez migrer vos applications pour utiliser Place.getPlaceTypes() à la place.

La méthode Place.getPlaceTypes() renvoie les valeurs de type sous forme de liste de valeurs de chaîne. Les valeurs renvoyées dépendent de votre version du SDK Places pour Android:

• SDK Places pour Android (Nouveau): renvoie les chaînes définies par les tables A et B affichées dans les types de lieux (nouveau), y compris tous les types de lieux ajoutés dans la version 3.3.0.
• SDK Places pour Android: renvoie les énumérations définies par Place.Types, qui n'inclut pas les nouveaux types ajoutés dans la version 3.3.0.

Pour connaître les principales différences entre les deux versions du SDK, consultez Choisir votre version de SDK.

Accéder aux avis sur les lieux

Le SDK Places pour Android (Nouveau) ajoute la classe Review, qui contient un avis sur un lieu. L'objet Place peut contenir jusqu'à cinq avis.

La classe Review peut également contenir une attribution et une attribution d'auteur. Si vous affichez l'avis dans votre application, vous devez également afficher toute mention d'attribution ou d'attribution d'auteur. Pour en savoir plus, consultez la section Afficher un avis.

Pour insérer des avis dans l'objet Place, vous devez:

1. Activez le nouveau SDK lorsque vous configurez votre projet Google Cloud.
2. Initialisez le nouveau SDK dans une activité ou un fragment.
3. Incluez Place.Field.REVIEWS dans la liste des champs de la requête de détails sur le lieu.
4. Appelez PlacesClient.fetchPlace(). Le champ "Avis" n'est pas compatible avec PlacesClient.findCurrentPlace().
5. Utilisez la méthode Place.getReviews() pour accéder au champ de données des avis dans l'objet Place.

Accéder au code de langue du nom du lieu

La méthode Place.getName() existante renvoie une chaîne de texte contenant le nom d'un lieu. Pour renseigner le nom du lieu dans l'objet Place, vous devez inclure Place.Field.NAME dans la liste des champs de la requête de détails sur le lieu.

L'objet Place contient désormais le code de langue de la chaîne "name". Pour renseigner l'objet Place avec le code de langue, vous devez:

1. Activez le nouveau SDK lorsque vous configurez votre projet Google Cloud.
2. Initialisez le nouveau SDK dans une activité ou un fragment.
3. Incluez Place.Field.NAME dans la liste des champs de la requête. Cette valeur configure la réponse pour inclure le nom du lieu et le code de langue dans l'objet Place.
4. Appelez PlacesClient.fetchPlace(). PlacesClient.findCurrentPlace() n'est pas compatible avec le champ de code de langue.
5. Utilisez la méthode Place.getNameLanguageCode() pour accéder au champ de code de langue dans l'objet Place.

Définir le code régional dans la version 3.3.0

Le SDK Places pour Android (Nouveau) ajoute le paramètre de requête de code régional à Place Details. Le code de région permet de mettre en forme la réponse, spécifié en tant que valeur de code CLDR à deux caractères. Ce paramètre peut également avoir un effet de biais sur les résultats de recherche. Il n'existe pas de valeur par défaut. Vous devez activer le nouveau SDK pour définir le code de région.

Si le nom du pays du champ d'adresse dans la réponse correspond au code de la région, ce dernier est omis de l'adresse.

La plupart des codes CLDR sont identiques aux codes ISO 3166-1, à quelques exceptions près. Par exemple, le ccTLD du Royaume-Uni est "uk" (.co.uk), tandis que son code ISO 3166-1 est "gb" (techniquement pour l'entité de "Royaume-Uni de Grande-Bretagne et d'Irlande du Nord"). Ce paramètre peut avoir une incidence sur les résultats en fonction de la loi applicable.

Obtenir un lieu par identifiant

Un ID de lieu est un identifiant texte qui identifie un lieu de façon unique. Dans le SDK Places pour Android, vous pouvez récupérer l'ID d'un lieu en appelant Place.getId(). Le service Place Autocomplete renvoie également un ID de lieu pour chaque lieu correspondant à la requête de recherche et au filtre fournis. Vous pouvez stocker l'ID de lieu et l'utiliser pour récupérer à nouveau l'objet Place ultérieurement.

Pour obtenir un lieu par ID, appelez PlacesClient.fetchPlace() en transmettant un FetchPlaceRequest.

L'API renvoie un élément FetchPlaceResponse dans un élément Task. Le FetchPlaceResponse contient un objet Place correspondant à l'ID de lieu fourni.

L'exemple de code suivant vous montre comment appeler fetchPlace() pour obtenir des détails sur le lieu spécifié.

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

      

Vous pouvez utiliser un CancellationToken pour tenter d'annuler une requête auprès de l'une des classes de requêtes (par exemple, FetchPlaceRequest). L'annulation est effectuée de la manière la plus optimale possible. Lorsqu'une demande d'annulation est envoyée, aucune réponse n'est renvoyée. L'émission d'un jeton d'annulation ne garantit PAS l'annulation d'une requête particulière, et elle peut vous être facturée même si aucune réponse n'est renvoyée.

Obtenir l'état d'ouverture

La méthode PlacesClient.isOpen(IsOpenRequest request) renvoie un objet IsOpenResponse indiquant si le lieu est actuellement ouvert à l'heure spécifiée dans l'appel.

Cette méthode utilise un seul argument de type IsOpenRequest contenant les éléments suivants:

• Un objet Place ou une chaîne spécifiant un ID de lieu.
  Remarque : L'objet Place doit contenir un ID de lieu valide.
• Valeur de temps facultative indiquant la durée en millisecondes à partir de 1970-01-01T00:00:00Z. Si aucune heure n'est spécifiée, la valeur par défaut est maintenant.

Cette méthode nécessite la présence des champs suivants dans l'objet Place:

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

Si ces champs ne sont pas fournis dans l'objet Place ou si vous transmettez un ID de lieu, la méthode utilise PlacesClient.fetchPlace() pour les récupérer. Pour en savoir plus sur la création d'un objet Place avec les champs nécessaires, consultez Place Details.

Remarque : Le SKU Basic Data de Places est facturé pour les appels à fetchPlace() pour Place.Field.UTC_OFFSET et Place.Field.BUSINESS_STATUS. Le SKU Contact Data de Places est facturé pour les appels à fetchPlace() pour Place.Field.CURRENT_OPENING_HOURS et Place.Field.OPENING_HOURS.

L'exemple suivant détermine si un établissement est actuellement ouvert. Dans cet exemple, vous ne transmettez l'ID de lieu qu'à 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());
// ...

      

L'exemple suivant montre comment appeler isOpen() lorsque vous transmettez un objet Place. L'objet Place doit contenir un ID de lieu valide:

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

      

Afficher les mentions dans votre application

Lorsque votre application affiche des informations sur des lieux, y compris des avis sur les lieux, elle doit également afficher les attributions. Pour en savoir plus, consultez la section Attributions.

Informations supplémentaires sur les identifiants de lieu

L'ID de lieu utilisé dans le SDK Places pour Android est le même que celui utilisé dans l'API Places. Chaque ID de lieu ne peut faire référence qu'à un seul lieu, mais un même lieu peut avoir plusieurs ID. Un lieu peut générer un nouvel ID de lieu dans d'autres circonstances. Cela peut se produire, par exemple, lorsqu'une entreprise déménage.

Lorsque vous demandez un lieu en spécifiant un ID de lieu, vous pouvez être sûr de recevoir toujours le même lieu dans la réponse (s'il existe toujours). Notez toutefois que la réponse peut contenir un ID de lieu différent de celui de votre requête.

Pour en savoir plus, consultez la présentation des ID de lieu.