Saisie semi-automatique (nouveau)

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

La saisie semi-automatique (nouvelle) renvoie des prédictions de lieux en réponse à une requête qui inclut une chaîne de recherche textuelle et des limites géographiques qui contrôlent la zone de recherche. La saisie semi-automatique peut correspondre à des mots entiers et à des sous-chaînes de la saisie, en résolvant les noms de lieux, les adresses et les plus codes. Votre application peut envoyer des requêtes à mesure que l'utilisateur saisit du texte, afin de fournir des prédictions de lieux et de requêtes instantanées.

Par exemple, vous appelez la saisie semi-automatique en utilisant une chaîne contenant une entrée utilisateur partielle, "pizza sicilienne", avec la zone de recherche limitée à San Francisco, en Californie. La réponse contient ensuite une liste de prédictions de lieux correspondant à la chaîne de recherche et à la zone de recherche, comme le restaurant nommé "Sicilian Pizza Kitchen".

Les prédictions de lieux renvoyées sont conçues pour être présentées à l'utilisateur afin de l'aider à sélectionner le lieu souhaité. Vous pouvez envoyer une requête Place Details (New) (Informations sur le lieu (nouveau)) pour obtenir plus d'informations sur l'une des prédictions de lieu renvoyées.

Requêtes de saisie semi-automatique (nouvelles)

Votre application peut obtenir une liste de noms de lieux et/ou d'adresses prédits à partir de l'API de saisie semi-automatique en appelant PlacesClient.findAutocompletePredictions() et en transmettant un objet FindAutocompletePredictionsRequest. L'exemple ci-dessous montre 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 saisie semi-automatique (nouvelles)

L'API renvoie un FindAutocompletePredictionsResponse dans un Task. FindAutocompletePredictionsResponse contient une liste de cinq objets AutocompletePrediction maximum représentant les lieux prédits. La liste peut être vide si aucun lieu connu ne correspond à la requête et aux critères de filtrage.

Pour chaque lieu prédit, vous pouvez appeler les méthodes suivantes pour récupérer des informations sur le lieu:

  • getFullText(CharacterStyle) renvoie le texte complet d'une description de lieu. Il s'agit d'une combinaison du texte principal et secondaire. Exemple : Tour Eiffel, Avenue Anatole France, Paris, France. De plus, cette méthode vous permet de mettre en surbrillance les sections de la description correspondant à la recherche avec un style de votre choix, à l'aide de CharacterStyle. Le paramètre CharacterStyle est facultatif. Définissez-le sur "null" si vous n'avez pas besoin de mise en surbrillance.
  • getPrimaryText(CharacterStyle) renvoie le texte principal décrivant un lieu. Il s'agit généralement du nom du lieu. Exemples : Tour Eiffel et 123, rue Pitt.
  • getSecondaryText(CharacterStyle) renvoie le texte secondaire d'une description de lieu. Cela peut être utile, par exemple, en tant que deuxième ligne lorsque vous affichez des prédictions de saisie semi-automatique. Exemples : Avenue Anatole France, Paris, France et Sydney, Nouvelle-Galles du Sud.
  • getPlaceId() renvoie l'ID du lieu prédit. Un ID de lieu est un identifiant textuel qui identifie de manière unique un lieu. Vous pouvez l'utiliser pour récupérer l'objet Place ultérieurement. Pour en savoir plus sur les ID de lieu dans la saisie semi-automatique, consultez Informations sur le lieu (nouveau). Pour en savoir plus sur les ID de lieu, consultez la présentation des ID de lieu.
  • getTypes() renvoie la liste des types de lieux associés à ce lieu.
  • getDistanceMeters() renvoie la distance en ligne droite, en mètres, entre cet emplacement et l'origine spécifiée dans la requête.

Paramètres obligatoires

  • Requête

    Chaîne de texte à rechercher. 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 des correspondances candidates en fonction de cette chaîne et trie les résultats en fonction de 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

    Liste de cinq valeurs de type maximum parmi les types du tableau A ou du tableau B, utilisées pour filtrer les lieux renvoyés dans la réponse. Pour être inclus dans la réponse, un lieu doit correspondre à l'une des valeurs de type principal spécifiées.

    Un lieu ne peut avoir 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".

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

    • Vous avez spécifié plus de cinq types.
    • Tous les types non reconnus sont spécifiés.

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

  • Pays

    Incluez uniquement les résultats de la liste des pays spécifiés, qui est une liste de 15 TLD de pays (domaine de premier niveau) de deux caractères maximum. Si ce paramètre est omis, aucune restriction n'est appliquée à la réponse. Par exemple, pour limiter les régions à l'Allemagne et à la France:

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

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

  • Décalage d'entrée

    Décalage de caractère Unicode à partir de 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 est vide, la longueur de la requête est utilisée par défaut.

    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 géographique

    Vous pouvez spécifier un biais de localisation ou une restriction de localisation, mais pas les deux, pour définir la zone de recherche. Considérez la restriction géographique comme une spécification de la région dans laquelle les résultats doivent se trouver, et le biais géographique comme une spécification de la région à proximité de laquelle les résultats doivent se trouver. La principale différence est que, avec le biais de localisation, des résultats en dehors de la région spécifiée peuvent toujours être renvoyés.

    • Biais de localisation

      Spécifie une zone à rechercher. Cet emplacement sert de biais, et non de restriction. Il est donc possible que des résultats en dehors de la zone spécifiée soient renvoyés.

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

    • Restriction géographique

      Spécifie une zone à rechercher. Les résultats en dehors de la zone spécifiée ne sont pas renvoyés.

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

    Spécifiez la région de biais ou de restriction de position sous la forme d'un viewport 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. La valeur par défaut est 0.0. Pour les restrictions géographiques, vous devez définir le rayon sur une valeur supérieure à 0,0. Sinon, la requête ne renvoie aucun résultat.

    • Un rectangle est un viewport de latitude-longitude, représenté par deux points low et high diamétralement opposés. Un viewport est considéré comme une région fermée, ce qui signifie qu'il 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, le viewport inclut toutes les longitudes.
      • Si low.longitude = 180 degrés et high.longitude = -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.

  • Origine

    Point d'origine à partir duquel calculer la distance en ligne droite jusqu'à la destination (accessible via getDistanceMeters()). 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:

    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 de région utilisé pour mettre en forme la réponse, y compris la mise en forme de l'adresse, spécifié sous la forme d'une valeur à deux caractères de TLD de pays (domaine de premier niveau). La plupart des codes ccTLD sont identiques aux codes ISO 3166-1, à quelques exceptions notables 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.

    Pour définir le paramètre de code de région, 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 les appels Autocomplete (Nouveau) en tant que "sessions". La saisie semi-automatique utilise des jetons de session pour regrouper les phases de requête et de sélection d'une recherche de saisie semi-automatique de l'utilisateur dans une session distincte à des fins de facturation. La session commence lorsque l'utilisateur commence à saisir une requête et se termine lorsqu'il sélectionne un lieu. Chaque session peut comporter plusieurs requêtes, suivies d'une sélection de lieu. Une fois une session terminée, 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 pour toutes les sessions de saisie semi-automatique programmatique (lorsque vous intégrez un fragment ou lancez la saisie semi-automatique à l'aide d'un intent, l'API s'en occupe automatiquement).

    La saisie semi-automatique utilise un AutocompleteSessionToken pour identifier chaque session. Votre application doit transmettre un nouveau jeton de session au début de chaque session, puis transmettre ce même jeton, ainsi qu'un ID de lieu, dans l'appel ultérieur à fetchPlace() pour récupérer les informations 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 la section Jetons de session.

Exemples de saisie semi-automatique (nouvelle)

Utiliser la restriction géographique et le biais géographique

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 utiliser une restriction géographique ou un biais géographique, mais pas les deux, pour spécifier une zone de recherche.

La restriction géographique 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 de zone géographique pour limiter la requête à une restriction de zone géographique circulaire d'un rayon de 5 000 mètres centrée 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());
        })
    );

Avec le biais de localisation, la localisation 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:

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 des types principaux

Utilisez le paramètre types principaux 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 "Football" et utilise le paramètre "types principaux" pour 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 "types principaux", les résultats peuvent inclure des établissements d'un type que vous ne souhaitez pas, comme "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 entre l'origine et la destination dans la réponse (accessible via getDistanceMeters()). Cet exemple définit l'origine 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) même sans carte. Si vous affichez une carte, elle doit être une carte Google. Lorsque vous affichez les prédictions du service de saisie semi-automatique (nouveau) sans carte, vous devez inclure le logo Google affiché en ligne avec le champ de recherche/les résultats. Pour en savoir plus, consultez Afficher le logo et les attributions Google.