Place Details

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

Le SDK Places pour Android fournit à votre application des informations détaillées sur un lieu, comme son nom et son adresse, son emplacement l'emplacement spécifié en tant que coordonnées de latitude/longitude, le type de lieu (boîte de nuit, animalerie, musée, etc.). Pour accéder à ces informations un lieu spécifique, vous pouvez utiliser l'identifiant de lieu, un identifiant stable qui identifie un lieu.

Détails sur le lieu

La Place fournit des informations sur un lieu spécifique. Vous pouvez obtenir Place de la manière suivante:

Lorsque vous demandez un lieu, vous devez spécifier les données de lieu à renvoyer. Pour ce faire, transmettez une liste de Place.Field spécifiant les données à renvoyer. Cette liste est un élément important à prendre en compte, car elle affecte coût de chaque requête.

Étant donné que les résultats de données de lieu ne peuvent pas être vides, seuls les résultats de lieu contenant des données sont renvoyé (par exemple, si le lieu demandé ne comporte aucune photo, 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<Place.Field> placeFields = Arrays.asList(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS);

Accéder aux champs de données des objets Place

Une fois que vous avez obtenu l'objet Place, utilisez ses méthodes pour accéder à champs de données spécifiés dans la requête. Si le champ n'est pas présent dans l'objet Place, la méthode associée renvoie la valeur "null". Vous trouverez ci-dessous quelques exemples de méthodes disponibles. Pour obtenir la liste complète des méthodes, consultez la Place Documentation de référence de l'API.

  • getAddress() : adresse du lieu, lisible par l'humain .
  • getAddressComponents() – A List de composants d'adresse pour ce lieu. Ces composants sont fournis vise à extraire des informations structurées sur l'adresse d'un lieu, par exemple pour trouver la ville dans laquelle un lieu est situé. Ne les utilisez pas. des composants pour le formatage des adresses ; Appelez plutôt getAddress(). qui fournit une adresse formatée localisée.
  • getId() : identifiant textuel du lieu. Lue plus d'informations sur les ID de lieu dans la suite de cette page.
  • getLatLng() : emplacement géographique du lieu. spécifiée en tant que coordonnées de latitude et de longitude.
  • getName() : nom du lieu.

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

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

  • isOpen() : booléen indiquant si le lieu est actuellement ouvert. Si aucune heure n'est spécifiée, la valeur par défaut est "now". isOpen n'est renvoyé que si Place.Field.UTC_OFFSET et Place.Field.OPENING_HOURS sont disponibles. Pour garantir la précision les résultats, demandez les Place.Field.BUSINESS_STATUS et Place.Field.UTC_OFFSET champs dans votre requête de lieu initiale. S'il n'est pas demandé, nous partons du principe que l'entreprise est opérationnelle. Regardez cette vidéo pour découvrir comment utiliser isOpen avec Place Details.

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

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'identifiant d'un lieu en appelant Place.getId() La Service Place Autocomplete renvoie également un identifiant pour chaque lieu correspondant à la requête de recherche fournie. et filtrer. Vous pouvez stocker l'ID de lieu et l'utiliser pour récupérer Place ultérieurement.

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

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

L'exemple de code suivant montre comment appeler fetchPlace() pour : obtenir les détails du 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.
    }
});

Obtenir l'état d'ouverture

PlacesClient.isOpen(IsOpenRequest request) renvoie un objet IsOpenResponse indiquant si le lieu est actuellement ouvert en fonction de l'heure spécifiée dans l'appel.

Cette méthode accepte un seul argument de type IsOpenRequest, qui contient les éléments suivants:

  • Un Place ou une chaîne spécifiant un ID de lieu.
  • Valeur de temps facultative spécifiant le temps en millisecondes depuis 1970-01-01T00:00:00Z. Si aucune heure n'est spécifiée, la valeur par défaut est "now".

Cette méthode nécessite que les champs suivants existent 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 de l'objet Place avec les champs nécessaires, consultez Place Details.

L'exemple suivant détermine si un lieu est actuellement ouvert. Dans cet exemple, vous ne transmettez l'ID de lieu vers 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(), où 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, elle doit également afficher toute attribution. Pour en savoir plus, consultez attributions.

Informations supplémentaires sur les identifiants de lieu

L'identifiant de lieu utilisé dans le SDK Places pour Android est le même telles qu'elles sont utilisées dans l'API Places. Chaque identifiant de lieu ne peut faire référence qu'à un seul lieu, mais un seul peut en contenir plusieurs. plusieurs ID de lieu. Dans d'autres circonstances, un lieu peut obtenir un nouvel ID de lieu. Cela peut se produire, par exemple, si une entreprise déménage l'emplacement.

Lorsque vous demandez un lieu en spécifiant un ID de lieu, vous êtes sûr que vous recevrez toujours la même réponse au même endroit (si le lieu est toujours . Notez toutefois que la réponse peut contenir un ID de lieu différente de celle de votre demande.

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