Recherche à proximité (nouveau)

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

Une requête Nearby Search (New) prend en entrée la région à rechercher spécifiée sous la forme d'un cercle, définie par les coordonnées de latitude et de longitude du point central du cercle et par le rayon en mètres. La requête renvoie une liste de lieux correspondants, chacun représentés 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 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 exclure tous les lieux de type "école".

Requêtes Nearby Search (nouvelle version)

Pour effectuer une requête Nearby Search (New), appelez PlacesClient.searchNearby et transmettez 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 sont 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 cette liste, l'appel renvoie une erreur.
  • Restriction d'emplacement 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 réponse contiennent les champs de lieu Place.Field.ID et Place.Field.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 exclure 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.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();
    });

Réponses Nearby Search (nouvelle)

La classe SearchNearbyResponse représente la réponse à une requête de recherche. Un objet SearchNearbyResponse contient:

  • 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 de lieu 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 plus d'exemples d'accès aux données d'un objet Place, consultez Accéder aux champs de données d'un 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 détails sur un lieu, vous devez spécifier les données à renvoyer dans l'objet Place du 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 à suivre pour vous assurer de ne pas demander de données inutiles, ce qui permet d'éviter des délais de traitement et des frais inutiles.

    Renseignez 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.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.SECONDARY_OPENING_HOURS, Place.Field.PHONE_NUMBER, Place.Field.PRICE_LEVEL, Place.Field.RATING, Place.Field.OPENING_HOURS, Place.Field.USER_RATINGS_TOTAL, Place.Field.WEBSITE_URI

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

      Place.Field.CURBSIDE_PICKUP, Place.Field.DELIVERY, Place.Field.DINE_IN, Place.Field.EDITORIAL_SUMMARY, Place.Field.RESERVABLE, Place.Field.REVIEWS, Place.Field.SERVES_BEER, Place.Field.SERVES_BREAKFAST, Place.Field.SERVES_BRUNCH, Place.Field.SERVES_DINNER, Place.Field.SERVES_LUNCH, Place.Field.SERVES_VEGETARIAN_FOOD, Place.Field.SERVES_WINE, Place.Field.TAKEOUT

    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.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.NAME);

  • Restriction géographique

    Un objet LocationRestriction qui définit la région dans laquelle effectuer la recherche, spécifiée sous forme de cercle, définie par un point central et un rayon en mètres. Le rayon doit être compris entre 0,0 et 50 000,0. Gardez à l'esprit que si vous spécifiez un rayon trop petit, la réponse renvoyée sera ZERO_RESULTS.

    Pour définir le paramètre de restriction d'emplacement, 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 du 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 issu des 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 avoir plusieurs valeurs de type issues des types du Tableau A. 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 = Arrays.asList("restaurant") et excludedPrimaryTypes = Arrays.asList("steak_house"), les lieux renvoyés fournissent des services associés à "restaurant", mais ne fonctionnent pas principalement en tant que "steak_house".

    Pour obtenir un exemple d'utilisation de includedTypes et excludedTypes, consultez la section Requêtes Nearby Search (New).

    Types inclus

    Liste des types de lieux à rechercher à partir du Tableau A. Si ce paramètre est omis, des lieux de tous types 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 le includedTypes (tel que "school") et le excludedTypes (tel que "primary_school") dans la requête, la réponse inclut les lieux classés dans la catégorie "school", mais pas "primary_school". La réponse inclut des lieux correspondant à au moins un des éléments includedTypes et aucun des éléments excludedTypes.

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

    Pour définir le paramètre des 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 des types principaux inclus, appelez la méthode setIncludedPrimaryTypes() lors de la création de l'objet SearchNearbyRequest.

    Types principaux exclus

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

    S'il existe des types principaux en conflit, 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 des 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 lieu à renvoyer. Doit être comprise 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 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 à 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 régional 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 de pays du champ formattedAddress dans la réponse correspond à regionCode, le code pays est omis de formattedAddress.

    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 un impact sur les résultats en fonction du droit applicable.

    Pour définir le paramètre de code régional, 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 la section Règles relatives au SDK Places pour Android.