Saisie semi-automatique (nouveau)

Sélectionnez une plate-forme : Android iOS JavaScript Services Web

Autocomplete (nouveau) renvoie des prédictions de lieu dans Réponse à une requête incluant une chaîne de recherche textuelle et des limites géographiques qui contrôlent la zone de recherche. La saisie semi-automatique peut correspondre sur des mots complets et des sous-chaînes de l'entrée, pour identifier les noms de lieux, les adresses plus codes. Votre application peut envoyer des requêtes lors de la saisie de l'utilisateur, afin de fournir des prédictions de lieux et de requêtes à la volée.

Par exemple, vous appelez la saisie semi-automatique en utilisant comme entrée 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 alors une liste de lieux prédictions correspondant à la chaîne de recherche et à la zone de recherche, par exemple le restaurant nommée "Sicilian Pizza Kitchen".

Les prédictions de lieu renvoyées sont conçues pour être présentées à l'utilisateur pour sélectionner le lieu souhaité. Vous pouvez créer un Place Details (Nouveau) demandez-en plus des informations sur les prédictions de lieu renvoyées.

Requêtes Autocomplete (nouvelle)

Votre application peut obtenir une liste de noms de lieux suggérés et/ou à partir de l'API de saisie semi-automatique en appelant PlacesClient.findAutocompletePredictions(), en transmettant FindAutocompletePredictionsRequest . L'exemple ci-dessous illustre un appel complet à PlacesClient.findAutocompletePredictions()

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Sicilian piz")
            .setRegionCode("ES")
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

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

L'API renvoie une FindAutocompletePredictionsResponse dans un Task La FindAutocompletePredictionsResponse contient une liste pouvant contenir jusqu'à cinq AutocompletePrediction objets représentant des lieux prédits. La liste peut être vide en l'absence de un lieu connu correspondant à la requête et aux critères de filtre.

Pour chaque lieu prédit, vous pouvez appeler les méthodes suivantes afin de récupérer le lieu détails:

  • getFullText(CharacterStyle) renvoie le texte complet d'une description de lieu. Il s'agit d'une combinaison texte principal et secondaire. Exemple : "Tour Eiffel, avenue Anatole France, Paris, France". De plus, cette méthode vous permet de mettre en évidence les sections description qui correspondent à la recherche avec le style de votre choix, en utilisant CharacterStyle Le paramètre CharacterStyle est facultatif. Définissez-le sur "null" si vous n'avez pas besoin aucune mise en surbrillance.
  • getPrimaryText(CharacterStyle) renvoie le texte principal décrivant un lieu. Il s'agit généralement du nom à un emplacement. Exemples : "Tour Eiffel" et "123 Pitt Street".
  • getSecondaryText(CharacterStyle) renvoie le texte annexe d'une description de lieu. Ceci est utile, car comme deuxième ligne lors de l'affichage des prédictions de saisie semi-automatique. Exemples: "Avenue Anatole France, Paris, France" et "Sydney, Nouvelle-Galles du Sud".
  • getPlaceId() renvoie l'identifiant de lieu du lieu prédit. Un ID de lieu est un ensemble de données identifiant unique d'un lieu, que vous pouvez utiliser pour récupérer la Place ultérieurement. Pour en savoir plus sur les ID de lieu dans Autocomplete, consultez Place Details (Nouveau). Généralités d'informations sur les identifiants de lieu, consultez le document Place ID présentation.
  • getTypes() renvoie la liste des types de lieux associés à ce lieu.
  • getDistanceMeters() renvoie la distance en mètres entre ce lieu et le spécifiée dans la requête.

Paramètres obligatoires

  • Requête

    Chaîne de texte dans laquelle effectuer la recherche. spécifier des mots complets et des sous-chaînes ; des noms de lieux, des adresses et des plus codes ; Service Autocomplete (nouveau) renvoie les résultats correspondant à cette chaîne et les classe en fonction leur pertinence perçue.

    Pour définir le paramètre de requête, appelez la méthode setQuery() lors de la création de l'objet FindAutocompletePredictionsRequest.

Paramètres facultatifs

  • Types principaux

    Une liste comportant jusqu'à cinq valeurs de type à partir des types Tableau A ou Tableau B utilisée pour filtrer les lieux renvoyés dans la réponse. Un lieu doit correspondre à l'une des valeurs de type principal spécifiées pour être inclus dans la réponse.

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

    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.

    Pour définir le paramètre des types principaux, appelez la méthode setTypesFilter(). lors de la création de l'objet FindAutocompletePredictionsRequest.

  • Pays

    Inclure uniquement les résultats de la liste des pays spécifiés (15 pays maximum) ccTLD ("domaine de premier niveau") à deux caractères. Si cette valeur est omise, aucune restriction n'est appliquée à la réponse. Par exemple : afin de limiter ces régions à l'Allemagne et à la France:

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

    Pour définir le paramètre de pays, appelez la méthode setCountries(). lors de la création de l'objet FindAutocompletePredictionsRequest.

  • Décalage d'entrée

    Décalage du caractère Unicode de base zéro indiquant la position du curseur dans la requête. La position du curseur peut influencer les prédictions renvoyées. Si ce champ n'est pas renseigné, la valeur par défaut la longueur de la requête.

    Pour définir le paramètre de décalage d'entrée, appelez la méthode setInputOffset() lors de la création de l'objet FindAutocompletePredictionsRequest.

  • Biais ou restriction de localisation

    Vous pouvez spécifier un biais ou une restriction en fonction de l'emplacement, mais pas les deux, pour définir la zone de recherche. Considérez la restriction d'emplacement comme une indication la région dans laquelle se trouvent les résultats, et le biais de localisation spécifiant la région à proximité des résultats. La principale différence est que avec un biais d'emplacement, des résultats situés en dehors de la région spécifiée peuvent tout de même être renvoyés.

    • Biais de localisation

      Spécifie une zone de recherche. Cet emplacement sert de biais et non de restriction. Par conséquent, les résultats situées en dehors de la zone spécifiée peuvent tout de même être renvoyées.

      Pour définir le paramètre de biais de localisation, appelez la fonction setLocationBias() lors de la création de l'objet FindAutocompletePredictionsRequest.

    • Restriction géographique

      Spécifie une zone de recherche. Les résultats situés en dehors de la zone spécifiée renvoyé.

      Pour définir le paramètre de restriction en fonction de l'emplacement, appelez la méthode setLocationRestriction(). lors de la création de l'objet FindAutocompletePredictionsRequest.

    Spécifiez la région de pondération ou de restriction d'emplacement une fenêtre d'affichage rectangulaire ou un 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 50000.0, inclus. La valeur par défaut est 0.0. Concernant les restrictions géographiques : vous devez définir le rayon sur une valeur supérieure à 0,0. Sinon, la requête renvoie aucun résultat.

    • Un rectangle est une fenêtre d'affichage de latitude-longitude, représentée par deux les points low et high en diagonale. Une fenêtre d'affichage est considérée comme fermée, ce qui signifie qu'elle inclut ses limites. Les limites de latitude doit être comprise entre -90 et 90 degrés inclus, et les limites de longitude doit être comprise 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.

      Vous devez renseigner les champs low et high, et la zone représentée Ce champ est obligatoire. Une fenêtre d'affichage vide entraîne une erreur.

  • Origine

    Point de départ à partir duquel calculer la distance en ligne droite par rapport à la (accessible via getDistanceMeters()). Si cette valeur est 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:

    Pour définir le paramètre d'origine, appelez la méthode setOrigin(). lors de la création de l'objet FindAutocompletePredictionsRequest.

  • Code régional

    Code régional utilisé pour formater la réponse, y compris le format de l'adresse, spécifié sous la forme d'un ccTLD ("domaine de premier niveau") à deux caractères. La plupart des codes ccTLD sont identiques aux codes ISO 3166-1, à quelques exceptions près. Par exemple, le ccTLD au Royaume-Uni est "uk" (.co.uk), tandis que son code ISO 3166-1 est "gb". (d'un point de vue technique, du Royaume-Uni de Grande-Bretagne et d'Irlande du Nord).

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

    Pour définir le paramètre de code régional, appelez la méthode setRegionCode() lors de la création de l'objet FindAutocompletePredictionsRequest.

  • Jeton de session

    Les jetons de session sont des chaînes générées par l'utilisateur qui suivent La saisie semi-automatique (nouvelle version) appelle les "sessions". La saisie semi-automatique 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 pour à des fins de facturation. La session commence lorsque L'utilisateur commence à saisir une requête et termine lorsqu'il sélectionne un lieu. Chaque session peut avoir plusieurs requêtes, suivies d'une sélection de lieux. Une fois qu’une session a le jeton n'est plus valide. votre application doit générer un nouveau jeton pour chaque session. Nous vous recommandons d'utiliser des jetons de session les sessions de saisie semi-automatique (lorsque vous intégrez un fragment ou lancez la saisie semi-automatique via un intent, l'API s'en charge automatiquement).

    La saisie semi-automatique utilise AutocompleteSessionToken pour identifier chaque session. Votre application doit transmettre un nouveau jeton de session commencer chaque nouvelle session, puis transmettre le même jeton, accompagné d'un ID de lieu, dans l'appel suivant à fetchPlace() afin de récupérer les détails sur le lieu sélectionné par l'utilisateur.

    Pour définir le paramètre de jeton de session, appelez la méthode setSessionToken(). lors de la création de l'objet FindAutocompletePredictionsRequest.

    Pour en savoir plus, consultez Jetons de session :

Exemples de saisie semi-automatique (nouveau)

Utiliser la restriction d'emplacement et le biais de localisation

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 des adresses IP, l'API utilise l'adresse IP du appareil pour fausser les résultats. Vous pouvez éventuellement utiliser les données de localisation restriction ou biais de la zone géographique, 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. Résultats en dehors de la plage de dates spécifiée ne sont pas renvoyées. L'exemple suivant utilise la restriction d'emplacement pour limiter la requête à un restriction d'emplacement circulaire dans un rayon de 5 000 mètres centré sur San Francisco:

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Le biais de localisation est utilisé comme un biais, c'est-à-dire que les résultats situés autour de la position spécifiée peut être renvoyée, y compris des résultats situés en dehors de la plage dans une zone géographique spécifique. L'exemple suivant modifie la requête précédente pour utiliser un biais de localisation:

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setLocationBias(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Utiliser les types principaux

Utilisez le paramètre de types principaux pour limiter les résultats provenant d'une d'un certain type, comme indiqué dans le Tableau A et Tableau B. Vous pouvez spécifier un tableau comportant 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 de "Soccer" et utilise l'instance principale paramètre types permettant de limiter les résultats aux établissements de type "sporting_goods_store":

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

final List<Place.Field> primaryTypes = Arrays.asList("sporting_goods_store");

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Soccer")
            .setIncludedPrimaryTypes(primaryTypes)
            .setLocationBias(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Si vous omettez le paramètre de types principaux, les résultats peuvent inclure des établissements. d'un type indésirable, tel que "athletic_field".

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 de l'origine à la destination dans la réponse (accessible via getDistanceMeters()). Dans l'exemple ci-dessous, le point de départ est défini sur le centre de San Francisco:

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setOrigin(center)
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Attributions

Vous pouvez utiliser la saisie semi-automatique (nouvelle version) même sans carte. Si si vous affichez une carte, il doit s'agir d'une carte Google. Lorsque vous affichez les prédictions le service de saisie semi-automatique (nouveau) sans carte, vous doit inclure le logo Google affiché à côté du champ ou des résultats de recherche. Pour Pour en savoir plus, consultez la section Afficher le logo Google et attributions.