Text Search

Une recherche textuelle renvoie des informations sur un ensemble de lieux en fonction d'une chaîne, par exemple "pizza à New York", "magasins de chaussures près d'Ottawa" ou "123 Main Street". Le service répond avec une liste de lieux correspondant à la chaîne de texte et aux limitations de zone géographique définis.

Ce service est particulièrement utile pour effectuer des requêtes d'adresse ambiguës dans un système automatisé. Les composants de la chaîne qui ne sont pas des adresses peuvent correspondre à des établissements et à des adresses. Les adresses mal formatées ou les requêtes incluant des composants qui ne sont pas des adresses, tels que des noms d'entreprise, sont des exemples de requêtes d'adresse ambiguës. Les requêtes comme dans les deux premiers exemples peuvent ne renvoyer aucun résultat, sauf si un lieu (région, restriction d'emplacement ou biais de localisation, par exemple) est défini.

"10 High Street, Royaume-Uni" ou "123 Main Street, États-Unis" Plusieurs "High Street" au Royaume-Uni et plusieurs "Main Street" aux États-Unis. La requête ne renvoie pas de résultats souhaitables, sauf si une restriction d'emplacement est définie.
"ChainRestaurant New York" Plusieurs "ChainRestaurant" à New York ; pas d'adresse postale ni même de nom de rue.
"10 High Street, Escher UK" ou "123 Main Street, Pleasanton US" Une seule "High Street" dans la ville d'Esccher au Royaume-Uni et une seule "Main Street" dans la ville de Pleasanton, aux États-Unis.
"NomRestaurantUnique New York" Un seul établissement portant ce nom à New York ; aucune adresse postale n'est nécessaire à différencier.
"pizzerias à New York" Cette requête contient la restriction d'emplacement, et "pizzeria" est un type de lieu bien défini. Elle renvoie plusieurs résultats.
"+1 514-670-8700"

Cette requête contient un numéro de téléphone. Elle renvoie plusieurs résultats pour les lieux associés à ce numéro de téléphone.

Requêtes Text Search

Une requête Text Search se présente sous la forme suivante:

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

// Define latitude and longitude coordinates of the search area.
LatLng southWest = new LatLng(37.38816277477739, -122.08813770258874);
LatLng northEast = new LatLng(37.39580487866437, -122.07702325966572);

// Use the builder to create a SearchByTextRequest object.
final SearchByTextRequest searchByTextRequest = SearchByTextRequest.builder("Spicy Vegetarian Food", placeFields)
  .setMaxResultCount(10)
  .setLocationRestriction(RectangularBounds.newInstance(southWest, northEast)).build();

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

Dans cet exemple, vous allez:

  • Définissez la liste des champs pour n'inclure que Place.Field.ID et Place.Field.NAME. Cela signifie que les objets Place de la réponse qui représentent chaque lieu correspondant ne contiennent que ces deux champs.

  • Utilisez SearchByTextRequest.Builder pour créer un objet SearchByTextRequest qui définit la recherche.

    • Définissez la chaîne de requête textuelle sur "Nourriture végétarienne épicée".

    • Définissez le nombre maximal de positions dans les résultats sur 10. La valeur par défaut (et la valeur maximale) est 20.

    • Limitez la zone de recherche au rectangle défini par les coordonnées de latitude et de longitude. Aucune correspondance en dehors de cette zone n'est renvoyée.

  • Ajoutez un OnSuccessListener et obtenez les lieux correspondants à partir de l'objet SearchByTextResponse.

Réponses Text Search

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

  • Liste d'objets Place qui représentent 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:

// Specify the list of fields to return.
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 du 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'objets Place.

Paramètres obligatoires

  • Liste des champs

    Spécifiez les champs de données de lieu à renvoyer. Transmettez une liste de valeurs Place.Field spécifiant les champs de données à renvoyer. Il n'existe pas de liste par défaut des champs renvoyés dans la réponse.

    Les listes de champs sont une bonne pratique à appliquer 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 Text Search (ID Only):

      Place.Field.ID, Place.Field.NAME

    • Les champs suivants déclenchent le SKU Text 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.TYPES, Place.Field.UTC_OFFSET, Place.Field.VIEWPORT, Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE

    • Les champs suivants déclenchent le SKU Text 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 Text 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

  • Requête textuelle

    Chaîne de texte sur laquelle doit porter la recherche. Par exemple: "restaurant", "123 Main Street" ou "meilleur lieu à visiter à San Francisco". L'API renvoie les résultats correspondant à cette chaîne et les classe en fonction de leur pertinence estimée.

Paramètres facultatifs

Définissez ces paramètres à l'aide des méthodes de SearchByTextRequest.Builder. Par exemple, pour définir le nombre maximal de résultats, appelez SearchByTextRequest.Builder.setMaxResultCount().

  • Type inclus

    Limite les résultats aux lieux correspondant au type spécifié défini par le tableau A. Vous ne pouvez spécifier qu'un seul type. Exemple :

    • setIncludedType("bar")
    • setIncludedType("pharmacy")

  • Limiter les résultats à une zone géographique

    Spécifie une zone à rechercher. Cette position sert de pondération : les résultats situés autour du lieu spécifié peuvent être renvoyés, y compris ceux situés en dehors de la zone spécifiée.

    Vous pouvez spécifier une restriction en fonction de la zone géographique ou une pondération de la zone géographique, mais pas les deux à la fois. Considérez la restriction d'emplacement comme le fait de spécifier la région dans laquelle les résultats doivent se trouver, et le biais de localisation comme la spécification de la région dans laquelle les résultats doivent se trouver à proximité, mais peuvent se trouver en dehors de la zone.

    Spécifiez la région sous la forme d'une fenêtre d'affichage rectangulaire ou d'un cercle.

    • Un cercle est défini par son point central et son rayon en mètres. Le rayon doit être compris entre 0,0 et 50 000,0 inclus. Le rayon par défaut est 0,0. Exemple :

      // Define latitude and longitude coordinates of the center of the search area.
LatLng searchCenter = new LatLng(37.38816277477739, -122.08813770258874);

// Use the builder to create a SearchByTextRequest object.
// Set the radius of the search area to 500.0 meters.
final SearchByTextRequest searchByTextRequest = SearchByTextRequest.builder("Spicy Vegetarian Food", placeFields)
  .setMaxResultCount(10)
  .setLocationBias(CircularBounds.newInstance(searchCenter, 500.0)).build();

    • Un rectangle est une fenêtre d'affichage de latitude-longitude, représentée par deux points bas et haut opposés en diagonale. Le point bas représente l'angle sud-ouest du rectangle et le point haut représente l'angle nord-est du rectangle.

      Une fenêtre d'affichage est considérée comme une région fermée, ce qui signifie qu'elle inclut ses limites. Les limites de latitude doivent être comprises entre -90 et 90 degrés inclus, et les limites de longitude doivent être comprises entre -180 et 180 degrés inclus:

      • Si low = high, la fenêtre d'affichage se compose de ce point unique.
      • Si low.longitude > high.longitude, la plage de longitudes est inversée (la fenêtre d'affichage traverse la ligne de longitude à 180 degrés).
      • Si low.longitude = -180 degrés et high.longitude = 180 degrés, la fenêtre d'affichage inclut toutes les longitudes.
      • Si low.longitude = 180 degrés et high.longitude = -180 degrés, la plage de longitude est vide.
      • Si low.latitude > high.latitude, la plage de latitudes est vide.

      Les valeurs "low" et "high" doivent être renseignées, et la zone représentée ne peut pas être vide. Une fenêtre d'affichage vide génère une erreur.

      Par exemple, pour une fenêtre d'affichage rectangulaire, consultez la section Requêtes Text Search.

  • Restriction de la zone géographique

    Spécifie une zone à rechercher. Les résultats situés en dehors de la zone spécifiée ne sont pas renvoyés. Spécifiez la région sous forme de fenêtre d'affichage rectangulaire. Pour plus d'informations sur la définition de la fenêtre d'affichage, reportez-vous à la description de la fonctionnalité Pondération de l'emplacement.

    Vous pouvez spécifier une restriction en fonction de la zone géographique ou une pondération de la zone géographique, mais pas les deux à la fois. Considérez la restriction d'emplacement comme la spécification de la région dans laquelle les résultats doivent se trouver, et le biais de l'emplacement comme la spécification de la région dans laquelle les résultats doivent se trouver à proximité, mais peuvent se trouver en dehors de la zone.

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

  • Note minimale

    restreint les résultats aux seuls résultats dont la note moyenne des utilisateurs est supérieure ou égale à cette limite. Les valeurs doivent être comprises entre 0,0 et 5,0 (inclus) par incréments de 0,5. Exemples: 0, 0,5, 1,0, ... , 5,0 inclus. Les valeurs sont arrondies à la décimale (0,5) la plus proche. Par exemple, une valeur de 0,6 élimine tous les résultats dont la note est inférieure à 1,0.

  • Ouvert

    Si la valeur est true, ne renvoie que les lieux ouverts au moment de l'envoi de la requête. Si la valeur est false, la fonction renvoie tous les établissements, qu'ils soient ouverts ou non. Les lieux sans horaires d'ouverture dans la base de données Google Places sont renvoyés si vous définissez ce paramètre sur false.

  • Niveaux de prix

    Limitez la recherche aux lieux indiqués à certains niveaux de prix. Par défaut, tous les niveaux de prix sont sélectionnés.

    Spécifiez une liste contenant une ou plusieurs des valeurs entières suivantes:

    • 1 - PRICE_LEVEL_INEXPENSIVE
    • 2 - PRICE_LEVEL_MODERATE
    • 3 - PRICE_LEVEL_EXPENSIVE
    • 4 - PRICE_LEVEL_VERY_EXPENSIVE

  • Préférence de classement

    Spécifie le classement des résultats dans la réponse. L'API utilise RELEVANCE par défaut, le cas échéant. Par exemple, pour une requête telle que "Restaurants à New York", RELEVANCE est la valeur par défaut. Pour les requêtes géographiques telles que "Mountain View, CA" ou tout autre type de requête, aucune valeur par défaut n'est appliquée et les résultats apparaissent dans l'ordre dans lequel ils sont renvoyés par le backend.

    Voici quelques valeurs :

    • SearchByTextRequest.RankPreference.DISTANCE: classez les résultats en fonction de la distance.
    • SearchByTextRequest.RankPreference.RELEVANCE: classez les résultats par pertinence.

  • Code régional

    Code de région utilisé pour mettre en forme la réponse, spécifié en tant que valeur de code CLDR à deux caractères. Ce paramètre peut également avoir un effet de biais sur les résultats de recherche. Il n'existe pas de valeur par défaut.

    Si le nom du pays du champ d'adresse dans la réponse correspond au code de la région, ce dernier est omis de l'adresse.

    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.

  • Filtrage strict des types

    Utilisé avec le paramètre de type "include". Lorsque ce paramètre est défini sur true, seuls les lieux correspondant aux types spécifiés par le type d'inclusion sont renvoyés. Lorsque la valeur par défaut est false, la réponse peut contenir des lieux qui ne correspondent pas aux types spécifiés.