Text Search (nouvelle version)

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

Text Search (nouvelle version) renvoie des informations sur un ensemble de lieux en fonction d'une chaîne, par exemple "pizza à New York", "magasin 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 biais d'emplacement 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 entreprises et à des adresses. Les adresses au format incorrect ou les requêtes incluant des composants autres que des adresses, comme les noms d'entreprise, constituent des exemples de requêtes d'adresse ambiguës. Les requêtes comme les deux premiers exemples peuvent renvoyer zéro résultat à moins qu'une zone géographique (telle qu'une région, une restriction d'emplacement ou un biais de localisation) ne soit définie.

Text Search (nouvelle version) est semblable à Nearby Search (nouveau). La principale différence entre les deux est que Text Search (nouvelle version) vous permet de spécifier une chaîne de recherche arbitraire, tandis que Nearby Search (nouvelle version) nécessite une zone spécifique dans laquelle effectuer la recherche.

"10 High Street, UK" ou "123 Main Street, US" Plusieurs boutiques "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 adresses "ChainRestaurant" à New York (pas d'adresse postale ni même de nom de rue).
"10 High Street, Escher Royaume-Uni" ou "123 Main Street, Pleasanton US" Une seule "High Street" dans la ville d'Escher au Royaume-Uni ; une seule "Main Street" dans la ville américaine de Pleasanton, en Californie.
"UniqueRestaurantName New York" Un seul établissement portant ce nom à New York (aucune adresse postale n'est nécessaire pour la différencier).
"restaurants pizzerias à Paris" Cette requête contient une restriction d'emplacement, et "pizzas" 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 dans 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 de texte sur « Spicy Vegetarian Food ».

    • Définissez le nombre maximal de résultats sur 10. La valeur par défaut et la valeur maximale sont 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 récupérez les lieux correspondants à partir de l'objet SearchByTextResponse.

Réponses de Text Search

La classe SearchByTextResponse représente la réponse à une requête de recherche. Un objet SearchByTextResponse 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:

// 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 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

Les paramètres requis pour SearchByTextRequest sont les suivants:

  • 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. La réponse ne contient pas de liste par défaut des champs renvoyés.

    Les listes de champs constituent une bonne pratique à suivre pour vous assurer de ne pas demander de données inutiles, ce qui permet d'éviter 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

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

  • Requête textuelle

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

    Pour définir le paramètre de requête de texte, appelez la méthode setTextQuery() lors de la création de l'objet SearchByTextRequest.

Paramètres facultatifs

Utilisez l'objet SearchByTextRequest pour spécifier les paramètres facultatifs de votre requête.

  • 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")

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

  • Biais de localisation

    Spécifie une zone de recherche. Cet emplacement sert de biais, ce qui signifie que des résultats à proximité du lieu spécifié peuvent être renvoyés, y compris des résultats situés en dehors de cette zone.

    Vous pouvez spécifier une restriction ou un biais d'emplacement, mais pas les deux. Considérez la restriction d'emplacement comme la spécification de la région dans laquelle les résultats doivent se trouver, et la pondération de la localisation comme la spécification de la région à laquelle les résultats doivent se trouver, mais qui peuvent se trouver en dehors de celle-ci.

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

    • Un cercle est défini par le point central et le rayon en mètres. Le rayon doit être compris entre 0,0 et 50 000,0 inclus. 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 un point haut en diagonale opposés. Le point bas représente l'angle sud-ouest du rectangle, tandis que 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 entre -180 et 180 degrés inclus:

      • Si low = high, la fenêtre d'affichage est constituée de ce seul point.
      • 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 longitudes est vide.
      • Si low.latitude > high.latitude, la plage de latitudes est vide.

      Les valeurs "Faible" et "Élevée" doivent être renseignées, et la zone représentée ne peut pas être vide. Une fenêtre d'affichage vide entraîne une erreur.

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

      Pour définir le paramètre de biais de localisation, appelez la méthode setLocationBias() lors de la création de l'objet SearchByTextRequest.

  • Restriction géographique

    Spécifie une zone de recherche. Les résultats situés en dehors de la zone spécifiée ne sont pas renvoyés. Spécifiez la région sous la forme d'une fenêtre d'affichage rectangulaire. Pour en savoir plus sur la définition de la fenêtre d'affichage, consultez la description du biais de localisation.

    Vous pouvez spécifier une restriction ou un biais d'emplacement, mais pas les deux. Considérez la restriction d'emplacement comme la spécification de la région dans laquelle les résultats doivent se trouver, et la pondération de la localisation comme la spécification de la région à laquelle les résultats doivent se trouver, mais qui peuvent se trouver en dehors de celle-ci.

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

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

  • Note minimale

    Limite les résultats aux seuls utilisateurs dont la note moyenne par les 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. Par exemple: 0, 0,5, 1.0, ... , 5.0 (inclus). Les valeurs sont arrondies au 0,5 le plus proche. Par exemple, une valeur de 0,6 élimine tous les résultats avec une note inférieure à 1,0.

    Pour définir le paramètre de note minimale, appelez la méthode setMinRating() lors de la création de l'objet SearchByTextRequest.

  • 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, renvoie tous les établissements, qu'ils soient ouverts ou non. Les lieux qui ne spécifient pas d'horaires d'ouverture dans la base de données Google Places sont renvoyés si vous définissez ce paramètre sur false.

    Pour définir le paramètre "Open Now", appelez la méthode setOpenNow() lors de la création de l'objet SearchByTextRequest.

  • Niveaux de prix

    Par défaut, les résultats incluent les établissements qui proposent des services à tous les niveaux de prix. Pour que les résultats n'incluent que les lieux à des niveaux de prix particuliers, vous pouvez transmettre une liste de valeurs entières correspondant aux niveaux de prix des lieux que vous souhaitez retourner:

    • 1 : Place fournit des services peu coûteux.
    • 2 : cet établissement propose des services à prix modéré.
    • 3 : Place fournit des services coûteux.
    • 4 : Place fournit des services très coûteux.

    Pour définir le paramètre des niveaux de prix, appelez la méthode setPriceLevels() lors de la création de l'objet SearchByTextRequest.

  • Préférence de classement

    Spécifie la façon dont les résultats sont classés dans la réponse en fonction du type de requête:

    • Pour une requête catégorielle telle que "Restaurants à New York", SearchByTextRequest.RankPreference.RELEVANCE (classer les résultats en fonction de la pertinence de la recherche) est la valeur par défaut. Vous pouvez définir la préférence de classement sur SearchByTextRequest.RankPreference.RELEVANCE ou SearchByTextRequest.RankPreference.DISTANCE (classer les résultats en fonction de la distance).
    • Pour une requête non catégorielle telle que "Mountain View, CA", nous vous recommandons de ne pas définir le paramètre de préférence de classement.

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

  • 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. Ce paramètre peut également influer sur les résultats de recherche. Il n'existe pas de valeur par défaut.

    Si le nom de pays du champ d'adresse dans la réponse correspond au code de région, celui-ci 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"). 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 SearchByTextRequest.

  • Filtrage strict par type

    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 sont renvoyés. Lorsque la valeur est false, la réponse peut contenir des lieux ne correspondant pas aux types spécifiés.

    Pour définir le paramètre de filtrage de type strict, appelez la méthode setStrictTypeFiltering() lors de la création de l'objet SearchByTextRequest.