Nearby Search (nouveau)

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

Développeurs de l'Espace économique européen (EEE)

Une requête Nearby Search (New) prend comme 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 Place objet, 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 également 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 (New)

Effectuez une requête Nearby Search (New) en appelant PlacesClient.searchNearby, 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 éléments suivants :

  • La liste des champs à renvoyer dans l'objet Place, également appelée masque de champ. Si vous ne spécifiez pas au moins un champ dans la liste de champs ou si vous omettez la liste de champs, l'appel renvoie une erreur.
  • La restriction de localisation 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 Nearby Search 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();
    });

Réponses Nearby Search (New)

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

  • Une liste d'objets Place qui représentent tous les lieux correspondants, avec un objet Place par lieu correspondant.
  • Chaque Place objet 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 obtenir d'autres exemples d'accès aux données dans un objet Place, consultez Accéder aux champs de données de l'objet Place.

Paramètres obligatoires

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

  • Liste de champs

    Lorsque vous demandez des détails 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 la référence Nearby Search Pro SKU :

      Place.Field.ADDRESS_COMPONENTS
      Place.Field.BUSINESS_STATUS
      Place.Field.ADDRESS
      Place.Field.DISPLAY_NAME >*
          * Utilisez à la place de Place.Field.NAME, qui est obsolète.
      Place.Field.ICON_BACKGROUND_COLOR
      Place.Field.ICON_MASK_URL*
          * Utilisez à la place de Place.Field.ICON_URL, qui est obsolète.
      Place.Field.ID
      Place.Field.LAT_LNG
      Place.Field.PHOTO_METADATAS
      Place.Field.PLUS_CODE
      Place.Field.PRIMARY_TYPE
      Place.Field.PRIMARY_TYPE_DISPLAY_NAME
      Place.Field.RESOURCE_NAME
      Place.Field.TYPES
      Place.Field.UTC_OFFSET
      Place.Field.VIEWPORT
      Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE

    • Les champs suivants déclenchent la référence Nearby Search Enterprise SKU :

      Place.Field.CURRENT_OPENING_HOURS
      Place.Field.CURRENT_SECONDARY_OPENING_HOURS
      Place.Field.INTERNATIONAL_PHONE_NUMBER*
          * Utilisez à la place de Place.Field.PHONE_NUMBER, qui est obsolète.
      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*
          * Utilisez à la place de Place.Field.USER_RATINGS_TOTAL, qui est obsolète.
      Place.Field.WEBSITE_URI

    • Les champs suivants déclenchent la référence Nearby Search Enterprise Plus SKU :

      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

    Pour définir le paramètre de la liste de champs, appelez la setPlaceFields() méthode 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' Place objet renvoyé par une requête contient les Place.Field.ID et Place.Field.DISPLAY_NAME champs :

// 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 d'emplacement

    Un LocationRestriction objet qui définit la région à rechercher, spécifiée sous la forme d'un cercle défini par un point central et un rayon en mètres. Le rayon doit être compris entre 0,0 et 50 000,0 inclus. N'oubliez pas que si vous spécifiez un rayon trop petit, la réponse ZERO_RESULTS sera renvoyée.

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

Paramètres facultatifs

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

  • Types et types principaux

    Vous permet de spécifier une liste de types du Tableau A utilisée 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 associé dans le 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 associées dans le Tableau A. Par exemple, un restaurant peut avoir les types suivants : "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment". Utilisez includedTypes et excludedTypes pour filtrer les résultats en fonction 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 "restaurant". La réponse peut alors contenir des lieux avec un type principal "restaurant", mais la réponse peut également contenir des lieux avec un type principal plus spécifique, tel que "chinese_restaurant" ou "seafood_restaurant".

    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 liés à "restaurant", mais ne fonctionnent pas principalement comme un "steak_house".

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

    Types inclus

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

    Pour définir le paramètre des 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 qui correspondent à au moins l'un de includedTypes et à aucun des excludedTypes.

    En cas de conflit entre les types, 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 des types exclus, appelez la méthode setExcludedTypes() lors de la création de l'objet SearchNearbyRequest.

    Types principaux inclus

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

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

    Types principaux exclus

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

    En cas de conflit entre les types principaux, par exemple si un type 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 setExcludedPrimaryTypes() lors de la création de l'SearchNearbyRequest.

  • Nombre maximal de résultats

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

    Pour définir le paramètre du nombre maximal de résultats, appelez la setMaxResultCount() lors de la création de l'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'une des valeurs suivantes :

    • 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 setRankPreference() méthode 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 du pays du champ FORMATTED_ADDRESS dans la réponse correspond au 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 affecter les résultats en fonction de la loi applicable.

    Pour définir le paramètre du code régional, appelez la setRegionCode() méthode 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 mentions requises.

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