Place Details (nouveau)

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

Le SDK Places pour iOS (nouveau) fournit à votre application des informations détaillées sur les lieux, y compris leur nom et leur adresse, leur emplacement géographique spécifié en tant que coordonnées de latitude/longitude, le type de lieu (par exemple, un club de nuit, une animalerie ou un musée), etc. Pour accéder à ces informations pour un lieu spécifique, vous pouvez utiliser l'ID de lieu, un identifiant stable qui identifie un lieu de manière unique.

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 (nouveaux). Obtenez un objet GMSPlace en appelant GMSPlacesClient fetchPlaceWithRequest:, en transmettant un objet GMSFetchPlaceRequest et une méthode de rappel de type GMSPlaceResultCallback.

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

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

Envoyer une requête Place Details

Cet exemple récupère un lieu par ID, en transmettant les paramètres suivants:

  • ID de lieu de ChIJV4k8_9UodTERU5KXbkYpSYs.
  • 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 objet GMSPlace. Si le lieu est introuvable, l'objet GMSPlace est nul.

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

SDK Places Swift pour iOS (bêta)

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

Réponse Place Details

Place Details renvoie un objet GMSPlace contenant des informations sur le lieu. Seuls les champs spécifiés dans la liste des 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 l'établissement est actuellement ouvert, en fonction de l'heure spécifiée dans l'appel.

Cette méthode accepte un seul argument de type GMSPlaceIsOpenWithRequest qui contient:

  • Un objet GMSPlace ou une chaîne spécifiant un ID de lieu. Pour en savoir plus sur la création de l'objet Place avec les champs nécessaires, consultez Détails du lieu.
  • Objet NSDate (Objective-C) ou Date (Swift) facultatif spécifiant l'heure que vous souhaitez vérifier. Si aucune heure n'est spécifiée, la valeur par défaut est l'heure actuelle.
  • Une méthode GMSPlaceOpenStatusResponseCallback pour gérer la réponse.
    • >

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 son état est inconnu.

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

Facturation pour isOpenWithRequest

  • Les champs GMSPlacePropertyUTCOffsetMinutes et GMSPlacePropertyBusinessStatus sont facturés sous le SKU Data Basic. Le reste des heures d'ouverture est facturé sous le code SKU Place Details (Advanced).
  • Si ces champs figurent déjà dans votre objet GMSPlace à la suite d'une demande 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.

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
            }
          }];

GooglePlacesSwift

          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
          }

Paramètres obligatoires

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

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.

Il existe des cas où 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 (s'il existe toujours). Notez toutefois que la réponse peut contenir un ID de lieu différent de celui de votre requête.

Liste des 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 (ID Only):

    GMSPlacePropertyPlaceID, GMSPlacePropertyName, GMSPlacePropertyPhotos

  • Les champs suivants déclenchent le SKU Place Details (Location Only):

    GMSPlacePropertyAddressComponents, GMSPlacePropertyFormattedAddress, GMSPlacePropertyCoordinate, GMSPlacePropertyPlusCode, GMSPlacePropertyTypes, GMSPlacePropertyViewport

  • Les champs suivants déclenchent le SKU Place Details (Basic):

    GMSPlacePropertyBusinessStatus, GMSPlacePropertyIconBackgroundColor, GMSPlacePropertyIconImageURL, GMSPlacePropertyUTCOffsetMinutes, GMSPlacePropertyWheelchairAccessibleEntrance

  • Les champs suivants déclenchent le SKU Place Details (Advanced):

    GMSPlacePropertyCurrentOpeningHours, GMSPlacePropertySecondaryOpeningHours, GMSPlacePropertyPhoneNumber, GMSPlacePropertyPriceLevel, GMSPlacePropertyRating, GMSPlacePropertyOpeningHours, GMSPlacePropertyUserRatingsTotal, GMSPlacePropertyWebsite

  • Les champs suivants déclenchent le SKU Place Details (Preferred):

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

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:

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];

SDK Places Swift pour iOS (bêta)

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

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 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 avoir une incidence sur les résultats en fonction de la législation applicable.

sessionToken

Les jetons de session sont des chaînes générées par l'utilisateur qui suivent les appels Autocomplete (Nouveau) en tant que "sessions". La saisie semi-automatique (nouvelle) 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 (New) qui suivent les appels Autocomplete (New). Pour en savoir plus, consultez la section 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 attributions requises.

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

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