Nearby Search (nouveau)

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

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)

Envoyez une requête de recherche à proximité 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 obligatoires incluent les suivants:

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

Cet exemple de requête de recherche à proximité spécifie 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 des lieux de type "restaurant" et "café".

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

SDK Places Swift pour iOS (bêta)

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
}

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.

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 utilise 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 Lieu 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 horaires d'ouverture est facturé au titre du code SKU Places Details Enterprise.
  • 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 GMSPlaceSearchNearbyRequest pour spécifier les paramètres requis pour la recherche.

  • 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 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:

    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]

  • locationRestriction

    Objet GMSPlaceLocationRestriction qui définit la région à rechercher spécifiée en tant que cercle, défini par le point central et le 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 requête.

Paramètres facultatifs

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

  • includedTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes

    Permet de spécifier une liste de types à partir des types de la table 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.

    Un lieu ne peut être associé qu'à un seul type principal parmi les types de la table 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 types du tableau A. Par exemple, un restaurant peut avoir les types suivants : "seafood_restaurant", "restaurant", "food", "point_of_interest" et "establishment". Utilisez includedTypes et excludedTypes pour filtrer les résultats dans 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 de "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, seules les zones géographiques qui répondent à toutes les restrictions sont renvoyées. Par exemple, si vous spécifiez {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}, les lieux renvoyés fournissent des services liés à "restaurant", mais ne fonctionnent pas principalement en tant que "steak_house".

    includedTypes

    Liste des types de lieux du tableau A à rechercher. Si ce paramètre est omis, tous les types de lieux 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 comme "school", mais pas comme "primary_school". La réponse inclut les lieux correspondant à au moins un des includedTypes et à aucun des excludedTypes.

    En cas de types contradictoires, par exemple si un type apparaît à 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.

    Si des types principaux contradictoires existent, par exemple un type qui apparaît à 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 (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'un des éléments suivants:

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

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 d'objets GMSPlaceReview pouvant comporter jusqu'à cinq éléments. 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.