Recherche à proximité (nouveau)

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

Une requête Nearby Search (New) utilise la région à rechercher spécifié 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 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 aussi filtrer la réponse en spécifiant une liste de types de lieux à inclure ou exclure explicitement du de réponse. Par exemple, vous pouvez spécifier de n'inclure dans la réponse que les lieux de type "restaurant", "boulangerie" et "café", ou exclure tous les lieux de type "école".

Requêtes Nearby Search (nouvelle version)

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

L'objet GMSPlaceSearchNearbyRequest spécifie tous les obligatoire et facultatif pour la requête. Les paramètres obligatoires sont les suivants:

  • 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.
  • Restriction liée à la localisation, c'est-à-dire le cercle définissant la zone de recherche.

Cet exemple de requête de recherche à proximité indique que la réponse avec les objets GMSPlace contiennent le nom (GMSPlacePropertyName) et les coordonnées du lieu ; (GMSPlacePropertyCoordinate) pour chaque objet GMSPlace de la recherche résultats. Il filtre également la réponse pour ne renvoyer que les 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 (preview)

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 suivante : GMSPlace avec un objet GMSPlace par lieu correspondant.

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.

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 Place avec les champs nécessaires, consultez Informations sur le lieu.
  • Objet facultatif NSDate (Obj-C) ou Date (Swift) spécifiant l'heure à laquelle vous souhaitez vérifier. Si aucune heure n'est spécifiée, la valeur par défaut est "now".
  • Une méthode GMSPlaceOpenStatusResponseCallback pour gérer la réponse.
  • &gt;

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 les récupère à l'aide de GMSPlacesClient GMSFetchPlaceRequest:.

isOpenWithRequest réponse

isOpenWithRequest renvoie un objet GMSPlaceIsOpenResponse contenant une valeur booléenne nommée status qui indique si l'établissement est ouvert ou fermé, ou si l'état est inconnu.

Langue Valeur si ouverte Valeur en cas de fermeture Valeur si état 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 Basic Data. Les autres horaires d'ouverture sont facturés sous le SKU Place Details (Advanced).
  • Si votre objet GMSPlace contient déjà ces champs provenant d'une requête précédente, vous ne serez plus facturé.

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 afin de 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 pour affichée dans l'objet GMSPlace du lieu en tant que masque de champ. Pour définir le masque de champ, transmettez un tableau de valeurs GMSPlaceProperty à l'objet GMSPlaceSearchNearbyRequest. Le masquage du champ est une bonne pratique de conception pour vous assurer que vous ne demandez pas de données inutiles, ce qui permet d'éviter le temps de traitement et les frais de facturation inutiles.

    Renseignez un ou plusieurs des champs suivants:

    • Les champs suivants déclenchent l'événement SKU Nearby Search (Basic):

      GMSPlacePropertyAddressComponents, GMSPlacePropertyBusinessStatus, GMSPlacePropertyCoordinate, GMSPlacePropertyFormattedAddress GMSPlacePropertyName, GMSPlacePropertyIconBackgroundColor, GMSPlacePropertyIconImageURL, GMSPlacePropertyPhotos, GMSPlacePropertyPlaceID, GMSPlacePropertyPlusCode, GMSPlacePropertyTypes, GMSPlacePropertyUTCOffsetMinutes, GMSPlacePropertyViewport, GMSPlacePropertyWheelchairAccessibleEntrance.

    • Les champs suivants déclenchent l'événement SKU Nearby Search (Advanced):

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

    • Les champs suivants déclenchent l'événement SKU Nearby Search (Preferred):

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

    L'exemple suivant transmet une liste de valeurs des champs pour spécifier que l'objet GMSPlace renvoyé par une requête contient le 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 (preview)

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

    Un GMSPlaceLocationRestriction d'objet qui définit la région dans laquelle effectuer la recherche. Il est spécifié sous la forme d'un cercle, défini par le point central et en mètres. Le rayon doit être compris entre 0,0 et 50 000,0 inclus. Le rayon par défaut est 0,0. Vous devez la définir dans votre requête sur une valeur supérieure à 0,0.

Paramètres facultatifs

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

  • inclusTypes/excludedTypes, inclusPrimaryTypes/excludedPrimaryTypes

    Permet de spécifier une liste de types à partir des types Tableau A utilisé 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 avoir qu'un seul type principal issu des types Le Tableau A est associé aux Par exemple, le type principal peut être "mexican_restaurant" ou "steak_house". Utilisez includedPrimaryTypes et excludedPrimaryTypes pour filtrer les résultats. le type principal d'un lieu.

    Un lieu peut également avoir plusieurs valeurs de type à partir des types. Tableau A qui lui est associée. Par exemple, un restaurant peut posséder les types suivants: "seafood_restaurant", "restaurant", "food" "point_of_interest", "establishment". Utiliser includedTypes et excludedTypes pour filtrer les résultats sur 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 la réponse peut également contenir des lieux avec une définition type principal, tel que "chinese_restaurant" ou "seafood_restaurant".

    Si une recherche est spécifiée avec plusieurs restrictions de type, seuls les lieux qui satisfont à toutes les restrictions sont renvoyées. Par exemple, si vous spécifiez {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}, le Les lieux renvoyés proposent des services associés à "restaurant", mais ne fonctionnent pas principalement en tant que "steak_house".

    includedTypes

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

    excludedTypes

    Une liste des types de lieux Tableau A pour exclure d'un recherche.

    Si vous spécifiez à la fois includedTypes (par exemple, "school") et excludedTypes (par exemple, "primary_school") dans la requête, le paramètre La réponse inclut des lieux classés dans la catégorie "school", mais pas dans la catégorie "primary_school" La réponse inclut des lieux correspondant à au moins un des éléments suivants : includedTypes et aucun excludedTypes.

    S'il existe des types en conflit, par exemple si un type apparaît à la fois dans includedTypes et excludedTypes, une erreur INVALID_REQUEST est renvoyée.

    includedPrimaryTypes

    La liste des principaux types de lieux Tableau A à inclure lors d'une recherche.

    excludedPrimaryTypes

    La liste des principaux types de lieux Tableau A pour exclure à partir d'une recherche.

    S'il existe des types principaux en conflit, par exemple un type apparaissant à la fois dans includedPrimaryTypes et excludedPrimaryTypes, un L'erreur INVALID_ARGUMENT est renvoyée.

  • maxResultCount

    Spécifie le nombre maximal de résultats de lieu à 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 en fonction de leur popularité. Il peut s'agir de 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 en fonction de leur distance par rapport à la à l'emplacement spécifié.
  • regionCode

    Code régional utilisé pour mettre en forme la réponse, spécifié sous la forme d'une <ph type="x-smartling-placeholder"></ph> CLDR à deux caractères. Il n'existe pas de valeur par défaut.

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

    La plupart des codes CLDR sont identiques les codes ISO 3166-1, à quelques exceptions près. Par exemple, le ccTLD au Royaume-Uni est "uk" (.co.uk), tandis que son code ISO 3166-1 est "gb". (d'un point de vue technique, du Royaume-Uni de Grande-Bretagne et d'Irlande du Nord). Ce paramètre peut avoir un impact sur les résultats en fonction de la législation applicable.

Afficher les mentions dans votre application

Lorsque votre application affiche des informations obtenues GMSPlacesClient telles que des photos et des avis, l'application doit également afficher les mentions requises.

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

Pour en savoir plus, consultez la documentation attributions.