Text Search (nouvelle version)

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". 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 (par exemple, une région, une restriction d'emplacement ou un biais d'emplacement) est défini.

Obtenir une liste de lieux par recherche textuelle

Envoyez une requête de recherche de texte en appelant GMSPlacesClient searchByTextWithRequest:, en transmettant un objet GMSPlaceSearchByTextRequest qui définit les paramètres de 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 incluent les suivants:

• Liste des champs à renvoyer dans l'objet GMSPlace, également appelé masque de champ, comme défini par GMSPlaceProperty. Si vous ne spécifiez pas au moins un champ dans la liste des champs ou si vous omettez la liste des champs, l'appel renvoie une erreur.
• La requête textuelle.

Cet exemple de requête de recherche de texte spécifie que les objets GMSPlace de la réponse contiennent le nom et l'ID du lieu pour chaque objet GMSPlace dans les résultats de recherche. Il filtre également la réponse pour ne renvoyer que des lieux de type "restaurant".

// Create the GMSPlaceSearchByTextRequest object.
let myProperties = [GMSPlaceProperty.name, GMSPlaceProperty.placeID].map {$0.rawValue}
let request = GMSPlaceSearchByTextRequest(textQuery:"pizza in New York", placeProperties:myProperties)
request.isOpenNow = true
request.includedType = "restaurant"
request.maxResultCount = 5
request.minRating = 3.5
request.rankPreference = .distance
request.isStrictTypeFiltering = true
request.locationBias =  GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0)

// Array to hold the places in the response
var placeResults: [GMSPlace] = []

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
  }
  placeResults = results
}

GMSPlacesClient.shared().searchByText(with: request, callback: callback)

// 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.locationBias = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.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 (error != nil) {
        NSLog(@"An error occurred %@", [error localizedDescription]);
        return;
      } else {
        if (placeResults.count > 0) {
          // Get list of places.
          _placeResults = placeResults;
      }
    }
  }
];

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.

Obtenir l'état d'ouverture

L'objet GMSPlacesClient contient une fonction membre appelée isOpenWithRequest (isOpenRequest dans Swift et isPlaceOpenRequest dans GooglePlacesSwift) qui renvoie une réponse indiquant si l'établissement est actuellement ouvert, en fonction de l'heure spécifiée dans l'appel.

Cette méthode utilise un seul argument de type GMSPlaceIsOpenWithRequest qui contient:

• Un objet GMSPlace ou une chaîne spécifiant un ID de lieu. Pour en savoir plus sur la création de l'objet Lieu avec les champs nécessaires, consultez Détails du lieu.
  
• Objet NSDate (Obj-C) ou Date (Swift) facultatif spécifiant l'heure que vous souhaitez vérifier. Si aucune heure n'est spécifiée, la valeur par défaut est l'heure actuelle.
• Une méthode GMSPlaceOpenStatusResponseCallback pour gérer la réponse.
>

La méthode GMSPlaceIsOpenWithRequest nécessite que les champs suivants soient définis dans l'objet GMSPlace:

• GMSPlacePropertyUTCOffsetMinutes
• GMSPlacePropertyBusinessStatus
• GMSPlacePropertyOpeningHours
• GMSPlacePropertyCurrentOpeningHours
• GMSPlacePropertySecondaryOpeningHours

Si ces champs ne sont pas fournis dans l'objet Place ou si vous transmettez un ID de lieu, la méthode utilise GMSPlacesClient GMSFetchPlaceRequest: pour les récupérer.

Réponse isOpenWithRequest

isOpenWithRequest renvoie un objet GMSPlaceIsOpenResponse contenant une valeur booléenne nommée status qui indique si l'établissement est ouvert, fermé ou si son état est inconnu.

Facturation pour isOpenWithRequest

• Les champs GMSPlacePropertyUTCOffsetMinutes et GMSPlacePropertyBusinessStatus sont facturés sous le SKU Data Basic. Le reste des heures d'ouverture est facturé sous le code SKU Place Details (Advanced).
• Si ces champs figurent déjà dans votre objet GMSPlace à la suite d'une demande précédente, vous ne serez pas facturé à nouveau.

Exemple: Envoyer une requête GMSPlaceIsOpenWithRequest

    let isOpenRequest = GMSPlaceIsOpenRequest(place: place, date: nil)
      GMSPlacesClient.shared().isOpen(with: isOpenRequest) { response, error in
        if let error = error {
          // Handle Error
        }
        switch response.status {
          case .open:
            // Handle open
          case .closed:
            // Handle closed
          case .unknown:
            // Handle unknown
        }
      }
        

          GMSPlaceIsOpenRequest *isOpenRequest = [[GMSPlaceIsOpenRequest alloc] initWithPlace:place date:nil];
  
          [[GMSPlacesClient sharedClient] isOpenWithRequest:isOpenRequest callback:^(GMSPlaceIsOpenResponse response, NSError *_Nullable error) {
            if (error) {
              // Handle error
            }
  
            switch (response.status) {
              case GMSPlaceOpenStatusOpen:
                // Handle open
              case GMSPlaceOpenStatusClosed:
                // Handle closed
              case GMSPlaceOpenStatusUnknown:
                // Handle unknown
            }
          }];
          

          let isOpenRequest = IsPlaceOpenRequest(place: place)
          switch await placesClient.isPlaceOpen(with: isOpenRequest) {
            case .success(let isOpenResponse):
              switch isOpenResponse.status {
                case true:
                  // Handle open
                case false:
                  // Handle closed
                case nil:
                  // Handle unknown
            case .failure(let placesError):
              // Handle error
          }
          

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 de 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 renverra une erreur.

  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):

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

  • request.includedType = "bar"
  • request.includedType = "pharmacy"

• isOpenNow

  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.

• isStrictTypeFiltering

  Utilisé avec le paramètre includeType. Lorsque la valeur est true, seuls les lieux correspondant aux types spécifiés par includeType sont renvoyés. Lorsque la valeur est "false" (par défaut), la réponse peut contenir des lieux qui ne correspondent pas aux types spécifiés.

• locationBias

  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 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 à proximité de laquelle les résultats doivent se trouver, mais qui peut être 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 un point central et un 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(40.7, -74.0), 200.0)

  • 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.

• locationRestriction

  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 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 à proximité de laquelle les résultats doivent se trouver, mais qui peut être en dehors de la zone.

• maxResultCount

  Spécifie le nombre maximal de résultats de lieux à renvoyer. Doit être compris entre 1 et 20 (par défaut), inclus.

• minRating

  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.

• priceLevels

  Limiter la recherche aux lieux qui sont marqués à certains niveaux de prix Par défaut, tous les niveaux de prix sont sélectionnés.

  Spécifiez un tableau d'une ou de 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 par catégorie telle que "Restaurants à New York", .relevance (classement des résultats en fonction de la pertinence de la recherche) est défini par défaut. Vous pouvez définir rankPreference sur .relevance ou .distance (classer les résultats par distance).
  • Pour une requête non catégorique 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é 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.

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

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