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 (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 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 (nouveau)

Effectuez une requête Nearby Search (nouvelle version) 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 requis incluent :

  • 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 des champs ou si vous omettez la liste des champs, l'appel renvoie une erreur.
  • 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 de recherche à proximité indique 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. Elle filtre également la réponse pour ne renvoyer que les lieux de type "restaurant" et "cafe", 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 (nouveau)

La classe SearchNearbyResponse représente la réponse à 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 dans un objet Place, consultez Accéder aux champs de données de l'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 sous forme de 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 Pro :

      Place.Field.ADDRESS_COMPONENTS
      Place.Field.BUSINESS_STATUS
      Place.Field.ADDRESS
      Place.Field.DISPLAY_NAME >*
          * Utilisez plutôt Place.Field.NAME, qui est obsolète.
      Place.Field.ICON_BACKGROUND_COLOR
      Place.Field.ICON_MASK_URL*
          * Utilisez plutôt 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 le SKU Nearby Search Enterprise :

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

    • Les champs suivants déclenchent le SKU Enterprise Plus de la recherche à proximité :

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

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

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

Paramètres facultatifs

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

  • Types et types principaux

    Vous permet de spécifier une liste de types à partir des types du tableau 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.

    Un lieu ne peut être associé qu'à un seul type principal parmi les 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 être associé à plusieurs valeurs de type du 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 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 dont le type principal est plus spécifique que celui indiqué. 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, 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 proposent des services liés à "restaurant", mais ne fonctionnent pas principalement comme "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 dans la catégorie "school", mais pas dans la catégorie "primary_school". La réponse inclut les lieux qui correspondent à au moins un des includedTypes et à aucun des excludedTypes.

    En cas de types conflictuels (par exemple, un type apparaissant à 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 types de lieux principaux du Tableau A à exclure d'une recherche.

    En cas de types principaux conflictuels (par exemple, un type apparaissant à 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 lieux à renvoyer. Doit être compris entre 1 et 20 (valeur par défaut), inclus.

    Pour définir le paramètre du 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'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 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"). Ce paramètre peut avoir une incidence sur les résultats en fonction de la loi 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, comme 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.