Text Search (nouvelle version)

Sélectionnez une plate-forme : Android iOS JavaScript Services 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". Ce service renvoie une liste des 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'adresses ambiguës dans un système automatisé. Les composants autres que l'adresse de la chaîne peuvent correspondre à des entreprises et à des adresses. Les adresses mal formatées ou les requêtes incluant des composants autres que des adresses, comme des noms d'entreprise, sont des exemples de requêtes d'adresses ambiguës. Les requêtes comme les deux premiers exemples peuvent ne renvoyer aucun résultat, sauf si un emplacement (comme une région, une restriction d'emplacement ou un biais d'emplacement) est défini.

Text Search (nouvelle version) est semblable à Nearby Search (nouvelle version). 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, Royaume-Uni" ou "123 Main Street, États-Unis"	"High Street" au Royaume-Uni et "Main Street" aux États-Unis La requête ne renvoie pas de résultats souhaités, sauf si une restriction de zone géographique est définie.
"ChainRestaurant New York"	Plusieurs établissements "ChainRestaurant" à New York, sans adresse ni même nom de rue.
"10 High Street, Escher UK" ou "123 Main Street, Pleasanton US"	Il n'existe qu'une seule "High Street" dans la ville britannique d'Escher et une seule "Main Street" dans la ville américaine de Pleasanton (Californie).
"UniqueRestaurantName New York"	Un seul établissement portant ce nom à New York. Aucune adresse n'est nécessaire pour le différencier.
"restaurants de pizza à New York"	Cette requête contient sa restriction géographique, et "restaurants de pizzas" est un type d'établissement bien défini. Il renvoie plusieurs résultats.
"[phone]"	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. Remarque : Pour de meilleurs résultats lors d'une recherche sur un numéro de téléphone, incluez le code pays suivi d'un espace, et définissez le paramètre region code pour qu'il corresponde au code pays.

Remarque :La recherche de texte (nouvelle) est disponible dans le SDK Places pour Android version 3.3.0 et ultérieure. Pour en savoir plus, consultez Choisir votre version de SDK. Pour en savoir plus sur l'utilisation des API Kotlin ajoutées dans la version 4.0.0, consultez la présentation des références.

Requêtes Text Search

Remarque :La recherche textuelle fait partie du SDK Places pour Android (nouveau) et n'est pas disponible dans le SDK Places pour Android.

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.DISPLAY_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:

• Définissez la liste des champs pour n'inclure que Place.Field.ID et Place.Field.DISPLAY_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 de résultats sur 10. La valeur par défaut et 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.

Remarque:Pour en savoir plus sur l'initialisation de PlacesClient, consultez la section Initialiser le client de l'API Places.

Vous pouvez utiliser un CancellationToken pour tenter d'annuler une demande à l'une des classes de requêtes (par exemple, FetchPlaceRequest). L'annulation est effectuée de la manière la plus optimale possible. Une fois la demande d'annulation envoyée, aucune réponse ne sera renvoyée. L'émission d'un jeton d'annulation ne garantit PAS qu'une requête particulière sera annulée. Vous pouvez toujours être facturé pour la requête, même si aucune réponse n'est renvoyée.

Réponses Text Search

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

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_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 d'un objet Place, consultez Accéder aux champs de données d'objet Place.

Paramètres obligatoires

Les paramètres obligatoires 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. Aucune liste par défaut des champs renvoyés n'est fournie dans la réponse.

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

    Place.Field.DISPLAY_NAME, Place.Field.ID, Place.Field.RESOURCE_NAME
    
    Remarques

    • Le champ Place.Field.NAME a été abandonné dans la version 4.0 du SDK Places pour Android. Utilisez Place.Field.DISPLAY_NAME à la place.
    • Le champ RESOURCE_NAME contient le nom de la ressource de lieu au format places/PLACE_ID. Utilisez DISPLAY_NAME pour accéder au nom textuel du lieu.

  • Les champs suivants déclenchent le SKU Text Search (Basic):

    Place.Field.ACCESSIBILITY_OPTIONS, Place.Field.ADDRESS_COMPONENTS, Place.Field.ADR_FORMAT_ADDRESS, Place.Field.BUSINESS_STATUS, Place.Field.FORMATTED_ADDRESS, Place.Field.GOOGLE_MAPS_URI, Place.Field.ICON_BACKGROUND_COLOR, Place.Field.ICON_MASK_URL, Place.Field.LOCATION, Place.Field.PHOTO_METADATAS, Place.Field.PLUS_CODE, Place.Field.PRIMARY_TYPE, Place.Field.PRIMARY_TYPE_DISPLAY_NAME, Place.Field.SHORT_FORMATTED_ADDRESS, Place.Field.SUB_DESTINATIONS, Place.Field.TYPES, Place.Field.UTC_OFFSET, Place.Field.VIEWPORT
    
    Remarque:Les champs Place.Field.ADDRESS, Place.Field.ICON_URL, Place.Field.LAT_LNG et Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE ont été abandonnés dans la version 4.0 du SDK Places pour Android. Utilisez plutôt Place.Field.FORMATTED_ADDRESS, Place.Field.ICON_MASK_URL, Place.Field.LOCATION et Place.ACCESSIBILITY_OPTIONS, respectivement. Place.Field.ACCESSIBILITY_OPTIONS n'est disponible que pour "Détails sur un lieu (nouveau)".

  • Les champs suivants déclenchent le SKU Text Search (Advanced):

    Place.Field.CURRENT_OPENING_HOURS, Place.Field.CURRENT_SECONDARY_OPENING_HOURS Place.Field.INTERNATIONAL_PHONE_NUMBER, 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 Place.Field.WEBSITE_URI
    
    Remarque:Les champs Place.Field.PHONE_NUMBER et Place.Field.USER_RATINGS_TOTAL ont été abandonnés dans la version 4.0 du SDK Places pour Android. Utilisez plutôt Place.Field.INTERNATIONAL_PHONE_NUMBER et Place.USER_RATING_COUNT.

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

    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
  Remarque:La version 4.0 du SDK Places pour Android a vu l'abandon de plusieurs champs de données de lieu et l'ajout de nouveaux champs. Pour en savoir plus, consultez Migrer vers les nouveaux champs de données de lieu dans le SDK Places pour Android 4.0 .

  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 textuelle, 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 la table A. Vous ne pouvez spécifier qu'un seul type. Exemple :

  • setIncludedType("bar")
  • setIncludedType("pharmacy")
  Remarque : Les valeurs du tableau B ne sont renvoyées que dans la réponse. Vous ne pouvez pas utiliser les valeurs de la table B comme filtre.

  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 à rechercher. Cet emplacement sert de biais, ce qui signifie que des résultats autour de l'emplacement spécifié peuvent être renvoyés, y compris en dehors de la zone spécifiée.

  Vous pouvez spécifier une restriction géographique ou un biais géographique, mais pas les deux. La restriction d'emplacement permet de spécifier la région dans laquelle les résultats doivent se trouver, tandis que la pondération géographique permet de spécifier la région dans laquelle les résultats sont susceptibles de se trouver ou de s'en rapprocher. Gardez à l'esprit que lorsque vous utilisez la pondération géographique, les résultats peuvent toujours se trouver en dehors de la zone spécifiée.

  Remarque : Si vous omettez à la fois le biais de localisation et la restriction de localisation, l'API utilise le biais d'adresse IP par défaut. Avec le biaisage IP, l'API utilise l'adresse IP de l'appareil pour biaiser les résultats.
  Remarque : Le paramètre locationBias peut être remplacé si textQuery contient un emplacement explicite tel que Market in Barcelona. Dans ce cas, locationBias est ignoré.

  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 un point central et un 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 hauts diamétralement opposés. Le point bas marque le coin sud-ouest du rectangle, et le point haut représente le coin 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 sa limite. Les limites de latitude doivent être comprises entre -90 et 90 degrés, et les limites de longitude entre -180 et 180 degrés, inclus:

    • Si low = high, la fenêtre d'affichage se compose de ce seul point.
    • Si low.longitude > high.longitude, la plage de longitude est inversée (la fenêtre d'affichage croise la ligne de longitude de 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 est défini sur 180 degrés et high.longitude sur -180 degrés, la plage de longitude est vide.
    • Si low.latitude > high.latitude, la plage de latitude est vide.

    Les valeurs basse et haute doivent être renseignées, et la zone représentée ne doit pas être vide. Un viewport vide génère une erreur.

    Par exemple, pour un viewport rectangulaire, consultez la section Requêtes de recherche de texte.

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

• Restriction géographique

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

  Vous pouvez spécifier une restriction géographique ou un biais géographique, mais pas les deux. Considérez la restriction d'emplacement comme une spécification de la région dans laquelle les résultats doivent se trouver, et le biais d'emplacement comme une spécification de la région à proximité de laquelle les résultats doivent se trouver, mais qui peut être en dehors de la zone.

  Remarque : Si vous omettez à la fois le biais de localisation et la restriction de localisation, l'API utilise le biais d'adresse IP par défaut. Avec le biaisage IP, l'API utilise l'adresse IP de l'appareil pour biaiser les résultats.

  Pour définir le paramètre de restriction de zone géographique, 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 lieux à renvoyer. Doit être compris 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 à ceux dont la note moyenne 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, etc., jusqu'à 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.

  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, seules les entreprises ouvertes au moment de l'envoi de la requête sont renvoyées. Si la valeur est false, tous les établissements sont renvoyés, quel que soit leur état d'ouverture. Si vous définissez ce paramètre sur false, les lieux qui ne précisent pas d'horaires d'ouverture dans la base de données Google Places sont renvoyés.

  Pour définir le paramètre "Ouvrir maintenant", 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 proposant des services à tous les niveaux de prix. Pour limiter les résultats aux seuls lieux situés dans des fourchettes de prix spécifiques, vous pouvez transmettre une liste de valeurs entières correspondant aux fourchettes de prix des lieux que vous souhaitez afficher:

  • 1 : l'établissement propose des services peu coûteux.
  • 2 : l'établissement propose des services à des prix modérés.
  • 3 : l'établissement propose des services coûteux.
  • 4 : l'établissement propose des services très onéreux.
  Remarque : La valeur entière 0, qui indique que l'établissement propose des services sans frais, peut être incluse dans une réponse, mais ne peut pas être utilisée comme valeur de filtre dans une requête.

  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 le classement des résultats dans la réponse en fonction du type de requête:

  • Pour une requête par catégorie telle que "Restaurants à New York", SearchByTextRequest.RankPreference.RELEVANCE (classement des résultats en fonction de la pertinence de la recherche) est défini par défaut. Vous pouvez définir la préférence de classement sur SearchByTextRequest.RankPreference.RELEVANCE ou SearchByTextRequest.RankPreference.DISTANCE (classement des résultats par distance).
  • Pour une requête non catégorique 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 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. Ce paramètre peut également avoir un effet 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 de la réponse correspond au code de région, le code pays 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.

  Pour définir le paramètre de code de région, 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 d'inclusion. Lorsque la valeur est true, seuls les lieux correspondant aux types spécifiés par le type d'inclusion sont renvoyés. Lorsque false, la valeur par défaut, est spécifiée, la réponse peut contenir des lieux qui ne correspondent pas aux types spécifiés.

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