Saisie semi-automatique (nouveau)

Autocomplete (New) 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 établir une correspondance avec des mots et des sous-chaînes complets de l'entrée afin de trouver des noms de lieux, des adresses et des Plus Codes. Votre application peut envoyer des requêtes lors de la frappe pour indiquer les lieux et les requêtes possibles à la volée.

Par exemple, vous appelez Autocomplete en utilisant comme entrée une chaîne contenant une saisie partielle de l'utilisateur, "Sicilian piz", 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 "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 (nouveau) pour obtenir plus d'informations sur les prédictions de lieux renvoyées.

Vous pouvez intégrer la fonctionnalité Saisie semi-automatique (nouveau) à votre application de deux manières principales :

• Ajoutez le widget Place Autocomplete : il fournit une expérience de saisie semi-automatique de recherche prête à l'emploi grâce à la classe PlaceAutocomplete qui affiche les prédictions à mesure que l'utilisateur saisit du texte.
• Obtenir des prédictions de lieux de manière programmatique : appelez directement l'API pour récupérer les prédictions et les afficher dans une interface utilisateur personnalisée.

Ajouter le widget Place Autocomplete

Pour proposer plus facilement une expérience de saisie semi-automatique de lieux cohérente, vous pouvez ajouter le widget Place Autocomplete à votre application. Ce widget fournit une interface dédiée en plein écran qui gère la saisie de l'utilisateur et affiche des prédictions de lieux à l'utilisateur tout en renvoyant des objets AutocompletePrediction à l'application. Vous pouvez ensuite envoyer une requête Place Details (New) pour obtenir des informations supplémentaires sur l'une des prédictions de lieux.

Comme pour obtenir des prédictions de lieux de manière programmatique, le widget Place Autocomplete vous permet d'utiliser des jetons de session pour regrouper les requêtes de saisie semi-automatique en sessions à des fins de facturation. Vous pouvez transmettre un jeton de session lorsque vous créez l'intention du widget en appelant setAutocompleteSessionToken(). Si vous ne fournissez pas de jeton de session, le widget en créera un pour vous, auquel vous pourrez accéder en appelant getSessionTokenFromIntent(). Pour en savoir plus sur l'utilisation des jetons de session, consultez À propos des jetons de session.

Pour ajouter le widget Place Autocomplete à votre application :

1. (Facultatif) Définissez un jeton de session. Si vous ne fournissez pas de jeton de session, le widget en créera un pour vous.

2. Définissez un autocompleteIntent avec les paramètres souhaités et votre jeton de session.

3. Définissez un ActivityResultLauncher pour StartActivityForResult. Ce lanceur gérera le résultat renvoyé par l'activité de saisie semi-automatique.

4. Gérez le résultat dans le rappel de ActivityResultLauncher. Cela implique d'extraire les AutocompletePrediction et AutocompleteSessionToken (si vous n'avez pas fourni les vôtres), de gérer les erreurs et, éventuellement, d'envoyer une requête fetchPlace() pour obtenir des informations supplémentaires sur un lieu.

5. Lancez l'intent à l'aide de placeAutocompleteActivityResultLauncher.

Les exemples suivants montrent comment ajouter le widget Place Autocomplete à l'aide de Kotlin et de Java :

// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console.
Places.initializeWithNewPlacesApiEnabled(/* Context= */ context, /* API Key= */ key)

// Optional, create a session token for Autocomplete request and the followup FetchPlace request.
val sessionToken: AutocompleteSessionToken = AutocompleteSessionToken.newInstance()

val autocompleteIntent: Intent =
    PlaceAutocomplete.createIntent(this) {
        // ... provide input params for origin, countries, types filter ...
        setAutocompleteSessionToken(sessionToken)
    }

val placeAutocompleteActivityResultLauncher: ActivityResultLauncher<Intent> =
    registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult ->
        val intent = result.data
        if (intent != null && result.resultCode == PlaceAutocompleteActivity.RESULT_OK) {
            // get prediction object
            val prediction: AutocompletePrediction? =
                PlaceAutocomplete.getPredictionFromIntent(intent!!)

            // get session token
            val sessionToken: AutocompleteSessionToken? =
                PlaceAutocomplete.getSessionTokenFromIntent(intent!!)

            // create PlacesClient to make FetchPlace request (optional)
            val placesClient: PlacesClient = Places.createClient(this)
            val response =
                placesClient.awaitFetchPlace(prediction.placeId, Field.DISPLAY_NAME)
                {
                    sessionToken = sessionToken // optional
                }
        }
    }

// Launch Activity
placeAutocompleteActivityResultLauncher.launch(autocompleteIntent)

// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console.
Places.initializeWithNewPlacesApiEnabled(/* Context= */ context, /* API Key= */ key);

// Optional, create a session token for Autocomplete request and the followup FetchPlace request
AutocompleteSessionToken sessionToken = AutocompleteSessionToken.newInstance();

Intent autocompleteIntent =
    new PlaceAutocomplete.IntentBuilder()
        // ... set input params for origin, countries, types filter ...
        .setSessionToken(sessionToken) // optional
        .build(this);

ActivityResultLauncher<Intent> placeAutocompleteActivityResultLauncher =
    registerForActivityResult(
        new ActivityResultContracts.StartActivityForResult(),
        new ActivityResultCallback<ActivityResult>() {
            @Override
            public void onActivityResult(ActivityResult result) {
                Intent intent = result.getData();
                if (result.getResultCode() == PlaceAutocompleteActivity.RESULT_OK) {
                    // get prediction object
                    AutocompletePrediction prediction =
                        PlaceAutocomplete.getPredictionFromIntent(
                            Preconditions.checkNotNull(intent));

                    // get session token
                    AutocompleteSessionToken sessionToken =
                        PlaceAutocomplete.getSessionTokenFromIntent(
                            Preconditions.checkNotNull(intent));

                    // create PlacesClient to make FetchPlace request (optional)
                    PlacesClient placesClient = Places.createClient(this);
                    FetchPlaceRequest request =
                        FetchPlaceRequest.builder(prediction.getPlaceId(),
                            Arrays.asList(Field.DISPLAY_NAME))
                            .setSessionToken(sessionToken).build();
                    Task<FetchPlaceResponse> task = placesClient.fetchPlace(request);
                }
            }
        }
    );

// Launch Activity
placeAutocompleteActivityResultLauncher.launch(autocompleteIntent);

Personnaliser le thème

Lorsque vous instanciez une expérience Autocomplete, vous pouvez spécifier un thème qui remplace l'un des attributs de style par défaut. Vous pouvez personnaliser les couleurs, la typographie, l'espacement, les bordures et les angles de votre composant Place Autocomplete. La valeur par défaut est PlacesMaterialTheme. Tous les attributs de thème qui ne sont pas remplacés utilisent les styles par défaut.

Vous pouvez définir des remplacements de thème dans …/res/values/themes.xml. Exemple :

<?xml version="1.0" encoding="utf-8"?>
<resources>
  <style name="BrandedTheme" parent="PlacesMaterialTheme">
    <!-- Color tokens. -->
    <item name="placesColorOnNeutralContainer">#5300e8</item>
    <item name="placesColorOnNeutralContainerVariant">#ee6002</item>
    ...

    <!-- Typography tokens. -->
    <item name="placesTextAppearanceTitleLarge">@style/PlacesTextAppearance</item>
    <item name="placesTextAppearanceBodyMedium">@style/PlacesTextAppearance</item>
    ...

    <!-- Spacing tokens. -->
    <item name="placesSpacingSmall">6dp</item>
    <item name="placesSpacingMedium">12dp</item>
    ...

    <!-- Attribution tokens. -->
    <item name="placesColorAttributionLightTheme">white</item>
    <item name="placesColorAttributionDarkTheme">black</item>
  </style>
</resources>

Vous pouvez ensuite faire référence aux styles de remplacement en appelant setAutocompleteUiCustomization :

ActivityResultLauncher<Intent> placeAutocompleteActivityResultLauncher =
  registerForActivityResult(
    new ActivityResultContracts.StartActivityForResult(),
    new ActivityResultCallback<ActivityResult>() {
      @Override
      public void onActivityResult(ActivityResult result) {
        Intent intent = result.getData();
        if (intent != null) {
          AutocompletePrediction prediction =
            PlaceAutocomplete.getPredictionFromIntent(intent);
          AutocompleteSessionToken sessionToken =
            PlaceAutocomplete.getSessionTokenFromIntent(intent);
          Status status = PlaceAutocomplete.getResultStatusFromIntent(intent);
          ...
        }
      }
    }
  );

Intent placeAutocompleteIntent =
  new PlaceAutocomplete.IntentBuilder()
    .setInitialQuery("INSERT_QUERY_TEXT")
    .setOrigin(new LatLng(10.0, 10.0))
    ...

    .setAutocompleteUiCustomization(
      AutocompleteUiCustomization.builder()
        .listItemIcon(AutocompleteUiIcon.noIcon())
        .listDensity(AutocompleteListDensity.MULTI_LINE)
        .theme(R.style.BrandedTheme)
        .build())
  .build(this);

placeAutocompleteActivityResultLauncher.launch(placeAutocompleteIntent);

Obtenir des prédictions de lieux de manière programmatique

Votre application peut obtenir une liste des noms et/ou adresses de lieux prédits à partir de l'API Autocomplete 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 Autocomplete (nouveau)

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 les détails du lieu :

• getFullText(CharacterStyle) renvoie le texte complet de la description d'un 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 évidence les sections de la description qui correspondent à la recherche avec le 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 subsidiaire d'une description de lieu. Cela peut être utile, par exemple, comme 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 un lieu de façon unique. Vous pouvez l'utiliser pour récupérer l'objet Place ultérieurement. Pour en savoir plus sur les ID de lieu dans Autocomplete, consultez Place Details (New). Pour obtenir des informations générales 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 à vol d'oiseau en mètres entre ce lieu et l'origine spécifiée dans la requête.

Paramètres obligatoires

• Requête

  Chaîne de texte sur laquelle effectuer la recherche. Spécifiez des mots et des sous-chaînes complets, des noms de lieux, des adresses et des Plus Codes. Le service Autocomplete (nouveau) renvoie les résultats correspondant à cette chaîne et les classe en fonction de leur pertinence estimée.

  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 au maximum issues du Tableau A ou du Tableau B, utilisées 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 être associé qu'à un seul type principal parmi ceux des Tableaux A ou 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 :

  • Plus de cinq types sont spécifiés.
  • vous spécifiez des types non reconnus ;

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

• Pays

  N'incluez que les résultats de la liste des pays spécifiés, sous la forme d'une liste de valeurs ccTLD ("domaine de premier niveau") à deux caractères (jusqu'à 15). 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 :

  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 basé sur 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 dont les résultats doivent être proches. La principale différence est qu'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 de recherche. Cet emplacement sert de biais, et non de restriction. Des résultats en dehors de la zone spécifiée peuvent donc toujours être 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 de recherche. Les résultats en dehors de la zone spécifiée ne sont pas renvoyés.

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

  Spécifiez la région de restriction ou de biais de localisation sous forme de fenêtre d'affichage rectangulaire ou de 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 la restriction géographique, vous devez définir un rayon supérieur à 0,0. Sinon, la requête ne renvoie aucun résultat.

  • Un rectangle est une fenêtre d'affichage de latitude et de longitude, représentée par deux points low et high diagonalement 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 inclus, et les limites de longitude doivent être comprises 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 traverse la ligne de longitude de 180°).
    • 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 longitude est vide.

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

• Origine

  Point d'origine à partir duquel calculer la distance à vol d'oiseau jusqu'à la destination (accessible à l'aide de getDistanceMeters()). Si cette valeur est omise, la distance à vol d'oiseau 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 régional utilisé pour mettre en forme la réponse, y compris l'adresse, spécifié sous la forme d'une valeur 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 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 une incidence sur les résultats en fonction de la loi 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 les appels Autocomplete (nouveau), qu'il s'agisse d'appels effectués via le widget ou d'appels programmatiques, en tant que "sessions". Autocomplete 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. 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. Lorsque la session prend fin, 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 programmatiques (lorsque vous intégrez un fragment ou lancez la saisie semi-automatique à l'aide d'un intent, l'API s'en charge 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 nouvelle session, puis transmettre ce même jeton, ainsi qu'un identifiant de lieu, dans l'appel suivant à fetchPlace() pour récupérer les détails du lieu sélectionné par l'utilisateur.

  Pour définir le paramètre du 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 et le biais de localisation

La saisie semi-automatique (nouvelle version) utilise par défaut le biais d'adresse IP pour contrôler la zone de recherche. Avec le biais d'adresse IP, l'API utilise l'adresse IP de l'appareil pour biaiser les résultats. Vous pouvez éventuellement utiliser la restriction de localisation ou le biais de localisation, 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 géographique pour limiter la requête à une restriction 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 la localisation spécifiée peuvent être renvoyés, y compris des résultats 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 les types principaux

Utilisez le paramètre primary_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 ce paramètre est omis, tous les types sont renvoyés.

L'exemple suivant spécifie une chaîne de requête "Soccer" et utilise le paramètre primary_types 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 des 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é sous forme de 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 à l'aide de getDistanceMeters()). Cet exemple définit l'origine au 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());
        })
    );

Optimisation d'Autocomplete (nouveau)

Cette section décrit les bonnes pratiques pour vous aider à exploiter au mieux le service Autocomplete (nouveau).

Voici quelques consignes générales :

• La méthode la plus rapide pour développer une interface utilisateur fonctionnelle consiste à utiliser le widget de saisie semi-automatique (nouveau) de l'API Maps JavaScript, le widget de saisie semi-automatique (nouveau) du SDK Places pour Android ou le widget de saisie semi-automatique (nouveau) du SDK Places pour iOS.
• Développez dès le départ vos connaissances des champs de données Autocomplete (nouveau) essentiels.
• Les champs de pondération et de restriction de lieu sont facultatifs, mais peuvent avoir un impact important sur les performances de la saisie semi-automatique.
• Utilisez la gestion des erreurs pour vérifier que votre application se dégrade correctement si l'API renvoie une erreur.
• Assurez-vous que votre application fonctionne lorsqu'il n'y a aucune sélection et qu'elle propose aux utilisateurs un moyen de poursuivre.

Bonnes pratiques liées à l'optimisation des coûts

Optimisation de base des coûts

Pour optimiser le coût d'utilisation du service Autocomplete (New), utilisez des masques de champ dans les widgets Place Details (New) et Autocomplete (New) afin de ne renvoyer que les champs de données Autocomplete (New) dont vous avez besoin.

Optimisation avancée des coûts

Envisagez d'implémenter Autocomplete (nouveau) de manière programmatique pour accéder au tarif par requête Autocomplete et demander des résultats d'API Geocoding pour le lieu sélectionné plutôt que pour Place Details (nouveau). La tarification par requête associée à l'API Geocoding est plus rentable que la tarification par session (basée sur la session) si les deux conditions suivantes sont remplies :

• Si vous n'avez besoin que de la latitude/longitude ou de l'adresse du lieu sélectionné par l'utilisateur, l'API Geocoding fournit ces informations à un prix inférieur à celui d'un appel Place Details (nouveau).
• Si les utilisateurs sélectionnent une prédiction de saisie semi-automatique toutes les quatre requêtes de prédiction Autocomplete (New) ou moins en moyenne, la tarification par requête peut être plus rentable que celle par session.

Votre application nécessite-t-elle des informations autres que l'adresse et la latitude/longitude de la prédiction sélectionnée ?

Bonnes pratiques en matière de performances

Les consignes suivantes décrivent les méthodes permettant d'optimiser les performances d'Autocomplete (nouveau) :

• Ajoutez des restrictions locales, une pondération géographique et des préférences linguistiques (pour les implémentations programmatiques) à votre implémentation Autocomplete (New). La préférence linguistique n'est pas obligatoire pour les widgets, car ils sélectionnent cette option dans le navigateur ou l'appareil mobile de l'utilisateur.
• Si la saisie semi-automatique (nouvelle version) est accompagnée d'une carte, vous pouvez pondérer la position en fonction de la fenêtre d'affichage de la carte.
• Dans les cas où l'utilisateur ne choisit pas l'une des prédictions de la saisie semi-automatique (nouvelle), généralement parce qu'aucune d'entre elles n'est l'adresse souhaitée, vous pouvez réutiliser l'entrée utilisateur d'origine pour essayer d'obtenir des résultats plus pertinents :
  • Si vous pensez que l'utilisateur ne saisira que des informations d'adresse, réutilisez son entrée d'origine dans un appel à l'API Geocoding.
  • Si vous pensez que l'utilisateur saisira des requêtes pour un lieu spécifique avec un nom ou une adresse, utilisez une requête Place Details (New). Si les résultats ne sont attendus que dans une région spécifique, utilisez la pondération géographique.
  Voici d'autres scénarios dans lesquels il est préférable de revenir à l'API Geocoding :
  • Les utilisateurs saisissent des adresses de sous-lieux, comme des adresses d'unités ou d'appartements spécifiques dans un bâtiment. Par exemple, l'adresse tchèque "Stroupežnického 3191/17, Praha" génère une prédiction partielle dans Autocomplete (New).
  • Lorsque des utilisateurs saisissent des adresses qui contiennent un préfixe identifiant une portion de route, par exemple "23-30 29th St, Queens" à New York ou "47-380 Kamehameha Hwy, Kaneohe" sur l'île de Kauai, à Hawaï.

Biais de localisation

Limitez les résultats à une zone spécifique en transmettant les paramètres location et radius. Cela indique à la saisie semi-automatique (nouvelle version) de privilégier les résultats dans la zone définie. Des résultats en dehors de la zone définie peuvent toutefois être affichés. Vous pouvez utiliser le paramètre components pour filtrer les résultats et n'afficher que les lieux situés dans un pays spécifique.

Restriction géographique

Limitez les résultats à une zone spécifique en transmettant un paramètre locationRestriction.

Vous pouvez également limiter les résultats à la région définie par les paramètres location et radius en ajoutant le paramètre locationRestriction. Cela indique à Autocomplete (New) de ne renvoyer que les résultats dans cette région.