Place Autocomplete (nouveau)

Le service Autocomplete (New) est une API iOS qui renvoie des suggestions de lieux en réponse à une requête. Dans la requête, spécifiez une chaîne de recherche textuelle et des limites géographiques qui contrôlent la zone de recherche.

Le service de saisie semi-automatique (nouveau) peut établir une correspondance avec des mots complets et des sous-chaînes de l'entrée, pour résoudre les noms de lieux, les adresses et les plus codes. Les applications peuvent ainsi envoyer des requêtes au fur et à mesure que l'utilisateur saisit sa requête pour suggérer des lieux à la volée.

Les suggestions de lieux correspondent à des lieux (tels que des établissements, des adresses et des points d'intérêt) en fonction de la chaîne de texte saisie et de la zone de recherche spécifiées.

Par exemple, vous appelez l'API en utilisant comme entrée une chaîne contenant une entrée utilisateur partielle, "Sicilian piz", avec la zone de recherche limitée à San Francisco, en Californie. La réponse contient ensuite une liste de suggestions de lieux correspondant à la chaîne de recherche et à la zone de recherche, par exemple le restaurant nommé "Sicilian Pizza Kitchen", ainsi que des détails sur le lieu.

Les suggestions de lieux renvoyées sont conçues pour être présentées à l'utilisateur afin qu'il puisse sélectionner le lieu souhaité. Vous pouvez effectuer une requête Place Details (New) pour obtenir plus d'informations sur les suggestions de lieux renvoyées.

Requêtes Autocomplete (nouvelle)

Créez une requête de saisie semi-automatique en appelant une méthode sur GMSPlaceClient. Vous pouvez transmettre des paramètres dans l'objet GMSAutocompleteRequest. La réponse fournit des suggestions de saisie semi-automatique dans un objet GMSAutocompletePlaceSuggestion.

La clé API et les paramètres query sont obligatoires. Vous pouvez également inclure GMSAutocompleteSessionToken pour associer des requêtes à une session de facturation et GMSAutocompleteFilter pour les appliquer aux résultats.

Pour en savoir plus sur les paramètres obligatoires et facultatifs, consultez la section Paramètres de ce document.

let token = GMSAutocompleteSessionToken()

let northEastBounds = CLLocationCoordinate2DMake(37.388162, -122.088137)
let southWestBounds = CLLocationCoordinate2DMake(37.395804, -122.077023)

let filter = GMSAutocompleteFilter()
filter.types = [kGMSPlaceTypeRestaurant]
filter.locationBias = GMSPlaceRectangularLocationOption(northEastBounds, southWestBounds)
    
let request = GMSAutocompleteRequest(query:"Sicilian piz")
request.filter = filter
request.sessionToken = token
GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { results, error in
  // Handle response
})

CLLocationCoordinate2D northEast = CLLocationCoordinate2DMake(37.388162, -122.088137);
CLLocationCoordinate2D southWest = CLLocationCoordinate2DMake(37.395804, -122.077023);

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.types = @[ kGMSPlaceTypeRestaurant ];
filter.locationBias = GMSPlaceRectangularLocationOption(northEast, southWest);
GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Sicilian piz"];
request.sessionToken = token;
request.filter = filter;

[[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){
  // Handle response
  for (GMSAutocompleteSuggestion *suggestion in results) {
    if (suggestion.placeSuggestion) {
      // Show place suggestion data.
    }
  }
}];

let center = (37.3913916, -122.0879074)
let northEast = (37.388162, -122.088137)
let southWest = (37.395804, -122.077023)

let bias = RectangularCoordinateRegion(northEast: northEast, southWest: southWest)
let filter = AutocompleteFilter(types: [ .restaurant ], origin: center, coordinateRegionBias: bias)

let autocompleteRequest = AutocompleteRequest(query: "Sicilian piz", filter: filter)
switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) {
case .success(let autocompleteSuggestions):
  // Handle suggestions.
case .failure(let placesError):
  // Handle error.
}

Réponses de la saisie semi-automatique (nouvelle version)

La saisie semi-automatique renvoie un tableau contenant jusqu'à cinq instances GMSAutocompleteSuggestion. Le tableau contient:

• placeID
• types: types qui s'appliquent à ce lieu.
• distanceMeters: distance depuis le point de départ.
• attributedFullText: texte complet d'une suggestion, lisible par l'humain.
• attributedPrimaryText: texte principal d'une suggestion, lisible par l'humain.
• attributedSecondaryText: texte secondaire lisible d'une suggestion.
• structuredFormat: nom spécifique et texte de distinction, comme la ville ou la région.

Paramètres obligatoires

requête

Chaîne de texte dans laquelle effectuer la recherche. Spécifiez des mots complets et des sous-chaînes, des noms de lieux, des adresses et des plus codes. Le service de saisie semi-automatique (nouveau) renvoie les correspondances de candidats en fonction de cette chaîne et les classe en fonction de leur pertinence estimée.

Paramètres facultatifs

Types

Un lieu ne peut être associé qu'à un seul type principal parmi les types du Tableau A ou du Tableau B. Par exemple, le type principal peut être mexican_restaurant ou steak_house.

Par défaut, l'API renvoie tous les lieux en fonction du paramètre input, quelle que soit la valeur de type principal associée au lieu. Limitez les résultats à un certain type principal en transmettant le paramètre types.

Utilisez ce paramètre pour spécifier jusqu'à cinq valeurs de type du Tableau A ou du Tableau B. Un lieu doit correspondre à l'une des valeurs de type principal spécifiées pour être inclus dans la réponse.

La requête est rejetée avec une erreur INVALID_REQUEST dans les cas suivants:

• Plus de cinq types sont spécifiés.
• Tous les types non reconnus sont spécifiés.

pays

N'incluez que les résultats de la liste des régions spécifiées, sous la forme d'un tableau comportant jusqu'à 15 valeurs ccTLD ("domaine de premier niveau") à deux caractères. Si cette valeur est omise, aucune restriction n'est appliquée à la réponse. Par exemple, pour limiter les régions à l'Allemagne et à la France:

let filter = GMSAutocompleteFilter()
filter.countries = ["DE", "FR"]

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.countries = @[ @"DE", @"FR" ];

let filter = AutocompleteFilter(countries: ["DE", "FR"])
  

Si vous spécifiez à la fois locationRestriction et countries, les résultats sont situés dans la zone d'intersection des deux paramètres.

inputOffset

Décalage du caractère Unicode de base zéro indiquant la position du curseur dans input. La position du curseur peut influencer les prédictions renvoyées. Si ce champ est vide, la longueur par défaut est input.

locationBias ou locationRestriction

Vous pouvez spécifier locationBias ou locationRestriction, mais pas les deux, pour définir la zone de recherche. 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 se trouver, mais qui peuvent se trouver en dehors de cette zone.

• locationBias spécifie une zone à rechercher. Cet emplacement sert de biais, ce qui signifie que des résultats situés à proximité du lieu spécifié peuvent être renvoyés, y compris des résultats situés en dehors de la zone spécifiée.

• 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 locationBias ou locationRestriction en tant que fenêtre d'affichage rectangulaire ou en tant que 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. La valeur par défaut est 0.0. Pour locationRestriction, vous devez définir le rayon sur une valeur supérieure à 0,0. Sinon, la requête ne renvoie aucun résultat.

Exemple :

let center = CLLocationCoordinate2DMake(40.730610, -73.935242)
let radius = 1000.0

filter.locationBias = GMSPlaceCircularLocationOption(center, radius)

CLLocationCoordinate2D center = CLLocationCoordinate2DMake(40.730610, -73.935242);
radius = 1000.0;

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.locationBias = GMSPlaceCircularLocationOption(center, radius);

let center = CLLocationCoordinate2DMake(40.477398, -74.259087)

let bias = CircularCoordinateRegion(center: center, radius: 1000.0)

let filter = AutocompleteFilter(coordinateRegionBias: bias)      
  

Un rectangle est une fenêtre d'affichage de latitude-longitude, représentée par deux points low et high opposés en diagonale. Une fenêtre d'affichage est considérée comme fermée (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 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 longitudes est vide.

Les champs low et high doivent tous les deux être renseignés, et la zone représentée ne peut pas être vide. Une fenêtre d'affichage vide entraîne une erreur.

Par exemple, cette fenêtre d'affichage englobe entièrement New York:

let high = CLLocationCoordinate2DMake(40.477398, -74.259087)
let low = CLLocationCoordinate2DMake(40.921628, -73.700051)

let filter = GMSAutocompleteFilter()
filter.locationBias = GMSPlaceRectangularLocationOption(high, low)

CLLocationCoordinate2D high = CLLocationCoordinate2DMake(40.477398, -74.259087);
CLLocationCoordinate2D low = CLLocationCoordinate2DMake(440.921628, -73.700051);

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.locationBias = GMSPlaceRectangularLocationOption(high, low);

let northEast = CLLocationCoordinate2DMake(40.477398, -74.259087)
let southWest = CLLocationCoordinate2DMake(40.921628, -73.700051)

let filter = AutocompleteFilter(coordinateRegionBias: bias)
  

origine

Point de départ à partir duquel calculer la distance en ligne droite jusqu'à la destination (renvoyé sous la forme distanceMeters). Si cette valeur est omise, la distance en ligne droite n'est pas renvoyée. Doit être spécifié en tant que coordonnées de latitude et de longitude:

let filter = GMSAutocompleteFilter()
filter.origin =  CLLocation(latitude: 37.395804, longitude:  -122.077023)
 

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];

filter.origin = [[CLLocation alloc] initWithLatitude:37.395804 longitude:-122.077023];

let filter = AutocompleteFilter(origin: CLLocation(latitude: 37.395804, longitude:  -122.077023))
  

regionCode

Code régional utilisé pour mettre en forme la réponse, spécifié sous la forme d'une valeur à deux caractères ccTLD ("domaine de premier niveau"). La plupart des codes ccTLD 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").

Si vous spécifiez un code de région non valide, l'API renvoie une erreur INVALID_ARGUMENT. Ce paramètre peut avoir un impact sur les résultats en fonction du droit applicable.

sessionToken

Les jetons de session sont des chaînes générées par l'utilisateur qui suivent les appels de la saisie semi-automatique (nouveau) comme des "sessions". La saisie semi-automatique (nouvelle version) utilise des jetons de session pour regrouper les phases de requête et de sélection d'une recherche avec saisie semi-automatique d'un utilisateur dans une session distincte à des fins de facturation. Pour en savoir plus, consultez la section Jetons de session.

Exemples de saisie semi-automatique (nouveau)

Utiliser locationRestriction et locationBias

La saisie semi-automatique (nouvelle version) utilise par défaut la pondération de l'adresse IP pour contrôler la zone de recherche. Avec la pondération de l'adresse IP, l'API utilise l'adresse IP de l'appareil pour pondérer les résultats. Vous pouvez éventuellement utiliser locationRestriction ou locationBias, mais pas les deux, pour spécifier une zone à rechercher.

Une restriction géographique permet de spécifier la zone dans laquelle effectuer la recherche. Les résultats situés en dehors de la zone spécifiée ne sont pas renvoyés. L'exemple suivant utilise une restriction d'emplacement pour limiter la requête à une restriction d'emplacement circulaire avec un rayon de 5 000 mètres centré sur San Francisco:

let token = GMSAutocompleteSessionToken()

let center = CLLocationCoordinate2DMake(37.775061, -122.419400)
let radius = 5000.0

let filter = GMSAutocompleteFilter()
filter.locationRestriction = GMSPlaceCircularLocationOption(center, radius)
    
let request = GMSAutocompleteRequest(query:"Sicilian piz")
request.filter = filter
request.sessionToken = token
GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { results, error in
  // Handle response
  })

CLLocationCoordinate2D center = CLLocationCoordinate2DMake(37.775061, -122.419400);
radius = 5000.0;

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.locationRestriction = GMSPlaceCircularLocationOption(center, radius);
GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Sicilian piz"];
request.sessionToken = token;
request.filter = filter;

[[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){
  // Handle response
  for (GMSAutocompleteSuggestion *suggestion in results) {
    if (suggestion.placeSuggestion) {
      // Show place suggestion data.
    }
  }
}];

let center = (37.775061, -122.419400)
let radius = 5000.0
let restriction = CircularCoordinateRegion(center: center, radius: radius)
let filter = AutocompleteFilter(coordinateRegionRestriction: restriction)
let token = AutocompleteSessionToken()

let autocompleteRequest = AutocompleteRequest(query: "Sicilian piz", sessionToken: token, filter: filter)
switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) {
case .success(let autocompleteSuggestions):
  for suggestion in autocompleteSuggestions {
    switch suggestion {
    case .place:
      // Show place suggestion data.
    }
  }
case .failure(let placesError):
  // Handle error.
}
  

Avec un biais de localisation, la localisation sert de biais, ce qui signifie que des résultats situés autour du lieu spécifié peuvent être renvoyés, y compris des résultats situés en dehors de cette zone. L'exemple suivant modifie la requête précédente pour utiliser un biais de localisation:

let token = GMSAutocompleteSessionToken()

let center = CLLocationCoordinate2DMake(37.775061, -122.419400)
let radius = 5000.0

let filter = GMSAutocompleteFilter()
filter.locationBias = GMSPlaceCircularLocationOption(center, radius)
    
let request = GMSAutocompleteRequest(query:"Sicilian piz")
request.filter = filter
request.sessionToken = token
GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { results, error in
  // Handle response
})

CLLocationCoordinate2D center = CLLocationCoordinate2DMake(37.775061, -122.419400);
radius = 5000.0;

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.locationBias = GMSPlaceCircularLocationOption(center, radius);
GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Sicilian piz"];
request.sessionToken = token;
request.filter = filter;

[[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){
  // Handle response
  for (GMSAutocompleteSuggestion *suggestion in results) {
    if (suggestion.placeSuggestion) {
      // Show place suggestion data.
    }
  }
}];

let center = (37.775061, -122.419400)
let radius = 5000.0
let bias = CircularCoordinateRegion(center: center, radius: radius)
let filter = AutocompleteFilter(coordinateRegionBias: bias)
let token = AutocompleteSessionToken()

let autocompleteRequest = AutocompleteRequest(query: "Sicilian piz", sessionToken: token, filter: filter)
switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) {
case .success(let autocompleteSuggestions):
  for suggestion in autocompleteSuggestions {
    switch suggestion {
    case .place:
      // Show place suggestion data.
    }
  }
case .failure(let placesError):
  // Handle error.
}
  

Types d'utilisation

Utilisez le paramètre de types pour limiter les résultats d'une requête à un certain type, comme indiqué dans le Tableau A et le Tableau B. Vous pouvez spécifier un tableau contenant jusqu'à cinq valeurs. Si cette valeur est omise, tous les types sont renvoyés.

L'exemple suivant spécifie une chaîne de requête "Soccer" et utilise le paramètre de type pour limiter les résultats aux établissements de type "sporting_goods_store":

let token = GMSAutocompleteSessionToken()

let filter = GMSAutocompleteFilter()
filter.types = ["sporting_goods_store"]
    
let request = GMSAutocompleteRequest(query:"Soccer")
request.filter = filter
request.sessionToken = token
GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { results, error in
  // Handle response
})

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.types = @[ "sporting_goods_store" ];
GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Soccer"];
request.sessionToken = token;
request.filter = filter;

[[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){
  // Handle response
  for (GMSAutocompleteSuggestion *suggestion in results) {
    if (suggestion.placeSuggestion) {
      // Show place suggestion data.
    }
  }
}];

let filter = AutocompleteFilter(types: [ PlaceType(rawValue: "sporting_goods_store") ])
let token = AutocompleteSessionToken()

let autocompleteRequest = AutocompleteRequest(query: "Soccer", sessionToken: token, filter: filter)
switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) {
case .success(let autocompleteSuggestions):
  for suggestion in autocompleteSuggestions {
    switch suggestion {
    case .place:
      // Show place suggestion data.
    }
  }
case .failure(let placesError):
  // Handle error.
}
    

Utiliser l'origine

Lorsque vous incluez le paramètre origin dans la requête, spécifié en tant que coordonnées de latitude et de longitude, l'API inclut la distance en ligne droite entre le point de départ et la destination dans la réponse. La réponse renvoie la distance au format distanceMeters.

Dans l'exemple ci-dessous, le point de départ est défini sur le centre de San Francisco:

let token = GMSAutocompleteSessionToken()

let origin = CLLocation(latitude: 37.7749, longitude: -122.4194)

let filter = GMSAutocompleteFilter()

filter.origin =  origin
    
let request = GMSAutocompleteRequest(query:"Amoeba")
request.filter = filter
request.sessionToken = token
GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { results, error in
  // Handle response
})

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.origin = [[CLLocation alloc] initWithLatitude:37.395804 longitude:-122.077023];
GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Amoeba"];
request.sessionToken = token;
request.filter = filter;

[[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){
  // Handle response
  for (GMSAutocompleteSuggestion *suggestion in results) {
    if (suggestion.placeSuggestion) {
      // Show place suggestion data.
      }
    }
}];

let filter = AutocompleteFilter(origin: CLLocation(latitude: 37.7749, longitude: -122.4194))
let token = AutocompleteSessionToken()

let autocompleteRequest = AutocompleteRequest(query: "Amoeba", sessionToken: token, filter: filter)
switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) {
case .success(let autocompleteSuggestions):
  for suggestion in autocompleteSuggestions {
    switch suggestion {
    case .place:
      // Show place suggestion data.
    }
  }
case .failure(let placesError):
  // Handle error.
}
  

Attributions

Vous pouvez utiliser la saisie semi-automatique (nouvelle version) même sans carte. Si vous affichez une carte, il doit s'agir d'une carte Google. Lorsque vous affichez des suggestions du service Autocomplete (New) sans carte, vous devez inclure le logo Google affiché de façon intégrée dans le champ et les résultats de recherche. Pour en savoir plus, consultez Afficher le logo Google et les mentions légales.