Text Search (nouvelle version)

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

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

Si votre adresse de facturation se trouve dans l'Espace économique européen, les Conditions d'utilisation de Google Maps Platform pour l'EEE s'appliqueront à votre utilisation des Services à compter du 8 juillet 2025. La fonctionnalité varie selon la région. En savoir plus

Text Search (nouveau) 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.

En plus des paramètres obligatoires, Text Search (New) permet d'affiner les requêtes à l'aide de paramètres facultatifs pour obtenir de meilleurs résultats.

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

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

Requêtes Text Search

Remarque : Text Search fait partie du SDK Places pour Android (New) 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 de sorte qu'elle n'inclue 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 "Spicy Vegetarian Food".

  • Définissez le nombre maximal de lieux à afficher sur 10. La valeur par défaut et la valeur maximale sont de 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 Initialiser le client de l'API Places.

Vous pouvez utiliser un CancellationToken pour tenter d'annuler une requête adressée à l'une des classes de requête (par exemple, FetchPlaceRequest). L'annulation est effectuée dans la mesure du possible. Une fois qu'une demande d'annulation est émise, aucune réponse n'est 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 à 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 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 d'un objet Place, consultez Accéder aux champs de données d'un objet Place.

Pagination

La classe SearchByTextResponse de Text Search permet d'accéder à la pagination des résultats de recherche textuelle via sa méthode getPagination(), qui renvoie un objet Pagination.

Utilisez la méthode hasNextPage() de l'objet Pagination pour déterminer si d'autres pages de résultats sont disponibles. Cette méthode renvoie une valeur booléenne (true ou false).

Tant que hasNextPage() renvoie "true", appelez la méthode fetchNextPage() pour récupérer la page de résultats suivante.

L'exemple suivant montre comment vérifier si une page suivante est disponible, puis charger la page.

Kotlin

val searchByTextRequest =
      searchByTextRequest("restaurants", Arrays.asList(Place.Field.NAME)) {
        maxResultCount = 10
      }

// using pagination object (Preferred)
placesClient.searchByText(searchByTextRequest)   
    .addOnSuccessListener {response: SearchByTextResponse ->
        val places = response.places

        val pagination = response.pagination

        if (pagination.hasNextPage()) {
            pagination.setPageSize(20)
            pagination.fetchNextPage()
                    .addOnSuccessListener { nextPageResponse ->
                          val nextPagePlaces = nextPageResponse.getPlaces()
                    }
                    .addOnFailureListener {// Handle error with given status code}
        }
}
.addOnFailureListener {
// TODO: Handle error with given status code.
exception -> {
          exception.printStackTrace();
        }
}

Java

SearchByTextRequest searchByTextRequest =
  SearchByTextRequest.builder("restaurants", Arrays.asList(Place.Field.NAME)).setMaxResultCount(10).build();

// using pagination object (Preferred)
placesClient.searchByText(searchByTextRequest)
  .addOnSuccessListener((response) -> {
    List<Place> places = response.getPlaces();
    Log.i(TAG, "Places result: " + places);

    Pagination pagination =
      response.getPagination();

    if (pagination.hasNextPage()) {
      pagination.setPageSize(20); // change the page size from 10 to 20
      pagination.fetchNextPage()
    	  .addOnSuccessListener((nextPageResponse) -> {
            List<Place> nextPagePlaces = nextPageResponse.getPlaces();
            Log.i(TAG, "Next page places result: " + nextPagePlaces);
        });
    }
  })
  .addOnFailureListener((exception) -> {
    if (exception instanceof ApiException) {
    	// Handle error with given status code
    }
  });

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. 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 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 Essentials ID Only :

    Place.Field.DISPLAY_NAME*
        * À utiliser à la place de Place.Field.NAME (obsolète depuis la version 4.0).
    Place.Field.ID
Place.Field.RESOURCE_NAME*
        * Contient le nom de ressource du lieu au format : places/PLACE_ID.
         Utilisez DISPLAY_NAME pour accéder au nom textuel du lieu.

    Pour obtenir la liste complète des champs et de leurs SKU associés, consultez Champs de données de lieu (nouveau).

  • Les champs suivants déclenchent le SKU Text Search Pro :

    Place.Field.ACCESSIBILITY_OPTIONS*
        À utiliser à la place de Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE (obsolète).
    Place.Field.ADDRESS_COMPONENTS
Place.Field.ADR_FORMAT_ADDRESS
Place.Field.BUSINESS_STATUS
Place.Field.FORMATTED_ADDRESS*
        À utiliser à la place de Place.Field.ADDRESS (obsolète).
    Place.Field.GOOGLE_MAPS_URI
Place.Field.ICON_BACKGROUND_COLOR
Place.Field.ICON_MASK_URL *
        À utiliser à la place de Place.Field.ICON_URL (obsolète).
    Place.Field.LOCATION*
        À utiliser à la place de Place.Field.LAT_LNG (obsolète).
    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

    Pour obtenir la liste complète des champs et de leurs SKU associés, consultez Champs de données de lieu (nouveau).

  • Les champs suivants déclenchent le SKU Text Search Enterprise :

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

    Pour obtenir la liste complète des champs et de leurs SKU associés, consultez Champs de données de lieu (nouveau).

  • Les champs suivants déclenchent le SKU Text Search Enterprise Plus :

    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 obtenir la liste complète des champs et de leurs SKU associés, consultez Champs de données de lieu (nouveau).

  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.

  Remarque  : Pour obtenir de meilleurs résultats lors d'une recherche sur un numéro de téléphone, incluez l'indicatif du pays suivi d'un espace, puis définissez le paramètre regionCode de sorte qu'il corresponde à l'indicatif du pays. Les formats de numéros de téléphone varient selon les pays, et l'API tente de renvoyer un résultat pour ces différents formats. Pour les numéros de téléphone valides, l'API Places (New) accepte le format E.164. Les caractères alphabétiques sont convertis en fonction du mappage du clavier E.161.

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

  Vous pouvez spécifier une restriction ou une pondération d'emplacement, mais pas les deux. La restriction géographique 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 d'être proches. 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 la pondération géographique et la restriction géographique, l'API utilise par défaut la pondération par adresse IP. Avec la pondération par adresse IP, l'API utilise l'adresse IP de l'appareil pour pondérer 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 opposés en diagonale (un point bas et un point haut). Le point bas marque l'angle sud-ouest du rectangle, et le point haut représente l'angle nord-est du rectangle.

    Un viewport est considéré comme une région fermée, ce qui signifie qu'il inclut sa limite. 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 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 = 180 degrés et high.longitude = -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 boîte représentée ne peut pas être vide. Un viewport vide génère une erreur.

    Pour obtenir un exemple de fenêtre d'affichage rectangulaire, consultez Requêtes Text Search.

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

• Restriction d'emplacement

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

  Vous pouvez spécifier une restriction ou une pondération d'emplacement, mais pas les deux. La restriction de zone géographique consiste à spécifier la région dans laquelle les résultats doivent se trouver, tandis que la pondération de zone géographique consiste à spécifier la région dont les résultats doivent être proches, mais ils peuvent se trouver en dehors de cette zone.

  Remarque  : Si vous omettez à la fois la pondération géographique et la restriction géographique, l'API utilise par défaut la pondération par adresse IP. Avec la pondération par adresse IP, l'API utilise l'adresse IP de l'appareil pour pondérer 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 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. 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 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, ne renvoie que les lieux ouverts au moment de l'envoi de la requête. Si la valeur est false, renvoie tous les établissements, 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 "ouvert 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 qui proposent des services à tous les niveaux de prix. Pour limiter les résultats aux lieux d'une certaine gamme de prix, vous pouvez transmettre une liste de valeurs entières correspondant aux gammes de prix des lieux que vous souhaitez renvoyer :

  • 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 onéreux.
  • 4 : l'établissement propose des services très onéreux.
  Remarque  : La valeur entière de 0, qui indique que le lieu 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 de 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 par catégorie telle que "Restaurants à New York", SearchByTextRequest.RankPreference.RELEVANCE (classement des résultats par pertinence de 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 (classement des résultats par 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 de région utilisé pour formater la réponse, spécifié sous la forme d'un 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 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 affecter 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 des types

  Utilisé avec le paramètre de type "include". Si la valeur est définie 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.

  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.