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 de texte 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 afin de trouver des noms de lieux, des adresses et des Plus Codes. Ainsi, les applications peuvent envoyer des requêtes lors de la frappe pour fournir des suggestions de lieux à la volée.

Les suggestions de lieux sont des lieux (comme 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ée.

Par exemple, vous appelez l'API en utilisant une chaîne contenant une entrée utilisateur partielle, "Spagh", avec une zone de recherche limitée à New York. La réponse contient ensuite une liste de suggestions de lieux correspondant à la chaîne de recherche et à la zone de recherche, comme le restaurant nommé "Cafe Spaghetti", ainsi que des informations 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 envoyer une requête Place Details (New) pour obtenir plus d'informations sur l'une des suggestions de lieux renvoyées.

Requêtes Autocomplete (nouveau)

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 les 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 northWestBounds = CLLocationCoordinate2DMake(40.921628, -73.700051)
let southEastBounds = CLLocationCoordinate2DMake(40.477398, -74.259087)

let filter = GMSAutocompleteFilter()
filter.types = [kGMSPlaceTypeRestaurant]
filter.locationBias = GMSPlaceRectangularLocationOption(northWestBounds, southEastBounds)
    
let request = GMSAutocompleteRequest(query:"Spagh")
request.filter = filter
request.sessionToken = token

GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { ( results, error ) in
      if let error = error {
        print("Autocomplete error: \(error)")
        return
      }
      if let autocompleteResults = results {
        for result in autocompleteResults {
          print("Result \(String(describing: result.placeSuggestion?.placeID)) with \(String(describing: result.placeSuggestion?.attributedFullText))")
        }
      }
    })

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 Autocomplete (nouveau)

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

• placeID
• types: types qui s'appliquent à ce lieu.
• distanceMeters: distance de l'origine.
• attributedFullText: texte complet d'une suggestion, lisible par l'utilisateur.
• attributedPrimaryText: texte principal lisible d'une suggestion.
• attributedSecondaryText: texte secondaire lisible d'une suggestion.
• structuredFormat: nom spécifique et texte permettant de lever l'ambiguïté, comme une ville ou une région.

Paramètres obligatoires

requête

Chaîne de texte à rechercher. Spécifiez des mots et des sous-chaînes complets, des noms de lieux, des adresses et des Plus Codes. Le service de saisie semi-automatique (nouveau) renvoie les résultats correspondant à 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 Table A ou Table 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 ou plusieurs types principaux 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. Pour être inclus dans la réponse, un lieu doit correspondre à l'une des valeurs de type principal spécifiées.

La requête est rejetée avec une erreur INVALID_REQUEST si:

• Vous spécifiez plus de cinq types.
• 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, spécifiées sous la forme d'un tableau de 15 valeurs ccTLD (domaine de premier niveau) à deux caractères maximum. Si elle 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 se trouvent dans la zone d'intersection des deux paramètres.

inputOffset

Décalage de caractère Unicode basé sur zéro indiquant la position du curseur dans input. La position du curseur peut influencer les prédictions renvoyées. S'il est vide, la longueur est définie par défaut sur 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 à proximité de laquelle les résultats doivent se trouver, mais qui peut être en dehors de la zone.

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

• 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 locationBias ou locationRestriction en tant que vue 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). 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 diamétralement opposés. 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 ne comprend qu'un seul point.
• Si low.longitude > high.longitude, la plage de longitude est inversée (le viewport croise la ligne de longitude de 180 degrés).
• Si low.longitude = -180 degrés et high.longitude= 180 degrés, le viewport 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.

low et high doivent être renseignés, et la zone représentée ne doit pas être vide. Un viewport vide génère une erreur.

Par exemple, ce viewport englobe entièrement la ville de New York :

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

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 d'origine à partir duquel calculer la distance en ligne droite jusqu'à la destination (rendue sous la forme distanceMeters). Si cette valeur est omise, la distance en ligne droite ne sera pas renvoyée. Doit être spécifié sous la forme de 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 ccTLD (TLD pour "domaine de premier niveau") à deux caractères. La plupart des codes de 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. Le paramètre peut avoir une incidence sur les résultats en fonction de la législation applicable.

sessionToken

Les jetons de session sont des chaînes générées par l'utilisateur qui suivent les appels de saisie semi-automatique (nouveau) en tant que "sessions". La saisie semi-automatique (nouvelle) utilise des jetons de session pour regrouper les phases de requête et de sélection d'une recherche de 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 (nouvelle)

Utiliser locationRestriction et locationBias

La saisie semi-automatique (nouvelle) utilise la présélection d'adresses IP par défaut pour contrôler la zone de recherche. Avec le biaisage IP, l'API utilise l'adresse IP de l'appareil pour biaiser les résultats. Vous pouvez éventuellement utiliser locationRestriction ou locationBias, mais pas les deux, pour spécifier une zone de recherche.

La restriction d'emplacement spécifie la zone à rechercher. Les résultats 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 d'un rayon de 5 000 mètres centrée 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:"Piz")
request.filter = filter
request.sessionToken = token

GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { ( results, error ) in
      if let error = error {
        print("Autocomplete error: \(error)")
        return
      }
      if let autocompleteResults = results {
        for result in autocompleteResults {
          print("Result \(String(describing: result.placeSuggestion?.placeID)) with \(String(describing: result.placeSuggestion?.attributedFullText))")
        }
      }
    })

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 le biais de localisation, l'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. L'exemple suivant modifie la requête précédente pour utiliser le 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:"Piz")
request.filter = filter
request.sessionToken = token

GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { ( results, error ) in
      if let error = error {
        print("Autocomplete error: \(error)")
        return
      }
      if let autocompleteResults = results {
        for result in autocompleteResults {
          print("Result \(String(describing: result.placeSuggestion?.placeID)) with \(String(describing: result.placeSuggestion?.attributedFullText))")
        }
      }
    })

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 types pour limiter les résultats d'une requête à un type spécifique, comme indiqué dans les tableaux A et B. Vous pouvez spécifier un tableau de cinq valeurs maximum. Si elle 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 types 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
      if let error = error {
        print("Autocomplete error: \(error)")
        return
      }
      if let autocompleteResults = results {
        for result in autocompleteResults {
          print("Result \(String(describing: result.placeSuggestion?.placeID)) with \(String(describing: result.placeSuggestion?.attributedFullText))")
        }
      }
    })

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 sous la forme distanceMeters.

Cet exemple définit l'origine 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
      if let error = error {
        print("Autocomplete error: \(error)")
        return
      }
      if let autocompleteResults = results {
        for result in autocompleteResults {
          print("Result \(String(describing: result.placeSuggestion?.placeID)) with \(String(describing: result.placeSuggestion?.attributedFullText)) and distance: \(String(describing: result.placeSuggestion?.distanceMeters))")
        }
      }
    })

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) même sans carte. Si vous affichez une carte, il doit s'agir d'une carte Google. Lorsque vous affichez des suggestions issues du service de saisie semi-automatique (nouveau) sans carte, vous devez inclure le logo Google affiché sur la même ligne que le champ de recherche/les résultats. Pour en savoir plus, consultez Afficher le logo et les attributions Google.