Place Details (nouveau)

Sélectionnez la plate-forme : Android iOS JavaScript Web Service
Développeurs de l'Espace économique européen (EEE)

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

Obtenir des informations sur un lieu

La classe GMSPlace contient des informations sur un lieu spécifique, y compris tous les champs de données affichés dans Champs de données de lieu (nouvelle génération). Obtenez un GMSPlace objet en appelant GMSPlacesClient fetchPlaceWithRequest:, en transmettant un GMSFetchPlaceRequest objet et une méthode de rappel de type GMSPlaceResultCallback.

L'objet GMSFetchPlaceRequest spécifie les éléments suivants :

  • (Obligatoire) L'ID de lieu, un identifiant unique pour un lieu dans la base de données Google Places et sur Google Maps.
  • (Obligatoire) La liste des champs à renvoyer dans l'objet GMSPlace, également appelé le masque de champ, tel que défini par GMSPlaceProperty. Si vous ne spécifiez pas au moins un champ dans la liste de champs ou si vous omettez la liste de champs, l'appel renvoie une erreur.
  • (Facultatif) Le code de région utilisé pour mettre en forme la réponse.
  • (Facultatif) Le jeton de session utilisé pour mettre fin à une session Autocomplete (nouvelle génération).

Envoyer une requête Place Details

Cet exemple obtient un lieu par ID en transmettant les paramètres suivants :

  • L'ID de lieu ChIJV4k8_9UodTERU5KXbkYpSYs.
  • Une liste de champs spécifiant de renvoyer le nom du lieu et l'URL du site Web.
  • Un GMSPlaceResultCallback pour gérer le résultat.

L'API appelle la méthode de rappel spécifiée, en transmettant un GMSPlace objet. Si le lieu est introuvable, l'objet GMSPlace est nul.

SDK Places Swift

// A hotel in Saigon with an attribution.
let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs"
let fetchPlaceRequest = FetchPlaceRequest(
  placeID: placeID,
  placeProperties: [.name, .website]
)
switch await placesClient.fetchPlace(with: fetchPlaceRequest) {
case .success(let place):
  // Handle place
case .failure(let placesError):
  // Handle error
}

Swift

// A hotel in Saigon with an attribution.
let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs"

// Specify the place data types to return.
let myProperties = [GMSPlaceProperty.name, GMSPlaceProperty.website].map {$0.rawValue}

// Create the GMSFetchPlaceRequest object.
let fetchPlaceRequest = GMSFetchPlaceRequest(placeID: placeID, placeProperties: myProperties, sessionToken: nil)

client.fetchPlace(with: fetchPlaceRequest, callback: {
  (place: GMSPlace?, error: Error?) in
  guard let place, error == nil else { return }
  print("Place found: \(String(describing: place.name))")
})

Objective-C

// A hotel in Saigon with an attribution.
NSString *placeID = @"ChIJV4k8_9UodTERU5KXbkYpSYs";

// Specify the place data types to return.
NSArray<NSString *> *myProperties = @[GMSPlacePropertyName, GMSPlacePropertyWebsite];

// Create the GMSFetchPlaceRequest object.
GMSFetchPlaceRequest *fetchPlaceRequest = [[GMSFetchPlaceRequest alloc] initWithPlaceID:placeID placeProperties: myProperties sessionToken:nil];

[placesClient fetchPlaceWithRequest: fetchPlaceRequest callback: ^(GMSPlace *_Nullable place, NSError *_Nullable error) {
    if (error != nil) {
      NSLog(@"An error occurred %@", [error localizedDescription]);
      return;
    } else {
    NSLog(@"Place Found: %@", place.name);
    NSLog(@"The place URL: %@", place.website);
  }
}];

Réponse Place Details

Place Details renvoie un GMSPlace objet contenant des informations sur le lieu. Seuls les champs spécifiés dans la liste de champs sont renseignés dans l'objet GMSPlace.

Obtenir l'état d'ouverture

L'objet GMSPlacesClient contient une fonction membre appelée isOpenWithRequest (isOpenRequest dans Swift et isPlaceOpenRequest dans GooglePlacesSwift) qui renvoie une réponse indiquant si le lieu est actuellement ouvert, en fonction de l'heure spécifiée dans l'appel.

Cette méthode utilise un seul argument de type GMSPlaceIsOpenWithRequest qui contient les éléments suivants :

La méthode GMSPlaceIsOpenWithRequest nécessite que les champs suivants soient définis dans l'objet GMSPlace :

  • GMSPlacePropertyUTCOffsetMinutes
  • GMSPlacePropertyBusinessStatus
  • GMSPlacePropertyOpeningHours
  • GMSPlacePropertyCurrentOpeningHours
  • GMSPlacePropertySecondaryOpeningHours

Si ces champs ne sont pas fournis dans l'objet Place ou si vous transmettez un ID de lieu, la méthode utilise GMSPlacesClient GMSFetchPlaceRequest: pour les récupérer.

Réponse isOpenWithRequest

isOpenWithRequest renvoie un objet GMSPlaceIsOpenResponse contenant une valeur booléenne nommée status qui indique si l'établissement est ouvert, fermé ou si l'état est inconnu.

Langue Valeur si ouvert Valeur si fermé Valeur si l'état est inconnu
Places Swift true false nil
Swift .open .closed .unknown
Objective-C GMSPlaceOpenStatusOpen GMSPlaceOpenStatusClosed GMSPlaceOpenStatusUnknown

Facturation pour isOpenWithRequest

  • Les champs GMSPlacePropertyUTCOffsetMinutes et GMSPlacePropertyBusinessStatus sont facturés sous le SKU Données de base. Le reste des horaires d'ouverture est facturé sous le SKU Place Details Enterprise.
  • Si votre objet GMSPlace comporte déjà ces champs à partir d'une requête précédente, vous ne serez pas facturé à nouveau.

Exemple : Envoyer une requête GMSPlaceIsOpenWithRequest

L'exemple suivant montre comment initialiser un GMSPlaceIsOpenWithRequest dans un objet GMSPlace existant.

SDK Places Swift

        let isOpenRequest = IsPlaceOpenRequest(place: place)
        switch await placesClient.isPlaceOpen(with: isOpenRequest) {
          case .success(let isOpenResponse):
            switch isOpenResponse.status {
              case true:
                // Handle open
              case false:
                // Handle closed
              case nil:
                // Handle unknown
          case .failure(let placesError):
            // Handle error
        }

Swift

    let isOpenRequest = GMSPlaceIsOpenRequest(place: place, date: nil)
      GMSPlacesClient.shared().isOpen(with: isOpenRequest) { response, error in
        if let error = error {
          // Handle Error
        }
        switch response.status {
          case .open:
            // Handle open
          case .closed:
            // Handle closed
          case .unknown:
            // Handle unknown
        }
      }

Objective-C

          GMSPlaceIsOpenRequest *isOpenRequest = [[GMSPlaceIsOpenRequest alloc] initWithPlace:place date:nil];

          [[GMSPlacesClient sharedClient] isOpenWithRequest:isOpenRequest callback:^(GMSPlaceIsOpenResponse response, NSError *_Nullable error) {
            if (error) {
              // Handle error
            }

            switch (response.status) {
              case GMSPlaceOpenStatusOpen:
                // Handle open
              case GMSPlaceOpenStatusClosed:
                // Handle closed
              case GMSPlaceOpenStatusUnknown:
                // Handle unknown
            }
          }];

Paramètres obligatoires

Utilisez l'objet GMSFetchPlaceRequest pour spécifier les paramètres obligatoires.

ID de lieu

L'ID de lieu utilisé dans le SDK Places pour iOS est le même identifiant que celui utilisé dans l'API Places, le SDK Places pour Android et d'autres API Google. Chaque ID de lieu ne peut faire référence qu'à un seul lieu, mais un même lieu peut avoir plusieurs ID de lieu.

Dans certaines circonstances, un lieu peut recevoir un nouvel ID de lieu. Par exemple, lorsqu'un professionnel déménage.

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

Liste de champs

Lorsque vous demandez des informations sur un lieu, vous devez spécifier les données à renvoyer dans l'objet GMSPlace pour le lieu en tant que masque de champ. Pour définir le masque de champ, transmettez un tableau de valeurs de GMSPlaceProperty à l'objet GMSFetchPlaceRequest. Le masquage de champ est une bonne pratique à appliquer pour vous assurer de ne pas demander de données inutiles. Vous pourrez ainsi réduire le temps de traitement et les frais facturés.

Spécifiez un ou plusieurs des champs suivants :

  • Les champs suivants déclenchent le SKU Place Details Essentials ID Only :

    GMSPlacePropertyPlaceID
    GMSPlacePropertyPhotos

    Pour obtenir la liste complète des champs et des SKU associés, consultez Champs de données de lieu (nouvelle génération).

  • Les champs suivants déclenchent le SKU Place Details Essentials :

    GMSPlacePropertyAddressComponents
    GMSPlacePropertyFormattedAddress
    GMSPlacePropertyCoordinate
    GMSPlacePropertyPlusCode
    GMSPlacePropertyTypes
    GMSPlacePropertyViewport

    Pour obtenir la liste complète des champs et des SKU associés, consultez Champs de données de lieu (nouvelle génération).

  • Les champs suivants déclenchent le SKU Place Details Pro :

    GMSPlacePropertyBusinessStatus
    GMSPlacePropertyIconBackgroundColor
    GMSPlacePropertyIconImageURL
    GMSPlacePropertyName
    GMSPlacePropertyUTCOffsetMinutes
    GMSPlacePropertyWheelchairAccessibleEntrance

    Pour obtenir la liste complète des champs et des SKU associés, consultez Champs de données de lieu (nouvelle génération).

  • Les champs suivants déclenchent le SKU Place Details Pro :

    GMSPlacePropertyCurrentOpeningHours
    GMSPlacePropertySecondaryOpeningHours
    GMSPlacePropertyPhoneNumber
    GMSPlacePropertyPriceLevel
    GMSPlacePropertyRating
    GMSPlacePropertyOpeningHours
    GMSPlacePropertyUserRatingsTotal
    GMSPlacePropertyWebsite

    Pour obtenir la liste complète des champs et des SKU associés, consultez Champs de données de lieu (nouvelle génération).

  • Les champs suivants déclenchent le SKU Place Details Enterprise :

    GMSPlacePropertyCurbsidePickup
    GMSPlacePropertyDelivery
    GMSPlacePropertyDineIn
    GMSPlacePropertyEditorialSummary
    GMSPlacePropertyReservable
    GMSPlacePropertyReviews
    GMSPlacePropertyServesBeer
    GMSPlacePropertyServesBreakfast
    GMSPlacePropertyServesBrunch
    GMSPlacePropertyServesDinner
    GMSPlacePropertyServesLunch
    GMSPlacePropertyServesVegetarianFood
    GMSPlacePropertyServesWine
    GMSPlacePropertyTakeout

    Pour obtenir la liste complète des champs et des SKU associés, consultez Champs de données de lieu (nouvelle génération).

L'exemple suivant transmet une liste de deux valeurs de champ pour spécifier que l'objet GMSPlace renvoyé par une requête contient les champs name et placeID :

SDK Places Swift

// Specify the place data types to return.
let fields: [PlaceProperty] = [.placeID, .displayName]

Swift

// Specify the place data types to return.
let fields: [GMSPlaceProperty] = [.placeID, .name]

Objective-C

// Specify the place data types to return.
NSArray<GMSPlaceProperty *> *fields = @[GMSPlacePropertyPlaceID, GMSPlacePropertyName];

Paramètres facultatifs

Utilisez l'objet GMSFetchPlaceRequest pour spécifier les paramètres facultatifs.

regionCode

Code de région utilisé pour mettre en forme la réponse, spécifié sous la forme d'une 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.

Si le nom du pays du champ d'adresse dans la réponse correspond au code de région, le code pays 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é "Royaume-Uni de Grande-Bretagne et d'Irlande du Nord"). Le paramètre peut affecter les résultats en fonction de la loi applicable.

sessionToken

Les jetons de session sont des chaînes générées par l'utilisateur qui suivent les appels Autocomplete (nouvelle génération) en tant que "sessions". Autocomplete (nouvelle génération) utilise des jetons de session pour regrouper les phases de requête et de sélection de lieu d'une recherche de saisie semi-automatique d'un utilisateur dans une session distincte à des fins de facturation. Les jetons de session sont transmis aux appels Place Details (nouvelle génération) qui suivent les appels Autocomplete (nouvelle génération). Pour en savoir plus, consultez Jetons de session.

Afficher les mentions dans votre application

Lorsque votre application affiche des informations obtenues à partir de GMSPlacesClient, telles que des photos et des avis, elle doit également afficher les mentions requises.

Par exemple, la propriété reviews de l'objet GMSPlacesClient contient un tableau de cinq GMSPlaceReview objets au maximum. Chaque objet GMSPlaceReview peut contenir des mentions et des mentions d'auteur. Si vous affichez l'avis dans votre application, vous devez également afficher toute mention ou mention d'auteur.

Pour en savoir plus, consultez la documentation sur les mentions.