La nouvelle génération du SDK Places pour iOS est désormais disponible avec le nouveau SDK Places pour iOS.

Cette page a été traduite par l'API Cloud Translation.

Place Details

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

Le SDK Places pour iOS fournit à votre application des informations détaillées sur les lieux, y compris leur nom et leur adresse, leur position géographique spécifiée en tant que coordonnées de latitude/longitude, leur type (par exemple, boîte de nuit, animalerie, 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.

Détails sur le lieu

La classe GMSPlace fournit des informations sur un lieu spécifique. Vous pouvez obtenir un objet GMSPlace de différentes manières:

Appelez GMSPlacesClient findPlaceLikelihoodsFromUserLocationWithPlaceFields:. Consultez le guide sur l'obtention du lieu actuel.
Appelez GMSPlacesClient fetchPlaceFromPlaceID: en transmettant un GMSPlaceField, un ID de lieu et une méthode de rappel. Pour les requêtes Place Details, si vous ne spécifiez pas au moins un champ avec une requête ou si vous omettez le paramètre fields d'une requête, TOUS les champs possibles seront renvoyés, et cela vous sera facturé en conséquence. Consultez le guide sur l'obtention d'un lieu par ID.

Avertissement:Si vous ne spécifiez pas au moins un champ avec une requête ou si vous omettez le paramètre fields d'une requête, TOUS les champs possibles seront renvoyés, et cela vous sera facturé en conséquence. Cela ne s'applique qu'aux requêtes Place Details.

Lorsque vous demandez un lieu, vous devez spécifier les types de données de lieu à renvoyer. Pour ce faire, transmettez un GMSPlaceField, en spécifiant les types de données à renvoyer. Il s'agit d'un point important, car il influe sur le coût de chaque requête.

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

L'exemple suivant transmet une liste de deux valeurs de champ pour spécifier les données renvoyées par une requête:

Swift

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

      // Specify the place data types to return.
      let fields: GMSPlaceField = GMSPlaceField(rawValue: UInt(GMSPlaceField.name.rawValue) |
      UInt(GMSPlaceField.placeID.rawValue))

Objective-C

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

      // Specify the place data types to return.
      GMSPlaceField fields = (GMSPlaceFieldName | GMSPlaceFieldPlaceID);

GMSPlaceFieldTakeout, GMSPlaceFieldDelivery, GMSPlaceFieldDineIn, GMSPlaceFieldCurbsidePickup, GMSPlaceFieldPhoneNumber, GMSPlaceFieldWebsite, GMSPlaceFieldOpeningHours et GMSPlaceFieldAddressComponents ne sont pas acceptés pour les objets de lieu GMSPlaceLikelihoodList.

En savoir plus sur les champs de lieu. Pour en savoir plus sur la facturation des requêtes de données de lieu, consultez Utilisation et facturation.

La classe GMSPlace peut contenir les données de lieu suivantes:

name : nom du lieu.
editorialSummary : fournit une description d'un lieu.
placeID : identifiant textuel du lieu. Pour en savoir plus sur les ID de lieu, consultez le reste de cette page.
coordinate : position géographique de l'établissement, spécifiée en termes de coordonnées de latitude et de longitude.
phoneNumber : numéro de téléphone du lieu, au format international.
formattedAddress : adresse lisible de cet établissement.
Bien souvent, cette adresse équivaut à l'adresse postale. Notez que certains pays, comme le Royaume-Uni, n'autorisent pas la distribution des vraies adresses postales en raison de restrictions de licence.

L'adresse formatée est composée d'un ou de plusieurs composants d'adresse logiques. Par exemple, l'adresse "111 8th Avenue, New York, NY" comprend les éléments suivants : "111" (le numéro de rue), "8th Avenue" (la route), "New York" (la ville) et "NY" (l'État américain).

N'analysez pas l'adresse formatée de manière programmatique. Utilisez plutôt les composants d'adresse individuels, que la réponse de l'API inclut en plus du champ d'adresse formaté.
openingHours : horaires d'ouverture de l'établissement (représentés par GMSOpeningHours). Appelez GMSOpeningHours.weekdayText pour obtenir une liste de chaînes localisées correspondant aux horaires d'ouverture quotidiens de la semaine. Appelez GMSOpeningHours.Periods pour renvoyer une liste de GMSPeriod avec des informations plus détaillées équivalentes aux données fournies par weekdayText. Remarque:Si un lieu est toujours ouvert, la période est représentée par le dimanche à minuit, et closeEvent est nul.
currentOpeningHours et secondaryOpeningHours : champs qui prennent en compte les jours fériés et les modifications temporaires de l'horaire d'un lieu.
addressComponents : tableau d'objets GMSAddressComponent représentant les composants de l'adresse d'un 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 il se trouve. N'utilisez pas ces composants pour le formatage des adresses. Utilisez plutôt la propriété formattedAddress, qui fournit une adresse formatée localisée.

Notez les informations suivantes concernant le tableau addressComponents:
- Le tableau de composants d'adresse peut contenir formattedAddress et des composants supplémentaires.
- Le tableau n'inclut pas nécessairement toutes les entités politiques contenant une adresse, à l'exception de celles incluses dans formattedAddress.
- Le format de la réponse ne sera peut-être pas le même d'une requête à l'autre. En particulier, le nombre d'addressComponents varie selon l'adresse demandée et peut changer au fil du temps pour la même adresse. Un composant peut changer de position dans le tableau. Le type du composant peut changer. Un composant particulier peut être manquant dans une réponse ultérieure.
userRatingsTotal : représente le nombre d'avis qui constituent la note du lieu.

La classe GMSPlace contient les fonctions membres suivantes:

isOpen indique si un lieu est ouvert à l'heure donnée, en fonction de openingHours et de UTCOffsetMinutes, ainsi que de la date et de l'heure actuelles.
isOpenAtDate calcule si un établissement est ouvert à une date donnée, en fonction de openingHours et UTCOffsetMinutes, ainsi que de la date et de l'heure actuelles.

Lorsque vous utilisez ces fonctions pour obtenir des heures et/ou des dates d'ouverture, la requête fetchPlaceFromPlaceID: ou findPlaceLikelihoodsFromUserLocationWithPlaceFields: d'origine doit spécifier les champs GMSPlaceFieldOpeningHours et GMSPlaceFieldUTCOffsetMinutes. Si l'un de ces champs est manquant, l'objet GMSPlace généré ne contient pas d'heures ni de dates d'ouverture, et l'appel renvoie GMSPlaceOpenStatusUnknown. Pour obtenir des résultats précis, demandez les champs GMSPlaceFieldBusinessStatus et GMSPlaceFieldUTCOffsetMinutes dans votre requête de lieu d'origine. Si elle n'est pas demandée, on suppose que l'établissement est opérationnel.

cette vidéo

isOpen

Obtenir des horaires exceptionnels

Les horaires d'ouverture habituels sont obtenus via openingHours, tandis que currentOpeningHours et secondaryOpeningHours permettent de modifier les horaires temporaires et les jours fériés. Si vous avez défini des horaires d'ouverture exceptionnels pour ces jours spéciaux, vous pouvez les filtrer et les présenter.

Swift

    func examineOpeningHours(place: GMSPlace) {

      // Check if the current opening hours contains a special day that has exceptional hours
      guard let currentOpeningHours = place.currentOpeningHours else { return }
      if let specialDays = currentOpeningHours.specialDays {
        guard !specialDays.isEmpty else { return }
        if let specialDay = specialDays.filter { $0.isExceptional }.first  {
          // Indicate exceptional hours
        }
      }

      // Check if current opening hours contains a truncated time period
      let periods = currentOpeningHours.periods

      if !periods.isEmpty {
        for period in periods {
          let open = period.open
          let close = period.close

          if let open = open {
            let date = open.date

            if open.isTruncated {
              // Indicate truncated time period
            }
          }
        }
      }

      // Check if the place's secondary opening hours indicate when delivery is available
      let secondaryOpeningHours = place.secondaryOpeningHours
      guard let hoursType = secondaryOpeningHours.first?.hoursType else {
      return
      }

      if (hoursType == GMSPlaceHoursTypeDelivery) {
        // Indicate hours where delivery is available
      }
  }

Objective-C

- (void)examineOpeningHours:(GMSPlace *) place {

    // Check if the current opening hours contains a special day that has exceptional hours
    GMSOpeningHours *currentOpeningHours = place.currentOpeningHours;
    if (currentOpeningHours != nil) {
      NSArray<GMSPlaceSpecialDay *> *specialDays = currentOpeningHours.specialDays;
      if ([specialDays count] != 0) {
        for (GMSPlaceSpecialDay *specialDay in specialDays) {
          NSDate *date = specialDay.date;
          if ([specialDay isExceptional]) {
            // Indicate exceptional hours
          }
        }
      }
    }

    // Check if current opening hours contains a truncated time period
    NSArray <GMSPeriod *> * periods = currentOpeningHours.periods;

    if ([periods count] != 0) {
      for (GMSPeriod * period in periods) {
        GMSTimeOfWeek *open = period.open;
        GMSTimeOfWeek *close = period.close;

        if (open) {
          if ([open isTruncated]) {
            // Indicate truncated time period
          }
        }
      }
    }

    // Check if the place's secondary opening hours indicate when delivery is available
    GMSOpeningHours *secondaryOpeningHours = place.secondaryOpeningHours;
    GMSPlaceHoursType hoursType = secondaryOpeningHours.getHoursType;

    if (hoursType == GMSPlaceHoursTypeDelivery) {
      // Indicate hours where delivery is available
    }
}

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 iOS, vous pouvez récupérer l'ID d'un lieu à partir d'un objet GMSPlace. Vous pouvez stocker l'ID de lieu et l'utiliser pour récupérer l'objet GMSPlace ultérieurement.

Pour obtenir un lieu par ID, appelez GMSPlacesClient fetchPlaceFromPlaceID: en transmettant les paramètres suivants:

Chaîne contenant un ID de lieu.
Un ou plusieurs GMSPlaceField, spécifiant les types de données à renvoyer.
Un jeton de session si l'appel est effectué pour conclure une requête de saisie semi-automatique. Sinon, transmettez "nil".
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 fields: GMSPlaceField = GMSPlaceField(rawValue: UInt(GMSPlaceField.name.rawValue) |
  UInt(GMSPlaceField.placeID.rawValue))!

placesClient?.fetchPlace(fromPlaceID: placeID, placeFields: fields, sessionToken: nil, callback: {
  (place: GMSPlace?, error: Error?) in
  if let error = error {
    print("An error occurred: \(error.localizedDescription)")
    return
  }
  if let place = place {
    self.lblName?.text = place.name
    print("The selected place is: \(place.name)")
  }
})

Objective-C

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

// Specify the place data types to return.
GMSPlaceField fields = (GMSPlaceFieldName | GMSPlaceFieldPlaceID);

[_placesClient fetchPlaceFromPlaceID:placeID placeFields:fields sessionToken:nil callback:^(GMSPlace * _Nullable place, NSError * _Nullable error) {
  if (error != nil) {
    NSLog(@"An error occurred %@", [error localizedDescription]);
    return;
  }
  if (place != nil) {
    NSLog(@"The selected place is: %@", [place name]);
  }
}];

Afficher les mentions dans votre application

Lorsque votre application affiche des informations obtenues à partir de GMSPlacesClient lookUpPlaceID:callback:, elle doit également afficher des attributions. Consultez la documentation sur les attributions.

Informations supplémentaires sur les identifiants 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 identifiant de lieu ne peut désigner qu'un seul lieu, mais un même lieu peut avoir plusieurs identifiants.

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 indiqué dans votre requête.

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