Le SDK Places pour iOS fournit à votre application des informations détaillées sur les lieux, y compris leur nom et leur adresse, l'emplacement géographique 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 sur un lieu spécifique, vous pouvez utiliser l'identifiant 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 pour obtenir le lieu actuel. - Appelez
GMSPlacesClient fetchPlaceFromPlaceID:
en transmettant unGMSPlaceField
, un ID de lieu et une méthode de rappel. Pour les requêtes Places Details, si vous ne spécifiez pas au moins un champ avec une requête ou si vous omettez le paramètrefields
d'une requête, TOUS les champs possibles seront renvoyés, et vous serez facturé en conséquence. Consultez le guide pour obtenir un lieu par ID.
Lorsque vous demandez un lieu, vous devez spécifier les types de données de lieu à renvoyer. Pour ce faire, transmettez un élément GMSPlaceField
en spécifiant les types de données à renvoyer. Il s'agit d'un élément important, car il aura une incidence sur le 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 ce type sont renvoyés (par exemple, si un lieu demandé n'a pas de photos, le champ photos
n'est pas présent dans le résultat).
L'exemple suivant transmet une liste de deux valeurs de champs 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);
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 simple d'un lieu.placeID
: identifiant textuel du lieu. Pour en savoir plus sur les ID de lieu, consultez le reste de cette page.coordinate
: emplacement géographique du lieu, spécifié sous la forme 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 du lieu (représentés parGMSOpeningHours
). AppelezGMSOpeningHours.weekdayText
pour obtenir la liste localisée des chaînes localisées des horaires d'ouverture de la semaine. AppelezGMSOpeningHours.Periods
pour renvoyer une liste deGMSPeriod
avec des informations plus détaillées équivalentes aux données fournies parweekdayText
. Remarque:Si un lieu est toujours ouvert, la période est représentée par le dimanche à minuit et la valeurcloseEvent
est nulle.currentOpeningHours
etsecondaryOpeningHours
: champs qui prennent en compte les modifications temporaires et temporaires des horaires pour un lieu donné.addressComponents
: tableau d'objetsGMSAddressComponent
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 en recherchant la ville dans laquelle se trouve le lieu. N'utilisez pas ces composants pour le formatage des adresses. Utilisez plutôt la propriétéformattedAddress
, qui fournit une adresse au format local.Notez les informations suivantes concernant le tableau
addressComponents
:- Le tableau de composants d'adresse peut contenir plus de composants que
formattedAddress
. - Le tableau n'inclut pas nécessairement toutes les entités politiques contenant une adresse, à l'exception de celles incluses dans
formattedAddress
. - Il n'est pas garanti que le format de la réponse reste le même entre les requêtes. En particulier, le nombre de
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.
- Le tableau de composants d'adresse peut contenir plus de composants que
userRatingsTotal
: représente le nombre d'avis formant la note du lieu.
La classe GMSPlace
contient les fonctions de membre suivantes:
-
isOpen
calcule si un lieu est ouvert à un moment donné, en fonction deopeningHours
etUTCOffsetMinutes
, et de la date et l'heure actuelles. isOpenAtDate
calcule si un lieu est ouvert à une date donnée en fonction deopeningHours
etUTCOffsetMinutes
, 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 à la fois les champs GMSPlaceFieldOpeningHours
et GMSPlaceFieldUTCOffsetMinutes
. Si l'un de ces champs est manquant, l'objet GMSPlace
obtenu ne contiendra pas de date et heure d'ouverture, et l'appel renverra GMSPlaceOpenStatusUnknown
. Pour garantir l'exactitude des résultats, demandez les champs GMSPlaceFieldBusinessStatus
et GMSPlaceFieldUTCOffsetMinutes
dans votre requête de lieu d'origine. Sinon, nous supposons que l'établissement est opérationnel.
isOpen
avec Place Details.
Horaires exceptionnels
Bien que les horaires d'ouverture standards soient obtenus viaopeningHours
, currentOpeningHours
et secondaryOpeningHours
permettent de modifier les horaires des jours fériés et des horaires temporaires.
Vous pouvez filtrer les horaires d'ouverture exceptionnels de ces jours particuliers et les afficher, le cas échéant.
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 à nouveau l'objet GMSPlace
.
Pour obtenir un lieu par ID, appelez GMSPlacesClient
fetchPlaceFromPlaceID:
en transmettant les paramètres suivants:
- Chaîne contenant un ID de lieu.
- Une ou plusieurs
GMSPlaceField
, en spécifiant les types de données à renvoyer. - Jeton de session si l'appel est effectué pour terminer 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 les attributions.
Consultez la documentation sur les attributions.
Informations supplémentaires sur les identifiants de lieu
L'identifiant de lieu utilisé dans le SDK Places pour iOS est le même que celui utilisé dans l'API Places, le SDK Places pour Android et les 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.
Dans certains cas, un même ID peut être attribué à un 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.
Pour en savoir plus, consultez la présentation des ID de lieu.