Text Search 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, tels que des 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, sauf si une zone géographique (telle qu'une région, une restriction ou un biais de localisation) est définie.
"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. |
"Chaîne de restaurants Paris" | Plusieurs établissements de type "Chaîne de restaurants" à 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. |
Obtenir une liste de lieux par recherche textuelle
Effectuez une requête Text Search en appelant GMSPlacesClient
searchByTextWithRequest:
et en transmettant un objet GMSPlaceSearchByTextRequest
qui définit les paramètres de la requête et une méthode de rappel, de type GMSPlaceSearchByTextResultCallback
, pour gérer la réponse.
L'objet GMSPlaceSearchByTextRequest
spécifie tous les paramètres obligatoires et facultatifs de la requête. Les paramètres obligatoires sont les suivants:
- Liste des champs à renvoyer dans l'objet
GMSPlace
, également appelé masque de champ, tel que défini parGMSPlaceProperty
. Si vous ne spécifiez pas au moins un champ dans la liste des champs ou si vous omettez cette liste, l'appel renvoie une erreur. - Requête textuelle.
Cet exemple de requête de recherche de texte spécifie que les objets GMSPlace
de réponse contiennent le nom et l'ID de lieu de chaque objet GMSPlace
dans les résultats de la recherche. Il filtre également la réponse pour ne renvoyer que les lieux de type "restaurant".
Swift
// Create the GMSPlaceSearchByTextRequest object. let placeProperties: [GMSPlaceProperty] = [GMSPlacePropertyName, GMSPlacePropertyPlaceID]; let request = GMSPlaceSearchByTextRequest(textQuery:"pizza in New York" placeProperties:placeProperties) request.isOpenNow = true request.includedType = "restaurant" request.maxResultCount = 5 request.minRating = 3.5 request.rankPreference = .distance request.isStrictTypeFiltering = true request.priceLevels = [GMSPlacesPriceLevel.moderate.rawValue, GMSPlacesPriceLevel.cheap.rawValue] request.locationRestriction = GMSPlaceRectangularLocationOption( CLLocationCoordinate2D(latitude: 20, longitude: 30), CLLocationCoordinate2D(latitude: 40, longitude: 50) ) // Array to hold the places in the response placeResults = []; let callback: GMSPlaceSearchByTextResultCallback = { [weak self] results, error in guard let self, error == nil else { if let error { print(error.localizedDescription) } return } guard let results = results as? [GMSPlace] else { return } self.placeResults = results } GMSPlacesClient.shared().searchByTextWithRequest(with: request, callback: callback)
Objective-C
// Create the GMSPlaceSearchByTextRequest object. GMSPlaceSearchByTextRequest *request = [[GMSPlaceSearchByTextRequest alloc] initWithTextQuery:@"pizza in New York" placeProperties:@[GMSPlacePropertyName, GMSPlacePropertyPlaceID]]; request.isOpenNow = YES; request.includedType = @"restaurant"; request.maxResultCount = 5; request.minRating = 3.5; request.rankPreference = GMSPlaceSearchByTextRankPreferenceDistance; request.isStrictTypeFiltering = YES; request.priceLevels = @[ @(kGMSPlacesPriceLevelFree), @(kGMSPlacesPriceLevelCheap) ]; request.locationRestriction = GMSPlaceRectangularLocationOption( CLLocationCoordinate2DMake(20, 30), CLLocationCoordinate2DMake(40, 50)); request.locationBias = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(20, 30), 2.0); // Array to hold the places in the response _placeResults = [NSArray array]; // Create the GMSPlaceSearchByTextRequest object. [_placesClient searchByTextWithRequest:request callback:^(NSArray<GMSPlace *> _Nullable placeResults, NSError * _Nullable error) { if (placeResults.count > 0) { // Get list of places. _placeResults = placeResults; } }];
GooglePlacesSwift
let restriction = RectangularLocationRestriction( northEast: CLLocationCoordinate2D(latitude: 20, longitude: 30), southWest: CLLocationCoordinate2D(latitude: 40, longitude: 50) ) let searchByTextRequest = SearchByTextRequest( textQuery: "pizza in New York", placeProperties: [ .name, .placeID ], locationRestriction: restriction, includedType: .restaurant, maxResultCount: 5, minRating: 3.5, priceLevels: [ .moderate, .inexpensive ], isStrictTypeFiltering: true ) switch await placesClient.searchByText(with: searchByTextRequest) { case .success(let places): // Handle places case .failure(let placesError): // Handle error }
Réponses de Text Search
L'API Text Search renvoie un tableau de correspondances sous la forme d'objets GMSPlace
, avec un objet GMSPlace
par lieu correspondant.
Outre les champs de données, l'objet GMSPlace
de la réponse contient les fonctions membres suivantes:
-
isOpen
calcule si un lieu est ouvert à l'heure donnée. isOpenAtDate
calcule si un lieu est ouvert à une date donnée.
Paramètres obligatoires
Utilisez l'objet GMSPlaceSearchByTextRequest
pour spécifier les paramètres requis pour la recherche.
-
Liste des champs
Spécifiez les propriétés des données de lieu à renvoyer. Transmettez une liste de propriétés
GMSPlace
spécifiant les champs de données à renvoyer. Si vous omettez le masque de champ, la requête renvoie une erreur.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):
GMSPlacePropertyPlaceID
,GMSPlacePropertyName
Les champs suivants déclenchent le SKU Text Search (Basic):
GMSPlacePropertyAddressComponents
,GMSPlacePropertyBusinessStatus
,GMSPlacePropertyFormattedAddress
,GMSPlacePropertyIconBackgroundColor
,GMSPlacePropertyIconImageURL
,GMSPlacePropertyCoordinate
,GMSPlacePropertyPhotos
,GMSPlacePropertyPlusCode
,GMSPlacePropertyTypes
,GMSPlacePropertyUTCOffsetMinutes
,GMSPlacePropertyViewport
,GMSPlacePropertyWheelchairAccessibleEntrance
Les champs suivants déclenchent le SKU Text Search (Advanced):
GMSPlacePropertyCurrentOpeningHours
,GMSPlacePropertySecondaryOpeningHours
,GMSPlacePropertyPhoneNumber
,GMSPlacePropertyPriceLevel
,GMSPlacePropertyRating
,GMSPlacePropertyOpeningHours
,GMSPlacePropertyUserRatingsTotal
,GMSPlacePropertyWebsite
Les champs suivants déclenchent le SKU Text Search (Preferred):
GMSPlacePropertyCurbsidePickup
,GMSPlacePropertyDelivery
,GMSPlacePropertyDineIn
,GMSPlacePropertyEditorialSummary
,GMSPlacePropertyReservable
,GMSPlacePropertyReviews
,GMSPlacePropertyServesBeer
,GMSPlacePropertyServesBreakfast
,GMSPlacePropertyServesBrunch
,GMSPlacePropertyServesDinner
,GMSPlacePropertyServesLunch
,GMSPlacePropertyServesVegetarianFood
,GMSPlacePropertyServesWine
,GMSPlacePropertyTakeout
-
textQuery
Chaîne de texte sur laquelle doit porter la recherche, par exemple "restaurant", "123 Main Street" ou "meilleur endroit à visiter à San Francisco".
Paramètres facultatifs
Utilisez l'objet GMSPlaceSearchByTextRequest
pour spécifier les paramètres facultatifs de la recherche.
includedType
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 :
request.includedType = "bar"
request.includedType = "pharmacy"
isOpenNow
Si la valeur est
true
, ne renvoie que les lieux ouverts au moment de l'envoi de la requête. Si la valeur estfalse
, 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 surfalse
.isStrictTypeFiltering
Utilisé avec le paramètre
includeType
. Lorsque ce paramètre est défini surtrue
, seuls les lieux correspondant aux types spécifiés parincludeType
sont renvoyés. Si la valeur est "false", la réponse peut contenir des lieux ne correspondant pas aux types spécifiés.locationBias
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
locationRestriction
oulocationBias
, mais pas les deux. ConsidérezlocationRestriction
comme spécifiant la région dans laquelle les résultats doivent se trouver, etlocationBias
comme spécifiant la région dans laquelle les résultats doivent se trouver, mais qui peuvent se trouver en dehors de cette zone.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. Le rayon par défaut est de 0,0. Exemple :
request.locationBias = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(latitude: 20, longitude: 30), radius: 2.0)
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 ethigh.longitude
= 180 degrés, la fenêtre d'affichage inclut toutes les longitudes. - Si
low.longitude
= 180 degrés ethigh.longitude
= -180 degrés, la plage de longitudes est vide. - Si
low.latitude
>high.latitude
, la plage de latitudes est vide.
- Si
locationRestriction
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. Consultez la description de
locationBias
pour en savoir plus sur la définition de la fenêtre d'affichage.Vous pouvez spécifier
locationRestriction
oulocationBias
, mais pas les deux. ConsidérezlocationRestriction
comme spécifiant la région dans laquelle les résultats doivent se trouver, etlocationBias
comme spécifiant la région dans laquelle les résultats doivent se trouver, mais qui peuvent se trouver en dehors de cette zone.-
maxResultCount
Spécifie le nombre maximal de résultats de lieu à renvoyer. Doit être comprise entre 1 et 20 (par défaut) inclus.
minRating
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.
-
priceLevels
Limitez la recherche aux lieux pour lesquels des tarifs s'appliquent. Par défaut, tous les niveaux de prix sont sélectionnés.
Spécifiez un tableau contenant une ou plusieurs valeurs définies par
PriceLevel
.Exemple :
request.priceLevels = [GMSPlacesPriceLevel.moderate.rawValue, GMSPlacesPriceLevel.cheap.rawValue]
rankPreference
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",
.relevance
(classer les résultats en fonction de la pertinence de la recherche) est la valeur par défaut. Vous pouvez définirrankPreference
sur.relevance
ou.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
rankPreference
.
- Pour une requête catégorielle telle que "Restaurants à New York",
regionCode
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.
Afficher les mentions dans votre application
Lorsque votre application affiche des informations obtenues à partir de GMSPlacesClient
, telles que des photos et des avis, elle doit également afficher les attributions requises.
Par exemple, la propriété reviews
de l'objet GMSPlacesClient
contient un tableau comportant jusqu'à cinq objets GMSPlaceReview
. Chaque objet GMSPlaceReview
peut contenir des attributions et des attributions d'auteurs.
Si vous affichez l'avis dans votre application, vous devez également afficher la mention d'attribution ou d'auteur.
Pour en savoir plus, consultez la documentation sur les attributions.