Place Autocomplete

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.
Sélectionnez une plate-forme : Android iOS JavaScript Service Web

Le service de saisie semi-automatique du SDK Places pour Android renvoie des prédictions de lieux en réponse aux requêtes de recherche des utilisateurs. À mesure que l'utilisateur saisit du texte, le service de saisie semi-automatique renvoie des suggestions de lieux, d'adresses, de plus codes et de points d'intérêt.

Vous pouvez ajouter Autocomplete à votre application de plusieurs façons :

Ajouter un widget Autocomplete

Le widget Autocomplete est une boîte de dialogue de recherche avec fonctionnalité de saisie semi-automatique intégrée. Lorsqu'un utilisateur saisit des termes de recherche, le widget affiche une liste de lieux prédictifs. Lorsque l'utilisateur effectue une sélection, une instance Place est renvoyée. Votre application peut ensuite l'utiliser pour obtenir des informations sur le lieu sélectionné.

Deux options sont possibles pour ajouter un widget Autocomplete à votre application :

Option 1: Intégrer un fragment AutocompleteSupportFragment

Pour ajouter un AutocompleteSupportFragment à votre application, procédez comme suit:

  1. Ajoutez un fragment à la mise en page XML de votre activité.
  2. Ajoutez un écouteur à votre activité ou fragment.

Ajouter AutocompleteSupportFragment à une activité

Pour ajouter AutocompleteSupportFragment à une activité, ajoutez un nouveau fragment à une mise en page XML. Exemple :

<fragment android:id="@+id/autocomplete_fragment"
  android:layout_width="match_parent"
  android:layout_height="wrap_content"
  android:name="com.google.android.libraries.places.widget.AutocompleteSupportFragment"
  />
  • Par défaut, le fragment ne contient ni bordure, ni arrière-plan. Pour fournir une apparence cohérente, imbriquez le fragment dans un autre élément de mise en page, tel qu'un CardView.
  • Si vous utilisez le fragment Autocomplete et devez remplacer onActivityResult, vous devez appeler super.onActivityResult. Sinon, le fragment ne fonctionnera pas correctement.

Ajouter un écouteur PlaceSelectionListener à une activité

PlaceSelectionListener gère le renvoi d'un lieu en réponse à la sélection de l'utilisateur. Le code suivant montre comment créer une référence au fragment et ajouter un écouteur à votre AutocompleteSupportFragment:

Java


    // Initialize the AutocompleteSupportFragment.
    AutocompleteSupportFragment autocompleteFragment = (AutocompleteSupportFragment)
        getSupportFragmentManager().findFragmentById(R.id.autocomplete_fragment);

    // Specify the types of place data to return.
    autocompleteFragment.setPlaceFields(Arrays.asList(Place.Field.ID, Place.Field.NAME));

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(new PlaceSelectionListener() {
        @Override
        public void onPlaceSelected(@NonNull Place place) {
            // TODO: Get info about the selected place.
            Log.i(TAG, "Place: " + place.getName() + ", " + place.getId());
        }


        @Override
        public void onError(@NonNull Status status) {
            // TODO: Handle the error.
            Log.i(TAG, "An error occurred: " + status);
        }
    });

      

Kotlin


    // Initialize the AutocompleteSupportFragment.
    val autocompleteFragment =
        supportFragmentManager.findFragmentById(R.id.autocomplete_fragment)
            as AutocompleteSupportFragment

    // Specify the types of place data to return.
    autocompleteFragment.setPlaceFields(listOf(Place.Field.ID, Place.Field.NAME))

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(object : PlaceSelectionListener {
        override fun onPlaceSelected(place: Place) {
            // TODO: Get info about the selected place.
            Log.i(TAG, "Place: ${place.name}, ${place.id}")
        }

        override fun onError(status: Status) {
            // TODO: Handle the error.
            Log.i(TAG, "An error occurred: $status")
        }
    })

      

Option 2: Utiliser un intent pour lancer l'activité de saisie semi-automatique

Si vous souhaitez que votre application utilise un flux de navigation différent (par exemple, pour déclencher l'expérience de saisie semi-automatique à partir d'une icône plutôt que d'un champ de recherche), votre application peut lancer la saisie semi-automatique à l'aide d'un intent.

Pour lancer le widget de saisie semi-automatique en utilisant un intent, procédez comme suit :

  1. Utilisez Autocomplete.IntentBuilder pour créer un intent en transmettant le mode Autocomplete souhaité. L'intent doit appeler startActivityForResult en transmettant un code de requête qui l'identifie.
  2. Ignorez le rappel onActivityResult pour recevoir le lieu sélectionné.

Créer un intent de saisie semi-automatique

L'exemple ci-dessous montre comment utiliser Autocomplete.IntentBuilder pour créer un intent afin de lancer le widget de saisie semi-automatique en tant qu'intent:

Java


    private static int AUTOCOMPLETE_REQUEST_CODE = 1;

    // Set the fields to specify which types of place data to
    // return after the user has made a selection.
    List<Place.Field> fields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

    // Start the autocomplete intent.
    Intent intent = new Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .build(this);
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE);

      

Kotlin


    private val AUTOCOMPLETE_REQUEST_CODE = 1

    // Set the fields to specify which types of place data to
    // return after the user has made a selection.
    val fields = listOf(Place.Field.ID, Place.Field.NAME)

    // Start the autocomplete intent.
    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .build(this)
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE)

      

Lorsque vous utilisez un intent pour lancer le widget de saisie semi-automatique, vous pouvez choisir le mode d'affichage en superposition ou en plein écran. Les captures d'écran suivantes illustrent chaque mode d'affichage:

Lorsqu&#39;il est affiché en mode superposition, le widget Autocomplete s&#39;affiche en superposition sur l&#39;interface utilisateur de l&#39;appel.
Figure 1 : Widget Autocomplete en mode CHEVAUCHEMENT
Lorsqu&#39;il est affiché en mode plein écran, le widget Autocomplete remplit tout l&#39;écran.
Figure 2 : Widget Autocomplete en mode Plein écran

Ignorer le rappel onActivityResult

Pour recevoir une notification lorsque l'utilisateur a sélectionné un lieu, votre application doit remplacer l'activité onActivityResult() en vérifiant le code de requête que vous avez transmis pour votre intent, comme illustré dans l'exemple suivant.

Java


@Override
protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
    if (requestCode == AUTOCOMPLETE_REQUEST_CODE) {
        if (resultCode == RESULT_OK) {
            Place place = Autocomplete.getPlaceFromIntent(data);
            Log.i(TAG, "Place: " + place.getName() + ", " + place.getId());
        } else if (resultCode == AutocompleteActivity.RESULT_ERROR) {
            // TODO: Handle the error.
            Status status = Autocomplete.getStatusFromIntent(data);
            Log.i(TAG, status.getStatusMessage());
        } else if (resultCode == RESULT_CANCELED) {
            // The user canceled the operation.
        }
        return;
    }
    super.onActivityResult(requestCode, resultCode, data);
}

      

Kotlin


override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    if (requestCode == AUTOCOMPLETE_REQUEST_CODE) {
        when (resultCode) {
            Activity.RESULT_OK -> {
                data?.let {
                    val place = Autocomplete.getPlaceFromIntent(data)
                    Log.i(TAG, "Place: ${place.name}, ${place.id}")
                }
            }
            AutocompleteActivity.RESULT_ERROR -> {
                // TODO: Handle the error.
                data?.let {
                    val status = Autocomplete.getStatusFromIntent(data)
                    Log.i(TAG, status.statusMessage ?: "")
                }
            }
            Activity.RESULT_CANCELED -> {
                // The user canceled the operation.
            }
        }
        return
    }
    super.onActivityResult(requestCode, resultCode, data)
}

      

Obtenir des prédictions de lieu de manière automatisée

Vous pouvez créer une UI de recherche personnalisée à la place de l'UI fournie par le widget de saisie semi-automatique. Pour ce faire, votre application doit obtenir des prédictions de lieu de manière automatisée. Votre application peut obtenir la liste des prédictions de noms et/ou d'adresses de lieux à partir de l'API Autocomplete en appelant PlacesClient.findAutocompletePredictions(), en transmettant un objet FindAutocompletePredictionsRequest avec les paramètres suivants:

  • Obligatoire:chaîne query contenant le texte saisi par l'utilisateur.
  • Recommandé : AutocompleteSessionToken, qui regroupe les phases de requête et de sélection d'une recherche d'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.
  • Recommandé : Objet RectangularBounds spécifiant les limites de latitude et de longitude pour limiter les résultats dans la région spécifiée.
  • Facultatif : un ou plusieurs codes pays à deux lettres (ISO 3166-1 Alpha-2), indiquant le ou les pays auxquels les résultats doivent être soumis
  • Facultatif : TypeFilter, que vous pouvez utiliser pour limiter les résultats au type de lieu spécifié. Les types de lieux suivants sont acceptés:

    • TypeFilter.GEOCODE : renvoie uniquement les résultats du geocoding, plutôt que des établissements. Utilisez cette requête pour faire la distinction entre les résultats dont l'emplacement spécifié peut être indéterminé.
    • TypeFilter.ADDRESS : renvoie uniquement les résultats de la saisie semi-automatique avec une adresse précise. Utilisez ce type lorsque vous savez que l'utilisateur recherche une adresse entièrement spécifiée.
    • TypeFilter.ESTABLISHMENT : renvoie uniquement les établissements qui correspondent à des établissements.
    • TypeFilter.REGIONS : renvoie uniquement les lieux correspondant à l'un des types suivants :

      • LOCALITY
      • SUBLOCALITY
      • POSTAL_CODE
      • COUNTRY
      • ADMINISTRATIVE_AREA_LEVEL_1
      • ADMINISTRATIVE_AREA_LEVEL_2
    • TypeFilter.CITIES : renvoie uniquement les résultats correspondant à LOCALITY ou ADMINISTRATIVE_AREA_LEVEL_3.

  • Facultatif:LatLng spécifiant le lieu d'origine de la requête. Lorsque vous appelez setOrigin(), le service renvoie la distance en mètres (distanceMeters) à partir de l'origine spécifiée, pour chaque prédiction de saisie semi-automatique dans la réponse.

Pour en savoir plus sur les types de lieux, consultez le guide sur les types de lieux.

L'exemple ci-dessous présente un appel complet à PlacesClient.findAutocompletePredictions().

Java


    // Create a new token for the autocomplete session. Pass this to FindAutocompletePredictionsRequest,
    // and once again when the user makes a selection (for example when calling fetchPlace()).
    AutocompleteSessionToken token = AutocompleteSessionToken.newInstance();

    // Create a RectangularBounds object.
    RectangularBounds bounds = RectangularBounds.newInstance(
        new LatLng(-33.880490, 151.184363),
        new LatLng(-33.858754, 151.229596));
    // Use the builder to create a FindAutocompletePredictionsRequest.
    FindAutocompletePredictionsRequest request = FindAutocompletePredictionsRequest.builder()
        // Call either setLocationBias() OR setLocationRestriction().
        .setLocationBias(bounds)
        //.setLocationRestriction(bounds)
        .setOrigin(new LatLng(-33.8749937,151.2041382))
        .setCountries("AU", "NZ")
        .setTypeFilter(TypeFilter.ADDRESS)
        .setSessionToken(token)
        .setQuery(query)
        .build();

    placesClient.findAutocompletePredictions(request).addOnSuccessListener((response) -> {
        for (AutocompletePrediction prediction : response.getAutocompletePredictions()) {
            Log.i(TAG, prediction.getPlaceId());
            Log.i(TAG, prediction.getPrimaryText(null).toString());
        }
    }).addOnFailureListener((exception) -> {
        if (exception instanceof ApiException) {
            ApiException apiException = (ApiException) exception;
            Log.e(TAG, "Place not found: " + apiException.getStatusCode());
        }
    });

      

Kotlin


    // Create a new token for the autocomplete session. Pass this to FindAutocompletePredictionsRequest,
    // and once again when the user makes a selection (for example when calling fetchPlace()).
    val token = AutocompleteSessionToken.newInstance()

    // Create a RectangularBounds object.
    val bounds = RectangularBounds.newInstance(
        LatLng(-33.880490, 151.184363),
        LatLng(-33.858754, 151.229596)
    )
    // Use the builder to create a FindAutocompletePredictionsRequest.
    val request =
        FindAutocompletePredictionsRequest.builder()
            // Call either setLocationBias() OR setLocationRestriction().
            .setLocationBias(bounds)
            //.setLocationRestriction(bounds)
            .setOrigin(LatLng(-33.8749937, 151.2041382))
            .setCountries("AU", "NZ")
            .setTypeFilter(TypeFilter.ADDRESS)
            .setSessionToken(token)
            .setQuery(query)
            .build()
    placesClient.findAutocompletePredictions(request)
        .addOnSuccessListener { response: FindAutocompletePredictionsResponse ->
            for (prediction in response.autocompletePredictions) {
                Log.i(TAG, prediction.placeId)
                Log.i(TAG, prediction.getPrimaryText(null).toString())
            }
        }.addOnFailureListener { exception: Exception? ->
            if (exception is ApiException) {
                Log.e(TAG, "Place not found: " + exception.statusCode)
            }
        }

      

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

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

  • getFullText(CharacterStyle) renvoie le texte intégral d'une description de lieu. Il s'agit d'une combinaison du texte principal et du texte secondaire. Exemple : Tour Eiffel, Avenue Anatole France, Paris, France. En outre, cette méthode vous permet de mettre en surbrillance les sections de la 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 de le mettre 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 des filiales d'une description de lieu. C'est utile, par exemple, comme deuxième ligne lors de l'affichage des prédictions de la saisie semi-automatique. Exemples : Avenue Anatole France, Paris, France"Sydney, Nouvelle-Galles du Sud.
  • getPlaceId() affiche l'ID de lieu du lieu prédit. Un ID de lieu est un identifiant texte qui identifie un lieu de manière unique. Il vous permet de récupérer à nouveau l'objet Place ultérieurement. Pour en savoir plus sur les ID de lieu dans le SDK Places pour Android, consultez la page Place Details. Pour obtenir des informations générales sur les ID de lieu, consultez la présentation des ID de lieu.
  • getPlaceTypes() affiche la liste des types de lieux associés à ce lieu.
  • getDistanceMeters() renvoie la distance en ligne droite en mètres entre ce lieu et le point de départ spécifié dans la requête.

Jetons de session

Les jetons de session regroupent les phases de requête et de sélection d'une recherche de saisie semi-automatique des utilisateurs 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 la session terminée, le jeton n'est plus valide. Votre application doit générer un 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 que vous lancez la saisie semi-automatique à l'aide d'un intent, l'API s'en charge automatiquement).

Le SDK Places pour Android 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 et un ID de lieu lors de l'appel ultérieur à fetchPlace(), afin de récupérer les détails sur le lieu sélectionnés par l'utilisateur.

En savoir plus sur les jetons de session

Limiter les résultats de la saisie semi-automatique

Vous pouvez limiter les résultats de la saisie semi-automatique à une zone géographique spécifique et/ou les filtrer en fonction d'un ou plusieurs types de lieux, ou de cinq pays au maximum. Vous pouvez appliquer ces contraintes à l'activité de saisie semi-automatique, aux AutocompleteSupportFragment et aux API de saisie semi-automatique programmatique.

Pour limiter les résultats, procédez comme suit:

  • Pour privilégier les résultats dans la région définie, appelez setLocationBias() (certains résultats provenant de l'extérieur de la région définie peuvent toutefois être renvoyés).
  • Pour n'afficher que les résultats dans la région définie, appelez setLocationRestriction() (seuls les résultats dans la région définie seront renvoyés).
  • Pour ne renvoyer que des résultats correspondant à un type de lieu particulier, appelez setTypeFilter() (par exemple, en spécifiant TypeFilter.ADDRESS), vous ne renverra que les résultats ayant une adresse précise.
  • Pour ne renvoyer que des résultats situés dans cinq pays au maximum, appelez setCountries(). Les pays doivent être indiqués sous la forme d'un code pays compatible avec la norme ISO 3166-1 Alpha-2 à deux caractères.

Limiter les résultats à une région spécifique

Pour pondérer les résultats de la saisie semi-automatique vers une région géographique spécifique, appelez setLocationBias() en transmettant une valeur RectangularBounds. L'exemple de code suivant montre comment appeler setLocationBias() sur une instance de fragment pour pondérer ses suggestions de saisie semi-automatique vers une région de Sydney, en Australie.

Java


    autocompleteFragment.setLocationBias(RectangularBounds.newInstance(
        new LatLng(-33.880490, 151.184363),
        new LatLng(-33.858754, 151.229596)));

      

Kotlin


    autocompleteFragment.setLocationBias(
        RectangularBounds.newInstance(
            LatLng(-33.880490, 151.184363),
            LatLng(-33.858754, 151.229596)
        )
    )

      

Limiter les résultats à une région spécifique

Pour limiter les résultats de la saisie semi-automatique à une région géographique spécifique, appelez setLocationRestriction() en transmettant une valeur RectangularBounds. L'exemple de code suivant montre comment appeler setLocationRestriction() sur une instance de fragment pour pondérer ses suggestions de saisie semi-automatique vers une région de Sydney, en Australie.

Java


    autocompleteFragment.setLocationRestriction(RectangularBounds.newInstance(
        new LatLng(-33.880490, 151.184363),
        new LatLng(-33.858754, 151.229596)));

      

Kotlin


    autocompleteFragment.setLocationRestriction(
        RectangularBounds.newInstance(
            LatLng(-33.880490, 151.184363),
            LatLng(-33.858754, 151.229596)
        )
    )

      

Remarque:Cette restriction ne s'applique qu'aux routes entières. Les résultats synthétiques situés en dehors des limites rectangulaires peuvent être renvoyés en fonction d'une route qui chevauche la restriction de localisation.

Filtrer les résultats par type de lieu

Vous pouvez limiter les résultats d'une requête de saisie semi-automatique afin qu'ils ne renvoient qu'un certain type de lieu. Si les résultats ne sont pas restreints, tous les types sont renvoyés. En général, un seul type est autorisé. La seule exception est que vous pouvez combiner les types GEOCODE et ESTABLISHMENT en toute sécurité. Toutefois, cela revient à ne spécifier aucun type.

Pour filtrer les résultats de la saisie semi-automatique selon un type de lieu spécifique, appelez setTypeFilter() pour définir le filtre à utiliser. Transmettez ensuite le filtre à un fragment ou un intent.

L'exemple de code suivant montre comment appeler setTypeFilter() sur un objet AutocompleteSupportFragment pour définir un filtre qui renvoie uniquement des résultats avec une adresse précise.

Java


    autocompleteFragment.setTypeFilter(TypeFilter.ADDRESS);

      

Kotlin


    autocompleteFragment.setTypeFilter(TypeFilter.ADDRESS)

      

L'exemple de code suivant montre comment appeler setTypeFilter() sur un objet IntentBuilder pour définir un filtre qui renvoie uniquement des résultats avec une adresse précise.

Java


    Intent intent = new Autocomplete.IntentBuilder(
        AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypeFilter(TypeFilter.ADDRESS)
        .build(this);
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE);

      

Kotlin


    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypeFilter(TypeFilter.ADDRESS)
        .build(this)
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE)

      

Pour en savoir plus sur les types de lieux, consultez le guide sur les types de lieux.

Filtrer les résultats par pays

Pour filtrer les résultats de la saisie semi-automatique jusqu'à cinq pays, appelez setCountries() pour définir le code de pays. Transmettez ensuite le filtre à un fragment ou un intent. Les pays doivent être indiqués sous la forme d'un code pays compatible ISO 3166-1 Alpha-2.

L'exemple de code suivant montre comment appeler setCountries() sur un objet AutocompleteSupportFragment pour définir un filtre qui ne renvoie que les résultats situés dans les pays spécifiés.

Java


    autocompleteFragment.setCountries("AU", "NZ");

      

Kotlin


    autocompleteFragment.setCountries("AU", "NZ")

      

Limites d'utilisation

Votre utilisation de l'API Places, y compris du SDK Places pour Android, n'est plus limitée à un nombre maximal de requêtes par jour (QPD). Toutefois, les limites d'utilisation suivantes s'appliquent toujours:

  • La limite est de 100 requêtes par seconde (RPS). Il correspond à la somme des requêtes côté client et côté serveur pour toutes les applications utilisant les identifiants du même projet.

Afficher les mentions dans votre application

  • Si votre application utilise le service de saisie semi-automatique par programmation, votre interface utilisateur doit afficher une attribution "Powered by Google" ou s'afficher sur une carte Google.
  • Si votre application utilise le widget de saisie semi-automatique, aucune action supplémentaire n'est requise (l'attribution requise s'affiche par défaut).
  • Si vous récupérez et affichez des informations supplémentaires sur un lieu après avoir reçu un lieu par ID, vous devez également afficher les attributions tierces.

Pour en savoir plus, consultez la documentation sur les attributions.

Optimisation de Place Autocomplete

Cette section décrit les bonnes pratiques pour vous aider à tirer le meilleur parti du service Place Autocomplete.

Voici quelques consignes générales:

  • Le moyen le plus rapide de développer une interface utilisateur fonctionnelle consiste à utiliser le widget Autocomplete de l'API Maps JavaScript, le widget Autocomplete du SDK Places pour Android ou le contrôle de l'interface utilisateur Autocomplete du SDK Places pour iOS.
  • Familiarisez-vous d'abord avec les champs de données Place Autocomplete essentiels.
  • Les champs de pondération et de restriction de la zone géographique sont facultatifs, mais peuvent avoir un impact important sur les performances de la saisie semi-automatique.
  • Utilisez la gestion des erreurs pour vous assurer que votre application se dégrade correctement si l'API renvoie une erreur.
  • Assurez-vous que votre application gère les options sans sélection et offre aux utilisateurs un moyen de poursuivre.

Bonnes pratiques en matière d'optimisation des coûts

Optimisation de base des coûts

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

Optimisation avancée des coûts

Envisagez d'implémenter le programmatique Place Autocomplete pour accéder à la tarification par requête et demander des résultats d'API Geocoding pour le lieu sélectionné plutôt que pour Place Details. 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 pour un appel à des adresses autres que Place Details.
  • Si les utilisateurs sélectionnent une prédiction de saisie semi-automatique dans une moyenne de quatre requêtes de prédiction de saisie semi-automatique ou moins, la tarification par requête peut s'avérer plus rentable que la tarification par session.
Pour obtenir de l'aide concernant la mise en œuvre de Place Autocomplete selon vos besoins, sélectionnez l'onglet correspondant à votre réponse à la question suivante.

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

Oui, j'ai besoin de plus d'informations

Utiliser Place Autocomplete basé sur des sessions avec Place Details
Étant donné que votre application nécessite Place Details, comme le nom du lieu, l'état de l'établissement ou les horaires d'ouverture, vous devez utiliser un jeton de session (programmatique ou intégré aux widgets JavaScript, Android ou iOS) pour un coût total de 0,017 $par session plus les codes SKU Places Data applicables, selon les champs de données de lieu que vous demandez.

Implémentation de widgets
La gestion de sessions est automatiquement intégrée aux widgets JavaScript, Android ou iOS. Cela inclut les requêtes Place Autocomplete et la requête Places Details pour la prédiction sélectionnée. Veillez à spécifier le paramètre fields afin de vous assurer de ne demander que les champs de données de lieu dont vous avez besoin.

Implémentation programmatique
Utilisez un jeton de session avec vos requêtes Place Autocomplete. Lorsque vous demandez des détails sur un lieu à propos de la prédiction sélectionnée, incluez les paramètres suivants:

  1. ID de lieu figurant dans la réponse Place Autocomplete
  2. Jeton de session utilisé dans la requête Place Autocomplete
  3. Le paramètre fields spécifiant les champs de données de lieu dont vous avez besoin

Non, je n'ai besoin que de l'adresse et du lieu

L'API Geocoding peut être une option plus rentable que Place Details pour votre application, en fonction des performances d'utilisation de Place Autocomplete. L'efficacité de la saisie semi-automatique dépend de l'entrée de l'application, de l'emplacement où elle est utilisée et de l'application ou non de bonnes pratiques en matière d'optimisation des performances.

Afin de répondre à la question suivante, analysez le nombre moyen de caractères saisis par un utilisateur avant de sélectionner une prédiction Place Autocomplete dans votre application.

Vos utilisateurs sélectionnent-ils en moyenne une prédiction Place Autocomplete en quatre requêtes maximum ?

Yes

Implémentez Place Autocomplete par programmation sans jetons de session et appelez l'API Geocoding sur la prédiction de lieu sélectionnée.
L'API Geocoding fournit des adresses et des coordonnées de latitude/longitude pour 0,005 $par requête. Le coût total de quatre requêtes Place Autocomplete – Per Request est de 0,01132 $. Le coût total de quatre requêtes plus un appel de l'API Geocoding pour la prédiction de lieu sélectionnée s'élève donc à 0,01632 $, ce qui est inférieur au prix par session de saisie semi-automatique de 0,017 $par session1.

Envisagez d'appliquer les bonnes pratiques en matière de performances pour aider vos utilisateurs à obtenir la prédiction qu'ils recherchent en utilisant moins de caractères.

Non

Utiliser Place Autocomplete basé sur des sessions avec Place Details
Étant donné que le nombre moyen de requêtes que vous prévoyez d'effectuer avant qu'un utilisateur ne sélectionne une prédiction Place Autocomplete dépasse le coût par session, votre implémentation de Place Autocomplete doit utiliser un jeton de session pour les requêtes Place Autocomplete et la requête Places Details associée, pour un coût total de 0,017 $par session1.

Implémentation de widgets
La gestion de sessions est automatiquement intégrée aux widgets JavaScript, Android ou iOS. Cela inclut les requêtes Place Autocomplete et la requête Places Details pour la prédiction sélectionnée. Veillez à spécifier le paramètre fields afin de vous assurer de ne demander que les champs Basic Data (Données de base).

Implémentation programmatique
Utilisez un jeton de session avec vos requêtes Place Autocomplete. Lorsque vous demandez des détails sur un lieu à propos de la prédiction sélectionnée, incluez les paramètres suivants:

  1. ID de lieu figurant dans la réponse Place Autocomplete
  2. Jeton de session utilisé dans la requête Place Autocomplete
  3. Paramètre fields spécifiant les champs de données de base tels que l'adresse et la géométrie

Envisager de retarder les requêtes Place Autocomplete
Vous pouvez appliquer des stratégies telles que le report d'une requête Place Autocomplete jusqu'à ce que l'utilisateur ait saisi les trois ou quatre premiers caractères afin que votre application envoie moins de requêtes. Par exemple, si vous effectuez des requêtes Place Autocomplete pour chaque caractère après que l'utilisateur a saisi le troisième caractère, cela signifie que s'il sélectionne sept caractères, puis sélectionne une prédiction pour laquelle vous effectuez une requête API Geocoding, le coût total sera de 0,01632 $ (4 x 0,00283 $ par requête semi-automatique + 0,005 $Geocoding).1

Si votre demande moyenne programmatique peut être inférieure à quatre, vous pouvez suivre les conseils pour l'implémentation de Place Autocomplete performante avec l'API Geocoding. Notez que les requêtes retardées peuvent être perçues comme de la latence par l'utilisateur, qui peut s'attendre à voir des prédictions à chaque nouvelle frappe.

Envisagez d'appliquer les bonnes pratiques en matière de performances pour aider vos utilisateurs à obtenir la prédiction qu'ils recherchent en utilisant moins de caractères.


  1. Les coûts indiqués ici sont en USD. Pour obtenir toutes les informations tarifaires, consultez la page Facturation Google Maps Platform.

Bonnes pratiques en matière de performances

Les consignes suivantes décrivent les méthodes permettant d'optimiser les performances de Place Autocomplete:

  • Ajoutez des restrictions locales, une pondération géographique et des préférences linguistiques (pour les implémentations programmatiques) à votre implémentation Place Autocomplete. Aucune préférence linguistique n'est requise avec les widgets, car ils sélectionnent les préférences linguistiques dans le navigateur ou l'appareil mobile de l'utilisateur.
  • Si Place Autocomplete est accompagné 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, généralement parce qu'aucune de ces prédictions n'est l'adresse de résultat 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, utilisez l'entrée utilisateur d'origine dans un appel à l'API Geocoding.
    • Si vous souhaitez que l'utilisateur saisit des requêtes pour un lieu spécifique en fonction de son nom ou de son adresse, utilisez une requête Find Place. 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 recourir à l'API Geocoding :
    • Utilisateurs saisissant des adresses de sous-réseaux autres que l'Australie, le Canada et la Nouvelle-Zélande. Par exemple, l'adresse américaine "123 Bowdoin St #456, Boston MA, États-Unis" n'est pas acceptée par Autocomplete. (La saisie semi-automatique n'accepte les adresses de sous-réseaux qu'en Australie, au Canada et en Nouvelle-Zélande. Les formats d'adresse acceptés dans ces trois pays sont les suivants : "9/321 Pitt Street, Sydney, Nouvelle-Galles du Sud, Australie" ou "14/19 Langana Avenue, Browns Bay, Auckland, Nouvelle-Zélande" ou "145-112 Renfrew Dr, Markham, Ontario, Canada".
    • Utilisateurs saisissant des adresses avec des préfixes de segment de route tels que "23-30 29th St, Queens" à New York ou "47-380 Kamehameha Hwy, Kaneohe" sur l'île de Kauai à Hawai.

Dépannage

Bien qu'une grande variété d'erreurs puissent se produire, la majorité des erreurs susceptibles d'être rencontrées par votre application sont généralement dues à des erreurs de configuration (par exemple, erreur d'utilisation de la clé API ou configuration incorrecte de la clé API) ou à des erreurs de quota (votre application a dépassé son quota). Pour en savoir plus sur les quotas, consultez la page Limites d'utilisation.

Les erreurs qui se produisent lors de l'utilisation des commandes de saisie semi-automatique sont renvoyées dans le rappel onActivityResult(). Appelez Autocomplete.getStatus() pour obtenir le message d'état du résultat.