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

Nearby Search (nouveau)

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

Développeurs de l'Espace économique européen (EEE)

Une requête Nearby Search (nouvelle version) prend en entrée la région à rechercher, spécifiée sous la forme d'un cercle défini par les coordonnées de latitude et de longitude du point central du cercle et le rayon en mètres. La requête renvoie une liste de lieux correspondants, chacun représenté par un objet GMSPlace, dans la zone de recherche spécifiée.

Par défaut, la réponse contient des lieux de tous types dans la zone de recherche. Vous pouvez éventuellement filtrer la réponse en spécifiant une liste de types de lieux à inclure ou à exclure explicitement de la réponse. Par exemple, vous pouvez spécifier d'inclure uniquement les lieux de type "restaurant", "boulangerie" et "café" dans la réponse, ou d'exclure tous les lieux de type "école".

Requêtes Nearby Search (nouveau)

Effectuez une requête Nearby Search en appelant GMSPlacesClient searchNearbyWithRequest:, en transmettant un objet GMSPlaceSearchNearbyRequest qui définit les paramètres de la requête et une méthode de rappel de type GMSPlaceSearchNearbyResultCallback pour gérer la réponse.

L'objet GMSPlaceSearchNearbyRequest spécifie tous les paramètres obligatoires et facultatifs de la requête. Les paramètres requis incluent :

Liste des champs à renvoyer dans l'objet GMSPlace, également appelée masque de champ, telle que définie 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.
La restriction d'emplacement, c'est-à-dire le cercle définissant la zone de recherche.

Cet exemple de requête Nearby Search indique que les objets GMSPlace de la réponse contiennent le nom du lieu (GMSPlacePropertyName) et les coordonnées du lieu (GMSPlacePropertyCoordinate) pour chaque objet GMSPlace dans les résultats de recherche. Il filtre également la réponse pour ne renvoyer que les lieux de type "restaurant" et "café".

SDK Places Swift

let restriction = CircularCoordinateRegion(center: CLLocationCoordinate2DMake(37.7937, -122.3965), radius: 500)
let searchNearbyRequest = SearchNearbyRequest(
  locationRestriction: restriction,
  placeProperties: [ .name, .coordinate],
  includedTypes: [ .restaurant, .cafe ],
)
switch await placesClient.searchNearby(with: searchNearbyRequest) {
case .success(let places):
  // Handle places
case .failure(let placesError):
  // Handle error
}

Swift

// Array to hold the places in the response
var placeResults: [GMSPlace] = []

// Define the search area as a 500 meter diameter circle in San Francisco, CA.
let circularLocationRestriction = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(37.7937, -122.3965), 500)

// Specify the fields to return in the GMSPlace object for each place in the response.
let placeProperties = [GMSPlaceProperty.name, GMSPlaceProperty.coordinate].map {$0.rawValue}

// Create the GMSPlaceSearchNearbyRequest, specifying the search area and GMSPlace fields to return.
var request = GMSPlaceSearchNearbyRequest(locationRestriction: circularLocationRestriction, placeProperties: placeProperties)
let includedTypes = ["restaurant", "cafe"]
request.includedTypes = includedTypes

let callback: GMSPlaceSearchNearbyResultCallback = { [weak self] results, error in
  guard let self, error == nil else {
    if let error {
      print(error.localizedDescription)
    }
    return
  }
  guard let results = results as? [GMSPlace] else {
    return
  }
  placeResults = results
}

GMSPlacesClient.shared().searchNearby(with: request, callback: callback)

Objective-C

// Array to hold the places in the response
_placeResults = [NSArray array];

// Define the search area as a 500 meter diameter circle in San Francisco, CA.
id<GMSPlaceLocationRestriction> circularLocation = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(37.7937, -122.3965), 500);

// Create the GMSPlaceSearchNearbyRequest, specifying the search area and GMSPlace fields to return.
GMSPlaceSearchNearbyRequest *request = [[GMSPlaceSearchNearbyRequest alloc]
  initWithLocationRestriction:circularLocation
              placeProperties:@[ GMSPlacePropertyName, GMSPlacePropertyCoordinate ]];

// Set the place types to filter on.
NSArray<NSString *> *includedTypes = @[ @"restaurant", @"cafe" ];
request.includedTypes = [[NSMutableArray alloc] initWithArray:includedTypes];

[_placesClient searchNearbyWithRequest:request
  callback:^(NSArray<GMSPlace *> *_Nullable places, NSError *_Nullable error) {
    if (error != nil) {
      NSLog(@"An error occurred %@", [error localizedDescription]);
      return;
    } else {
        // Get list of places.
        _placeResults = places;
    }
  }
];

Réponses Nearby Search

L'API Nearby Search renvoie un tableau de correspondances sous la forme d'objets GMSPlace, avec un objet GMSPlace par lieu correspondant.

Remarque : Les champs de l'objet GMSPlace de la réponse ne peuvent pas être vides. Par exemple, si la liste des champs inclut GMSPlacePropertyPhotos pour demander le champ photos dans la réponse et que le champ photos de la réponse est vide, il est omis de l'objet GMSPlace de la réponse.

Obtenir l'état d'ouverture

L'objet GMSPlacesClient contient une fonction membre appelée isOpenWithRequest (isOpenRequest en 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.

Remarque : Les fonctions GMSPlace isOpen: et GMSPlace isOpenAtDate: obsolètes peuvent être inexactes et ne sont pas destinées à être utilisées avec l'API Places (nouveau).

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

Objet GMSPlace ou 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.

Remarque : L'objet Place doit contenir un ID de lieu valide.
Objet NSDate (Obj-C) ou Date (Swift) facultatif spécifiant l'heure à vérifier. Si aucune heure n'est spécifiée, la valeur par défaut est l'heure actuelle.
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.

`isOpenWithRequest` réponse

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 la porte est fermée	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 Basic Data. Le reste des horaires d'ouverture est facturé sous le SKU Enterprise Place Details.
Si votre objet GMSPlace possède déjà ces champs à la suite d'une demande précédente, vous ne serez pas facturé à nouveau.
Avertissement : Si votre objet GMSPlace ne comporte pas ces champs, le SKU Basic Data vous sera facturé une nouvelle fois. Le reste des horaires d'ouverture est facturé sous le SKU Enterprise Place Details. Si votre projet utilise isOpenWithRequest, nous vous recommandons de vous assurer de récupérer les détails du lieu nécessaires.

Exemple : effectuer 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 GMSPlaceSearchNearbyRequest pour spécifier les paramètres requis pour la recherche.

Liste des champs

Lorsque vous demandez des détails sur un lieu, vous devez spécifier les données à renvoyer dans l'objet GMSPlace pour le lieu sous forme de masque de champ. Pour définir le masque de champ, transmettez un tableau de valeurs de GMSPlaceProperty à l'objet GMSPlaceSearchNearbyRequest. 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 Nearby Search Pro :
  
  GMSPlacePropertyAddressComponents
  GMSPlacePropertyBusinessStatus
  GMSPlacePropertyCoordinate
  GMSPlacePropertyFormattedAddress
  GMSPlacePropertyName
  GMSPlacePropertyIconBackgroundColor
  GMSPlacePropertyIconImageURL
  GMSPlacePropertyPhotos
  GMSPlacePropertyPlaceID
  GMSPlacePropertyPlusCode
  GMSPlacePropertyTypes
  GMSPlacePropertyUTCOffsetMinutes
  GMSPlacePropertyViewport
  GMSPlacePropertyWheelchairAccessibleEntrance
- Les champs suivants déclenchent le SKU Nearby Search Enterprise :
  
  GMSPlacePropertyCurrentOpeningHours
  GMSPlacePropertySecondaryOpeningHours
  GMSPlacePropertyPhoneNumber
  GMSPlacePropertyPriceLevel
  GMSPlacePropertyRating
  GMSPlacePropertyOpeningHours
  GMSPlacePropertyUserRatingsTotal
  GMSPlacePropertyWebsite
- Les champs suivants déclenchent le SKU Nearby Search Enterprise Plus :
  
  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 :
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];
        
```
locationRestriction

Objet GMSPlaceLocationRestriction qui définit la région à rechercher, spécifiée sous la forme d'un cercle défini par un point central et un rayon en mètres. Le rayon doit être compris entre 0,0 et 50 000,0 (inclus). Le rayon par défaut est de 0.0. Vous devez définir une valeur supérieure à 0,0 dans votre demande.

Paramètres facultatifs

Utilisez l'objet GMSPlaceSearchNearbyRequest pour spécifier les paramètres facultatifs de la recherche.

includedTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes

Vous permet de spécifier une liste de types à partir des types du tableau A utilisés pour filtrer les résultats de recherche. Vous pouvez spécifier jusqu'à 50 types dans chaque catégorie de restriction de type.

Remarque : Les valeurs du tableau B ne sont renvoyées que dans la réponse. Vous ne pouvez pas utiliser les valeurs du Tableau B comme filtre.

Un lieu ne peut être associé qu'à un seul type principal parmi les types du Tableau A. Par exemple, le type principal peut être "mexican_restaurant" ou "steak_house". Utilisez includedPrimaryTypes et excludedPrimaryTypes pour filtrer les résultats en fonction du type principal d'un lieu.

Un lieu peut également être associé à plusieurs valeurs de type du Tableau A. Par exemple, un restaurant peut avoir les types suivants : "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment". Utilisez includedTypes et excludedTypes pour filtrer les résultats de la liste des types associés à un lieu.

Lorsque vous spécifiez un type principal général, tel que "restaurant" ou "hotel", la réponse peut contenir des lieux avec un type principal plus spécifique que celui spécifié. Par exemple, vous spécifiez d'inclure un type principal "restaurant". La réponse peut alors contenir des lieux dont le type principal est "restaurant", mais elle peut également contenir des lieux dont le type principal est plus spécifique, comme "chinese_restaurant" ou "seafood_restaurant".

Si une recherche est spécifiée avec plusieurs restrictions de type, seuls les lieux qui répondent à toutes les restrictions sont renvoyés. Par exemple, si vous spécifiez {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}, les lieux renvoyés proposent des services liés à "restaurant", mais ne fonctionnent pas principalement comme "steak_house".

Si vous omettez includedTypes, excludedTypes, includedPrimaryTypes et excludedPrimaryTypes de la requête, la recherche renvoie des lieux de tous types dans les limites de restriction de localisation.

includedTypes

Liste des types de lieux du Tableau A à rechercher. Si ce paramètre est omis, les lieux de tous types sont renvoyés.

excludedTypes

Liste des types de lieux du Tableau A à exclure d'une recherche.

Si vous spécifiez à la fois includedTypes (par exemple, "school") et excludedTypes (par exemple, "primary_school") dans la requête, la réponse inclut les lieux classés dans la catégorie "school", mais pas dans la catégorie "primary_school". La réponse inclut les lieux qui correspondent à au moins un des includedTypes et à aucun des excludedTypes.

En cas de types conflictuels (par exemple, un type apparaissant à la fois dans includedTypes et excludedTypes), une erreur INVALID_REQUEST est renvoyée.

includedPrimaryTypes

Liste des principaux types de lieux du Tableau A à inclure dans une recherche.

excludedPrimaryTypes

Liste des types de lieux principaux du Tableau A à exclure d'une recherche.

En cas de types principaux conflictuels (par exemple, un type apparaissant à la fois dans includedPrimaryTypes et excludedPrimaryTypes), une erreur INVALID_ARGUMENT est renvoyée.
maxResultCount

Spécifie le nombre maximal de résultats de lieux à renvoyer. Doit être compris entre 1 et 20 (valeur par défaut), inclus.
rankPreference

Type de classement à utiliser. Si ce paramètre est omis, les résultats sont classés par popularité. Peut être l'une des valeurs suivantes :
- .popularity (par défaut) : trie les résultats en fonction de leur popularité.
- .distance : trie les résultats par ordre croissant selon leur distance par rapport à l'emplacement spécifié.
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. Il n'existe pas de valeur par défaut.

Si le nom du pays du champ formattedAddress de la réponse correspond à regionCode, le code pays est omis de formattedAddress. Ce paramètre n'a aucun effet sur adrFormatAddress, qui inclut toujours le nom du pays, ni sur shortFormattedAddress, qui ne l'inclut jamais.

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"). Ce paramètre peut avoir une incidence sur les résultats en fonction de la loi applicable.

Afficher les mentions dans votre application

Lorsque votre application affiche des informations obtenues à partir de GMSPlacesClient, comme 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 d'auteur.

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

Nearby Search (nouveau) Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Requêtes Nearby Search (nouveau)

SDK Places Swift

Swift

Objective-C

Réponses Nearby Search

Obtenir l'état d'ouverture

isOpenWithRequest réponse

Facturation pour isOpenWithRequest

Exemple : effectuer une requête GMSPlaceIsOpenWithRequest

SDK Places Swift

Swift

Objective-C

Paramètres obligatoires

Liste des champs

SDK Places Swift

Swift

Objective-C

locationRestriction

Paramètres facultatifs

includedTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes

includedTypes

excludedTypes

includedPrimaryTypes

excludedPrimaryTypes

maxResultCount

rankPreference

regionCode

Afficher les mentions dans votre application

Nearby Search (nouveau)

`isOpenWithRequest` réponse

Facturation pour `isOpenWithRequest`

Exemple : effectuer une requête `GMSPlaceIsOpenWithRequest`