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 Place, 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 explicitement ou à exclure 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".

Remarque :La recherche à proximité (nouvelle) est disponible dans le SDK Places pour Android version 3.5.0 et ultérieure. Pour en savoir plus, consultez Choisir votre version de SDK. Pour en savoir plus sur l'utilisation des API Kotlin ajoutées dans la version 4.0.0, consultez la présentation des références.

Requêtes Nearby Search (nouveau)

Envoyez une requête Nearby Search (Nouvelle) en appelant PlacesClient.searchNearby et en transmettant un objet SearchNearbyRequest qui définit les paramètres de la requête.

L'objet SearchNearbyRequest 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 Place, également appelé masque de champ. 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 de zone géographique pour la zone de recherche, définie comme une paire latitude/longitude et une valeur de rayon, en mètres.

Cet exemple de requête de recherche à proximité spécifie que les objets Place de la réponse contiennent les champs de lieu Place.Field.ID et Place.Field.DISPLAY_NAME pour chaque objet Place dans les résultats de recherche. Il filtre également la réponse pour ne renvoyer que les lieux de type "restaurant" et "café", mais exclut les lieux de type "pizza_restaurant" et "american_restaurant".

// Define a list of fields to include in the response for each returned place.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME);

// Define the search area as a 1000 meter diameter circle in New York, NY.
LatLng center = new LatLng(40.7580, -73.9855);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 1000);

// Define a list of types to include.
final List<String> includedTypes = Arrays.asList("restaurant", "cafe");
// Define a list of types to exclude.
final List<String> excludedTypes = Arrays.asList("pizza_restaurant", "american_restaurant");

// Use the builder to create a SearchNearbyRequest object.
final SearchNearbyRequest searchNearbyRequest =
SearchNearbyRequest.builder(/* location restriction = */ circle, placeFields)
    .setIncludedTypes(includedTypes)
    .setExcludedTypes(excludedTypes)
    .setMaxResultCount(10)
    .build());

// Call placesClient.searchNearby() to perform the search.
// Define a response handler to process the returned List of Place objects.
placesClient.searchNearby(searchNearbyRequest)
    .addOnSuccessListener(response -> {
      List<Place> places = response.getPlaces();
    });

Remarque:Pour en savoir plus sur l'initialisation de PlacesClient, consultez la section Initialiser le client de l'API Places.

Vous pouvez utiliser un CancellationToken pour tenter d'annuler une demande à l'une des classes de requêtes (par exemple, FetchPlaceRequest). L'annulation est effectuée de la manière la plus optimale possible. Une fois la demande d'annulation envoyée, aucune réponse ne sera renvoyée. L'émission d'un jeton d'annulation ne garantit PAS qu'une requête particulière sera annulée. Vous pouvez toujours être facturé pour la requête, même si aucune réponse n'est renvoyée.

Réponses Nearby Search (nouveau)

La classe SearchNearbyResponse représente la réponse d'une requête de recherche. Un objet SearchNearbyResponse contient les éléments suivants:

• Liste d'objets Place représentant tous les lieux correspondants, avec un objet Place par lieu correspondant.
• Chaque objet Place ne contient que les champs définis par la liste de champs transmise dans la requête.

Par exemple, dans la requête, vous avez défini une liste de champs comme suit:

// Define a list of fields to include in the response for each returned place.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

Cette liste de champs signifie que chaque objet Place de la réponse ne contient que l'ID et le nom de chaque lieu correspondant. Vous pouvez ensuite utiliser les méthodes Place.getId() et Place.getName() pour accéder à ces champs dans chaque objet Place.

Pour obtenir d'autres exemples d'accès aux données d'un objet Place, consultez Accéder aux champs de données d'objet Place.

Paramètres obligatoires

Utilisez l'objet SearchNearbyRequest 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 Place pour le lieu en tant que masque de champ. Pour définir le masque de champ, transmettez un tableau de valeurs de Place.Field à l'objet SearchNearbyRequest. 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 (Basic):

    Place.Field.ADDRESS_COMPONENTS, Place.Field.BUSINESS_STATUS, Place.Field.ADDRESS, Place.Field.ICON_BACKGROUND_COLOR, Place.Field.ICON_URL, Place.Field.LAT_LNG, Place.Field.PHOTO_METADATAS, Place.Field.PLUS_CODE, Place.Field.PRIMARY_TYPE, Place.Field.PRIMARY_TYPE_DISPLAY_NAME, Place.Field.ID, Place.Field.NAME, Place.Field.TYPES, Place.Field.UTC_OFFSET, Place.Field.VIEWPORT, Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE

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

    Place.Field.CURRENT_OPENING_HOURS, Place.Field.CURRENT_SECONDARY_OPENING_HOURS Place.Field.INTERNATIONAL_PHONE_NUMBER, Place.Field.NATIONAL_PHONE_NUMBER Place.Field.OPENING_HOURS, Place.Field.PRICE_LEVEL, Place.Field.RATING, Place.Field.SECONDARY_OPENING_HOURS, Place.Field.USER_RATING_COUNT Place.Field.WEBSITE_URI
    
    Remarque:Les champs Place.Field.PHONE_NUMBER et Place.Field.USER_RATINGS_TOTAL ont été abandonnés dans la version 4.0 du SDK Places pour Android. Utilisez plutôt Place.Field.INTERNATIONAL_PHONE_NUMBER et Place.USER_RATING_COUNT.

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

    Place.Field.ALLOWS_DOGS, Place.Field.CURBSIDE_PICKUP, Place.Field.DELIVERY, Place.Field.DINE_IN, Place.Field.EDITORIAL_SUMMARY, Place.Field.EV_CHARGE_OPTIONS, Place.Field.FUEL_OPTIONS, Place.Field.GOOD_FOR_CHILDREN, Place.Field.GOOD_FOR_GROUPS, Place.Field.GOOD_FOR_WATCHING_SPORTS, Place.Field.LIVE_MUSIC, Place.Field.MENU_FOR_CHILDREN, Place.Field.OUTDOOR_SEATING, Place.Field.PARKING_OPTIONS, Place.Field.PAYMENT_OPTIONS, Place.Field.RESERVABLE, Place.Field.RESTROOM, Place.Field.REVIEWS, Place.Field.SERVES_BEER, Place.Field.SERVES_BREAKFAST, Place.Field.SERVES_BRUNCH, Place.Field.SERVES_COCKTAILS, Place.Field.SERVES_COFFEE, Place.Field.SERVES_DESSERT, Place.Field.SERVES_DINNER, Place.Field.SERVES_LUNCH, Place.Field.SERVES_VEGETARIAN_FOOD, Place.Field.SERVES_WINE, Place.Field.TAKEOUT
  Remarque:La version 4.0 du SDK Places pour Android a vu l'abandon de plusieurs champs de données de lieu et l'ajout de nouveaux champs. Pour en savoir plus, consultez Migrer vers les nouveaux champs de données de lieu dans le SDK Places pour Android 4.0 .

  Pour définir le paramètre de liste de champs, appelez la méthode setPlaceFields() lors de la création de l'objet SearchNearbyRequest.

  L'exemple suivant définit une liste de deux valeurs de champ pour spécifier que l'objet Place renvoyé par une requête contient les champs Place.Field.ID et Place.Field.DISPLAY_NAME:

// Define a list of fields to include in the response for each returned place.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME);

• Restriction géographique

  Objet LocationRestriction 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 supérieur à 0,0 et inférieur ou égal à 50 000,0. N'oubliez pas que spécifier un rayon trop petit renvoie ZERO_RESULTS en réponse.

  Pour définir le paramètre de restriction de zone géographique, appelez la méthode setLocationRestriction() lors de la création de l'objet SearchNearbyRequest.

Paramètres facultatifs

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

• Types et types principaux

  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.

  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 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 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 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 = Arrays.asList("restaurant") et excludedPrimaryTypes = Arrays.asList("steak_house"), les lieux renvoyés fournissent des services liés à "restaurant", mais ne fonctionnent pas principalement en tant que "steak_house".

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

  Pour savoir comment utiliser includedTypes et excludedTypes, consultez la section Requêtes Nearby Search (New).

  Types inclus

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

  Pour définir le paramètre de types inclus, appelez la méthode setIncludedTypes() lors de la création de l'objet SearchNearbyRequest.

  Types exclus

  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.

  Pour définir le paramètre de types exclus, appelez la méthode setExcludedTypes() lors de la création de l'objet SearchNearbyRequest.

  Types principaux inclus

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

  Pour définir le paramètre de types principaux inclus, appelez la méthode setIncludedPrimaryTypes() lors de la création de l'objet SearchNearbyRequest.

  Types de primaires exclus

  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.

  Pour définir le paramètre de types principaux exclus, appelez la méthode setExcludedPrimaryTypes() lors de la création de l'objet SearchNearbyRequest.

• Nombre maximal de résultats

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

  Pour définir le paramètre de nombre maximal de résultats, appelez la méthode setMaxResultCount() lors de la création de l'objet SearchNearbyRequest.

• Préférence de classement

  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é.

  Pour définir le paramètre de préférence de classement, appelez la méthode setRankPreference() lors de la création de l'objet SearchNearbyRequest.

• Code régional

  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 FORMATTED_ADDRESS de la réponse correspond à regionCode, le code pays est omis de FORMATTED_ADDRESS.

  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.

  Pour définir le paramètre de code de région, appelez la méthode setRegionCode() lors de la création de l'objet SearchNearbyRequest.

Afficher les mentions dans votre application

Lorsque votre application affiche des informations obtenues à partir de PlacesClient, telles que des photos et des avis, elle doit également afficher les attributions requises.

Pour en savoir plus, consultez les Règles du SDK Places pour Android.