Text Search (nouvelle version)

Une recherche de texte renvoie des informations sur un ensemble de lieux en fonction d'une chaîne. Par exemple, "pizza à New York", "magasins 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 à toute pondération de localisation définie.

Ce service est particulièrement utile pour effectuer des requêtes d'adresse ambiguës dans un système automatisé, et les composants de la chaîne qui ne sont pas des adresses peuvent correspondre à des établissements et à des adresses. Les adresses au format incorrect ou les requêtes qui incluent des composants qui ne sont pas des adresses, tels que des noms d'entreprise, sont des exemples de requêtes d'adresse ambiguës. Les requêtes comme dans les deux premiers exemples peuvent ne renvoyer aucun résultat, sauf si un lieu (région, restriction d'emplacement ou biais de localisation, par exemple) est défini.

"10 High Street, Royaume-Uni" ou "123 Main Street, États-Unis" Plusieurs "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 "chaînes de restaurants" à New York ; pas d'adresse postale ni même de nom de rue.
"10 High Street, Escher UK" ou "123 Main Street, Pleasanton US" Une seule "High Street" dans la ville d'Esccher au Royaume-Uni et une seule "Main Street" dans la ville de Pleasanton, aux États-Unis.
"NomRestaurantUnique New York" Un seul établissement portant ce nom à New York ; aucune adresse postale n'est nécessaire à différencier.
"pizzerias à New York" Cette requête contient la restriction d'emplacement, et "pizzeria" 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:, 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, telle que définie par GMSPlaceProperty. 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.
  • La requête textuelle.

Cet exemple de requête de recherche de texte indique que les objets GMSPlace de la 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 Text Search

L'API Text Search renvoie un tableau de correspondances sous la forme d'objets GMSPlace, avec un objet GMSPlace par lieu correspondant.

Avec les champs de données, l'objet GMSPlace de la réponse contient les fonctions de membre suivantes:

  • isOpen calcule si un lieu est ouvert à un horaire donné.
  • 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 sont une bonne pratique à appliquer pour vous assurer de ne pas demander de données inutiles. Vous pouvez ainsi réduire 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 et GMSPlacePropertyTakeout

  • textQuery

    Chaîne de texte sur laquelle doit porter la recherche. Par exemple: "restaurant", "123 Main Street" ou "meilleur lieu à 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 est false, la fonction renvoie tous les établissements, qu'ils soient ouverts ou non. Les lieux sans horaires d'ouverture dans la base de données Google Places sont renvoyés si vous définissez ce paramètre sur false.

  • isStrictTypeFiltering

    Utilisé avec le paramètre includeType. Lorsque ce paramètre est défini sur true, seuls les lieux correspondant aux types spécifiés par includeType 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.

  • locationBias

    Spécifie une zone à rechercher. Cette position sert de pondération : les résultats situés autour du lieu spécifié peuvent être renvoyés, y compris ceux situés en dehors de la zone spécifiée.

    Vous pouvez spécifier locationRestriction ou locationBias, mais pas les deux. Considérez locationRestriction comme spécifiant la région dans laquelle les résultats doivent se trouver et locationBias comme spécifiant la région dans laquelle les résultats doivent être à proximité, mais peuvent se trouver en dehors de la zone.

    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 son point central et son rayon en mètres. Le rayon doit être compris entre 0,0 et 50 000,0 inclus. Le rayon par défaut est 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 haut opposés en diagonale. Le point bas représente 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 ses limites. 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 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 longitude est vide.
      • Si low.latitude > high.latitude, la plage de latitudes est vide.

  • locationRestriction

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

    Vous pouvez spécifier locationRestriction ou locationBias, mais pas les deux. Considérez locationRestriction comme spécifiant la région dans laquelle les résultats doivent se trouver et locationBias comme spécifiant la région dans laquelle les résultats doivent être à proximité, mais peuvent se trouver en dehors de la 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

    restreint les résultats aux seuls résultats 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. Exemples: 0, 0,5, 1,0, ... , 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.

  • priceLevels

    Limitez la recherche aux lieux indiqués à certains niveaux de prix. 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 le 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", .relevance (classer les résultats en fonction de la pertinence de la recherche) est la valeur par défaut. Vous pouvez définir rankPreference 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.

  • regionCode

    Code de région utilisé pour mettre en forme la réponse, spécifié en tant que valeur de 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 dans la réponse correspond au code de la région, ce dernier 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.

Afficher les mentions dans votre application

Lorsque votre application affiche des informations obtenues à partir de GMSPlacesClient, comme 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 de cinq objets GMSPlaceReview maximum. Chaque objet GMSPlaceReview peut contenir des attributions et des attributions d'auteurs. Si vous affichez l'avis dans votre application, vous devez également afficher toute attribution ou attribution d'auteur.

Pour en savoir plus, consultez la documentation sur les attributions.