Recherche à proximité (nouveau)

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

Une requête Nearby Search (New) utilise comme entrée la région à rechercher, spécifiée par 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 de n'inclure dans la réponse que les lieux de type "restaurant", "boulangerie" et "café", ou d'exclure tous les lieux de type "école".

Requêtes Nearby Search (nouvelles)

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 obligatoires sont les suivants:

  • Liste des champs à renvoyer dans l'objet GMSPlace, également appelé 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 cette liste, l'appel renvoie une erreur.
  • La restriction d'emplacements, c'est-à-dire le cercle définissant la zone de recherche

Cet exemple de requête de recherche à proximité 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é".

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

GooglePlacesSwift

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.

Avec les champs de données, l'objet GMSPlace de la réponse contient les fonctions de membre suivantes:

  • isOpen calcule si un lieu est ouvert à un horaire donné.
  • isOpenAtDate calcule si un lieu est ouvert à une date donnée.

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 à renvoyer dans l'objet GMSPlace du 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 de conception pour vous assurer de ne pas demander de données inutiles. Vous pouvez ainsi réduire le temps de traitement et les frais facturés.

    Renseignez un ou plusieurs des champs suivants:

    • Les champs suivants déclenchent le SKU Nearby Search (Basic):

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

    • Les champs suivants déclenchent le SKU Nearby Search (Advanced):

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

    • Les champs suivants déclenchent le SKU Nearby Search (Preferred):

      GMSPlacePropertyCurbsidePickup, GMSPlacePropertyDelivery, GMSPlacePropertyDineIn, GMSPlacePropertyEditorialSummary, GMSPlacePropertyReservable, GMSPlacePropertyReviews, GMSPlacePropertyServesBeer, GMSPlacePropertyServesBreakfast, GMSPlacePropertyServesBrunch, GMSPlacePropertyServesDinner, GMSPlacePropertyServesLunch, GMSPlacePropertyServesVegetarianFood, GMSPlacePropertyServesWine et 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];

    GooglePlacesSwift

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

  • locationRestriction

    Un objet GMSPlaceLocationRestriction qui définit la région à rechercher, spécifiée sous la forme d'un 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 le définir dans votre demande sur une valeur supérieure à 0,0.

Paramètres facultatifs

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

  • includePrimaryTypes/excludedTypes, includePrimaryTypes/excludedPrimaryTypes

    Permet de spécifier une liste de types à partir des types Tableau A utilisés pour filtrer les résultats de la 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 parmi les types Table A qui lui sont associés. 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 avoir plusieurs valeurs de type issues des types Tableau A qui lui sont associés. Par exemple, un restaurant peut présenter les types suivants : "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment". Utilisez includedTypes et excludedTypes pour filtrer les résultats sur la liste des types associés à un lieu.

    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 fournissent des services liés à "restaurant", mais ne fonctionnent pas principalement en tant que "steak_house".

    includedTypes

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

    excludedTypes

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

    Si vous spécifiez à la fois les valeurs 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 des lieux correspondant à au moins un des éléments includedTypes et aucun des éléments excludedTypes.

    En cas de types conflictuels, tels qu'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 principaux types de lieux du Tableau A à exclure d'une recherche.

    En cas de types principaux en conflit, tels qu'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 lieu à renvoyer. Doit être comprise 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é. 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 à l'emplacement spécifié.

  • regionCode

    Code de région utilisé pour mettre en forme la réponse, spécifié en tant que valeur de code CLDR à deux caractères. Il n'existe pas de valeur par défaut.

    Si le nom du pays du champ formattedAddress dans la réponse correspond à regionCode, le code pays est omis dans formattedAddress. Ce paramètre n'a aucun effet sur adrFormatAddress, qui inclut toujours le nom du pays, ou 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, 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'auteurs. 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.