Text Search (nouvelle version)

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

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

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.

En plus des paramètres obligatoires, Text Search (nouvelle version) 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 (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.

Requêtes Text Search

Une requête Text Search se présente comme suit :

// 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 de champs de manière à 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 SearchByTextRequest objet 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 de résultats 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. Aucun résultat en dehors de cette zone n'est renvoyé.

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

Réponses Text Search

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

  • Une 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.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 dans un objet Place, consultez Accéder aux champs de données de l'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 des pages de résultats supplémentaires sont disponibles. Cette méthode renvoie une valeur booléenne (true ou false).

Lorsque hasNextPage() renvoie la valeur "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 comment la charger.

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 obligatoires pour SearchByTextRequest sont les suivants :

  • Liste de champs

    Spécifiez les champs de données de lieu à renvoyer. Transmettez une liste de Place.Field valeurs spécifiant les champs de données à renvoyer. Il n'existe pas de liste par défaut de 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 uniquement) :

      Place.Field.DISPLAY_NAME*
          * Utilisez-le à la place de Place.Field.NAME (obsolète dans 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 des SKU associés, consultez Champs de données de lieu (nouvelle version).

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

      Place.Field.ACCESSIBILITY_OPTIONS*
          Utilisez-le à 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*
          Utilisez-le à la place de Place.Field.ADDRESS (obsolète).
      Place.Field.GOOGLE_MAPS_URI
      Place.Field.ICON_BACKGROUND_COLOR
      Place.Field.ICON_MASK_URL *
          Utilisez-le à la place de Place.Field.ICON_URL (obsolète).
      Place.Field.LOCATION*
          Utilisez-le à 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 des SKU associés, consultez Champs de données de lieu (nouvelle version).

    • 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-le à 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-le à 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 des SKU associés, consultez Champs de données de lieu (nouvelle version).

    • 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 des SKU associés, consultez Champs de données de lieu (nouvelle version).

    Pour définir le paramètre de la liste de champs, appelez la setPlaceFields() lors de la création de l'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 la requête textuelle, appelez la setTextQuery() lors de la création de l'SearchByTextRequest.

Paramètres facultatifs

Utilisez l' SearchByTextRequest objet 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 du type inclus, appelez la setIncludedType() méthode lors de la création de l'objet SearchByTextRequest.

  • Pondération géographique

    Spécifie une zone dans laquelle effectuer la recherche. Cet emplacement sert de pondération, ce qui signifie que les résultats autour de l'emplacement spécifié peuvent être renvoyés, y compris les résultats en dehors de la zone spécifiée.

    Vous pouvez spécifier une restriction géographique ou une pondération géographique, mais pas les deux. Considérez la restriction géographique comme la spécification de la région dans laquelle les résultats doivent se trouver, et la pondération géographique comme la spécification de la région dans laquelle les résultats seront probablement situés ou à proximité. N'oubliez pas que lorsque vous utilisez la pondération géographique, les résultats peuvent toujours se trouver en dehors de la zone spécifiée.

    Spécifiez la région en tant que fenêtre d'affichage rectangulaire ou en tant que 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 opposés en diagonale. Le point bas marque 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 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 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 Requêtes Text Search.

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

  • Restriction géographique

    Spécifie une zone dans laquelle effectuer la recherche. 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 de la fenêtre d'affichage, consultez la description de la pondération géographique.

    Vous pouvez spécifier une restriction géographique ou une pondération géographique, mais pas les deux. Considérez la restriction géographique comme la spécification de la région dans laquelle les résultats doivent se trouver, et la pondération géographique comme la spécification de la région dans laquelle les résultats doivent se trouver à proximité, mais peuvent être en dehors de la zone.

    Pour définir le paramètre de restriction géographique, appelez la setLocationRestriction() méthode 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 compris entre 1 et 20 (par défaut) inclus.

    Pour définir le paramètre du nombre maximal de résultats, appelez la setMaxResultCount() méthode 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 à 0,5 près. 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 setMinRating() méthode lors de la création de l'objet SearchByTextRequest.

  • Ouvert

    Si la valeur est true, ne renvoyez que les lieux ouverts au moment de l'envoi de la requête. Si la valeur est false, renvoyez tous les établissements quel que soit leur état d'ouverture. 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 "Ouvert", 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 lieux qui proposent des services à tous les niveaux de prix. Pour limiter les résultats aux lieux dont les niveaux de prix sont spécifiques, vous pouvez transmettre une liste de valeurs entières correspondant aux niveaux de prix des lieux que vous souhaitez renvoyer :

    • 1 : le lieu propose des services peu coûteux.
    • 2 : le lieu propose des services à prix modérés.
    • 3 : le lieu propose des services coûteux.
    • 4 : le lieu propose des services très coûteux.

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

  • Préférence de classement

    Spécifie le mode de classement des résultats 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 (classement des résultats par 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 (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 setRankPreference() méthode 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 avoir un effet de pondération 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 régional, 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 loi applicable.

    Pour définir le paramètre de code régional, appelez la setRegionCode() méthode lors de la création de l'objet SearchByTextRequest.

  • Filtrage strict par type

    Utilisé avec le paramètre de type inclus. Lorsque la valeur est définie sur true, seuls les lieux correspondant aux types spécifiés par le type inclus sont renvoyés. Lorsque false (par défaut), 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 par type, appelez la setStrictTypeFiltering() lors de la création de l'objet SearchByTextRequest.