Le service de saisie semi-automatique du SDK Places pour Android renvoie en réponse aux requêtes de recherche des utilisateurs. Au fur et à mesure que l'utilisateur tape, de saisie semi-automatique renvoie des suggestions pour des lieux des adresses postales, des plus codes et les points d'intérêt.
Vous pouvez ajouter Autocomplete à votre application de plusieurs façons :
- Ajoutez un widget de saisie semi-automatique pour enregistrer. de développement et garantir une expérience utilisateur cohérente.
- Obtenir des prédictions de lieux de manière programmatique pour créer expérience utilisateur personnalisée.
Ajouter un widget de saisie semi-automatique
Le widget de saisie semi-automatique est une boîte de dialogue de recherche avec saisie semi-automatique intégrée.
de Google Cloud. À mesure qu'un utilisateur saisit des termes de recherche, le widget affiche une liste de
de prédictions de lieux à choisir. Lorsque l'utilisateur effectue une sélection,
Place
que votre application peut utiliser pour obtenir des informations
le lieu sélectionné.
Deux options sont possibles pour ajouter un widget Autocomplete à votre application :
- Option 1: Intégrer un
AutocompleteSupportFragment
- Option 2: Utiliser un intent pour lancer l'activité de saisie semi-automatique
Option 1: Intégrer un AutocompleteSupportFragment
Pour ajouter un AutocompleteSupportFragment
à votre application, procédez comme suit:
- Ajoutez un fragment à la mise en page XML de votre activité.
- 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 une apparence visuelle cohérente, imbriquez le fragment dans une autre mise en page. tel que CardView :
- Si vous utilisez le fragment Autocomplete et que vous devez remplacer
onActivityResult
, vous devez appelersuper.onActivityResult
. Sinon, la fonction fragment ne fonctionnera pas correctement.
Ajouter un PlaceSelectionListener à une activité
PlaceSelectionListener
gère le renvoi d'un lieu en réponse à la demande de l'utilisateur
de votre choix. Le code suivant montre comment créer une référence au fragment et
en ajoutant un écouteur à votre AutocompleteSupportFragment
:
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") } })
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); } });
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 la saisie semi-automatique à partir d'une icône plutôt que d'un champ de recherche) votre application peut lancer la saisie automatique à l'aide d'un intent.
Pour lancer le widget de saisie semi-automatique en utilisant un intent, procédez comme suit :
- Utiliser
Autocomplete.IntentBuilder
pour créer un intent en transmettant le modeAutocomplete
souhaité. - Définir un lanceur de résultats d'activité
registerForActivityResult
qui permet de lancer l'intent et de gérer l'emplacement sélectionné par l'utilisateur dans le résultat.
Créer un intent de saisie semi-automatique
L'exemple ci-dessous utilise
Autocomplete.IntentBuilder
Pour créer un intent et lancer le widget de saisie semi-automatique en tant qu'intent, procédez comme suit:
Kotlin
// 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) startAutocomplete.launch(intent)
Java
// 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); startAutocomplete.launch(intent);
Lorsque vous utilisez un intent pour lancer le widget de saisie semi-automatique, vous pouvez choisir superposition ou l'affichage plein écran. Les captures d'écran suivantes montrent chacune mode d'affichage respectivement:
![Lorsqu'il est affiché en mode superposition, le widget de saisie semi-automatique apparaît en superposition sur l'interface utilisateur qui est à l'origine de l'appel.](https://developers.google.cn/static/maps/documentation/places/images/acw_overlay.png?authuser=6&hl=fr)
![Lorsqu'il est affiché en mode plein écran, le widget de saisie semi-automatique occupe la totalité de l'écran.](https://developers.google.cn/static/maps/documentation/places/images/acw_fullscreen.png?authuser=6&hl=fr)
Enregistrer un rappel pour le résultat de l'intent
Pour recevoir une notification lorsque l'utilisateur a sélectionné un lieu, définissez un
Le lanceur d'applications registerForActivityResult()
, qui lance l'activité et gère également les
comme illustré dans l'exemple suivant. Si l'utilisateur a sélectionné une prédiction,
est transmis dans l'intent contenu dans l'objet de résultat. Puisque l'intent
a été créée par Autocomplete.IntentBuilder
, la méthode
Autocomplete.getPlaceFromIntent()
peut en extraire l'objet Place.
Kotlin
private val startAutocomplete = registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult -> if (result.resultCode == Activity.RESULT_OK) { val intent = result.data if (intent != null) { val place = Autocomplete.getPlaceFromIntent(intent) Log.i( TAG, "Place: ${place.name}, ${place.id}" ) } } else if (result.resultCode == Activity.RESULT_CANCELED) { // The user canceled the operation. Log.i(TAG, "User canceled autocomplete") } }
Java
private final ActivityResultLauncher<Intent> startAutocomplete = registerForActivityResult( new ActivityResultContracts.StartActivityForResult(), result -> { if (result.getResultCode() == Activity.RESULT_OK) { Intent intent = result.getData(); if (intent != null) { Place place = Autocomplete.getPlaceFromIntent(intent); Log.i(TAG, "Place: ${place.getName()}, ${place.getId()}"); } } else if (result.getResultCode() == Activity.RESULT_CANCELED) { // The user canceled the operation. Log.i(TAG, "User canceled autocomplete"); } });
Obtenir des prédictions de lieu par programmation
Vous pouvez créer une interface utilisateur de recherche personnalisée à la place de l'interface utilisateur fournie par le
de saisie semi-automatique. Pour ce faire, votre application doit obtenir des prédictions de lieu
de manière programmatique. 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
avec les paramètres suivants:
- Obligatoire:une chaîne
query
contenant le texte saisi par l'utilisateur. - Recommandé:A
AutocompleteSessionToken
qui regroupe les phases de requête et de sélection d'une recherche utilisateur dans un ensemble de à des fins de facturation. La session commence lorsque l'utilisateur commence à saisir du texte. une requête et se termine lorsqu'il sélectionne un lieu. - Recommandation:
RectangularBounds
, qui spécifie les limites de latitude et de longitude pour limiter les résultats dans la région spécifiée. - Facultatif:un ou plusieurs pays à deux lettres (ISO 3166-1) Alpha-2), indiquant le ou les pays auxquels les résultats doivent être renvoyés. restreintes.
Facultatif:A
TypeFilter
que vous pouvez utiliser pour limiter les résultats au type de lieu spécifié. La les types de lieux suivants sont acceptés:TypeFilter.GEOCODE
: renvoie uniquement les résultats de geocoding les entreprises. Utilisez cette requête pour lever l'ambiguïté sur les résultats lorsque de localisation peut être indéterminée.TypeFilter.ADDRESS
: renvoie uniquement les résultats de la saisie semi-automatique avec un une adresse précise. Utilisez ce type de requête lorsque vous savez que l'utilisateur recherche adresse entièrement spécifiée.TypeFilter.ESTABLISHMENT
: renvoie uniquement les lieux qui sont les entreprises.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
ouADMINISTRATIVE_AREA_LEVEL_3
Facultatif:un champ
LatLng
spécifiant le lieu d'origine de la requête. Lorsque vous appelezsetOrigin()
, le service renvoie la distance en mètres (distanceMeters
) de la valeur pour chaque prédiction de saisie semi-automatique contenue dans la réponse.
Pour en savoir plus sur les types de lieux, consultez le guide Place différents types d'appareil.
L'exemple ci-dessous illustre un appel complet à
PlacesClient.findAutocompletePredictions()
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") .setTypesFilter(listOf(PlaceTypes.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}") } }
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") .setTypesFilter(Arrays.asList(PlaceTypes.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()); } });
L'API renvoie une
FindAutocompletePredictionsResponse
dans un
Task
FindAutocompletePredictionsResponse
contient une liste
AutocompletePrediction
objets représentant des lieux prédits. La liste peut être vide en l'absence de
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 utilisantCharacterStyle
Le paramètreCharacterStyle
est facultatif. Définissez-le sur "null" n'ont pas besoin d'être mises en évidence.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 laPlace
ultérieurement. Pour en savoir plus sur les ID de lieu dans SDK Places pour Android, consultez la page Place Détails. Généralités d'informations sur les identifiants de lieu, consultez le document Place ID présentation.getPlaceTypes()
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.
Jetons de session
Les jetons de session regroupent les phases de requête et de sélection d'une saisie semi-automatique de l'utilisateur une recherche dans une session distincte à 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).
Le SDK Places pour Android utilise un
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.
En savoir plus sur les sessions les jetons.
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
filtrer les résultats pour n'afficher qu'un ou plusieurs types de lieux, ou jusqu'à cinq pays. Toi
appliquer ces contraintes
à la saisie semi-automatique
AutocompleteSupportFragment
et les API de saisie semi-automatique programmatique.
Pour contraindre les résultats, procédez comme suit:
- Pour privilégier les résultats dans la région définie, appelez
setLocationBias()
(certains résultats situés en dehors de la région définie peuvent tout de même être renvoyés). - Pour afficher uniquement les résultats de la région définie, appelez
setLocationRestriction()
(seuls les résultats situés dans la région définie sont renvoyé). - Pour renvoyer uniquement les résultats conformes à un type de lieu particulier, appelez
setTypesFilter()
(par exemple, si vous spécifiezTypeFilter.ADDRESS
, le résultat les résultats avec une adresse précise uniquement). - Pour renvoyer uniquement les résultats correspondant à un maximum de cinq pays spécifiés, appelez
setCountries()
Les pays doivent être transmis, au format ISO 3166-1, à deux caractères. Pays compatible avec la version alpha-2 code.
Limiter les résultats à une région spécifique
Pour limiter les résultats de la saisie semi-automatique à une zone géographique spécifique, appelez
setLocationBias()
, qui transmet une
RectangularBounds
L'exemple de code suivant montre comment appeler setLocationBias()
sur un fragment
pour orienter ses suggestions de saisie semi-automatique vers une région de Sydney, en Australie.
Kotlin
autocompleteFragment.setLocationBias( RectangularBounds.newInstance( LatLng(-33.880490, 151.184363), LatLng(-33.858754, 151.229596) ) )
Java
autocompleteFragment.setLocationBias(RectangularBounds.newInstance( new LatLng(-33.880490, 151.184363), new 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 zone géographique spécifique, appelez
setLocationRestriction()
, qui transmet une
RectangularBounds
L'exemple de code suivant montre comment appeler setLocationRestriction()
sur un
pour orienter ses suggestions de saisie semi-automatique vers une région de Sydney,
Australie.
Kotlin
autocompleteFragment.setLocationRestriction( RectangularBounds.newInstance( LatLng(-33.880490, 151.184363), LatLng(-33.858754, 151.229596) ) )
Java
autocompleteFragment.setLocationRestriction(RectangularBounds.newInstance( new LatLng(-33.880490, 151.184363), new LatLng(-33.858754, 151.229596)));
Remarque:Cette restriction ne s'applique qu'aux routes entières, les résultats synthétiques situées en dehors des limites rectangulaires peuvent être renvoyées en fonction d'un itinéraire chevauche la restriction géographique.
Filtrer les résultats par type de lieu ou par collection de types
Vous pouvez limiter les résultats d'une requête de saisie semi-automatique pour qu'ils ne renvoient qu'un un certain type de lieu. Spécifiez un filtre à l'aide des types de lieux ou d'une collection de types répertoriés dans les tableaux 1, 2 et 3 de la section Types de lieux. Si rien n'est spécifié, tous les types sont renvoyés.
Pour filtrer les résultats de la saisie semi-automatique, appelez
setTypesFilter()
pour définir le filtre.
Pour spécifier un filtre de type ou de collection de types:
Appelez
setTypesFilter()
et spécifiez jusqu'à cinq valeurs type du tableau 1. et le tableau 2 figurant sur les types de lieux. Les valeurs de type sont définies par les constantes PlaceTypes.Appelez
setTypesFilter()
et spécifiez une collection de types à partir du tableau 3 indiqué. sur les types de lieux. Les valeurs de collection sont définies par constantes dans PlaceTypes.Un seul type du Tableau 3 est autorisé dans la requête. Si vous spécifiez un du Tableau 3, vous ne pouvez pas spécifier de valeur du Tableau 1 ni du Tableau 2. Si une erreur se produit.
L'exemple de code suivant appelle setTypesFilter()
sur un
AutocompleteSupportFragment
et spécifie plusieurs valeurs de type.
Kotlin
autocompleteFragment.setTypesFilter(listOf("landmark", "restaurant", "store"))
Java
autocompleteFragment.setTypesFilter(Arrays.asList("landmark", "restaurant", "store"));
L'exemple de code suivant montre comment appeler setTypesFilter()
sur un
AutocompleteSupportFragment
pour définir un filtre ne renvoyant que les résultats avec un
en spécifiant une collection de types.
Kotlin
autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))
Java
autocompleteFragment.setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS, PlaceTypes.ESTABLISHMENT));
L'exemple de code suivant montre comment appeler setTypesFilter()
sur un
IntentBuilder
pour définir un filtre renvoyant uniquement les résultats avec une adresse précise par
spécifiant une collection de types.
Kotlin
val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields) .setTypesFilter(listOf(PlaceTypes.ADDRESS)) .build(this)
Java
Intent intent = new Autocomplete.IntentBuilder( AutocompleteActivityMode.FULLSCREEN, fields) .setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS)) .build(this);
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 pays.
Transmettez ensuite le filtre à un fragment ou un intent. Les pays doivent être indiqués au format
pays à 2 caractères, compatible avec la norme ISO 3166-1 Alpha-2
code.
L'exemple de code suivant montre comment appeler setCountries()
sur un
AutocompleteSupportFragment
, pour définir un filtre ne renvoyant que les résultats compris dans
dans certains pays.
Kotlin
autocompleteFragment.setCountries("AU", "NZ")
Java
autocompleteFragment.setCountries("AU", "NZ");
Limites d'utilisation
Votre utilisation de l'API Places, y compris du SDK Places pour Android, est de n'est plus limité à un nombre maximal de requêtes par jour (QPD). Toutefois, les limites d'utilisation suivantes continuent de s'appliquer:
- La limite de débit est de 6 000 RPM (requêtes par minute). Il est il correspond à la somme des requêtes côté client et côté serveur pour toutes les requêtes des applications à l'aide des identifiants du même projet.
Afficher les mentions dans votre application
- Si votre application utilise le service de saisie semi-automatique de manière programmatique, votre UI doit affichent la mention « Fourni par Google » l'attribution, ou s'affichent dans un Carte Google.
- Aucune action supplémentaire n'est requise si votre application utilise le widget de saisie semi-automatique (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 placé par ID, vous doivent également afficher les mentions tierces.
Pour en savoir plus, consultez la documentation attributions.
Optimisation de Place Autocomplete
Cette section décrit les bonnes pratiques pour vous aider à exploiter au mieux le 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 la commande d'interface utilisateur Autocomplete du SDK Places pour iOS.
- Développez dès le départ vos connaissances des champs de données Place Autocomplete 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 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 Place Autocomplete de manière programmatique pour accéder au tarif 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 à un prix inférieur à celui d'un appel Place Details.
- Si les utilisateurs sélectionnent une prédiction de saisie semi-automatique toutes les quatre requêtes de prédiction 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 ?
Oui, elle a besoin de plus d'informations
Utilisez Place Autocomplete basé sur des sessions avec Place Details
Étant donné que votre application nécessite des informations Places Details telles que le nom du lieu, l'état de l'établissement ou les horaires d'ouverture, votre implémentation de Place Autocomplete doit utiliser un jeton de session (de manière programmatique ou intégré aux widgets JavaScript, Android ou iOS) pour un coût total de 0,017 $ par session, auquel s'ajoutent les SKU Places Data en fonction des champs de données de lieu que vous demandez1.
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
pour 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 concernant la prédiction sélectionnée, incluez les paramètres suivants :
- ID de lieu figurant dans la réponse Place Autocomplete
- Jeton de session utilisé dans la requête Place Autocomplete
- Le paramètre
fields
spécifiant les champs de données de lieu dont vous avez besoin
Non, seuls les adresses et les lieux sont nécessaires
L'API Geocoding peut être une option plus rentable que Place Details pour votre application, en fonction de vos performances d'utilisation de Place Autocomplete. L'efficacité de la saisie semi-automatique varie d'une application à l'autre en fonction des informations saisies, du lieu d'utilisation de l'application et de l'implémentation des bonnes pratiques d'optimisation des performances.
Afin de répondre à la question suivante, analysez le nombre moyen de caractères saisis par un utilisateur avant qu'il sélectionne une prédiction Place Autocomplete dans votre application.
En moyenne, vos utilisateurs sélectionnent-ils une prédiction Place Autocomplete en quatre requêtes ou moins ?
Oui
Implémentez Place Autocomplete de manière programmatique sans jeton de session, puis 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 de quatre requêtes Place Autocomplete – Par requête 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 $, soit moins que le tarif Autocomplete par session (0,017 $ par session)1.
Pensez à appliquer les bonnes pratiques liées aux performances pour aider vos utilisateurs à obtenir la prédiction qu'ils recherchent en utilisant moins de caractères.
Non
Utilisez 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 Place 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 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 concernant la prédiction sélectionnée, incluez les paramètres suivants :
- ID de lieu figurant dans la réponse Place Autocomplete
- Jeton de session utilisé dans la requête Place Autocomplete
- Paramètre
fields
spécifiant les champs de données de base comme l'adresse et la géométrie
Envisagez de reporter 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. Votre application enverra ainsi 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, s'il en saisit sept, 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 $ pour la saisie semi-automatique par requête + 0,005 $ pour Geocoding)1.
Si, à cause du report de requêtes, votre requête programmatique moyenne est inférieure à quatre, vous pouvez suivre les instructions pour intégrer efficacement Place Autocomplete à l'API Geocoding. Notez que les requêtes reportées peuvent être perçues comme de la latence par l'utilisateur, qui peut s'attendre à voir des prédictions à chaque nouvelle frappe.
Pensez à appliquer les bonnes pratiques liées aux performances pour aider vos utilisateurs à obtenir la prédiction qu'ils recherchent en utilisant moins de caractères.
-
Les coûts indiqués ici sont exprimés en USD. Pour obtenir des informations complètes sur les tarifs, consultez la page Facturation Google Maps Platform.
Bonnes pratiques liées aux 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. 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 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 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 Find Place. Si les résultats ne sont attendus que dans une région spécifique, utilisez la pondération géographique.
- Lorsque des utilisateurs saisissent des compléments d'adresse dans des pays où Place Autocomplete n'est pas totalement compatible avec ce type d'adresses : Estonie, Lituanie et Tchéquie, par exemple. Par exemple, l'adresse tchèque "Stroupežnického 3191/17, Praha" génère une prédiction partielle dans Place Autocomplete.
- 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ï.
Dépannage
Bien qu'une grande variété d'erreurs puissent se produire, la majorité d'entre elles sont généralement causées par des erreurs de configuration (par exemple, si vous avez utilisé une clé API incorrecte ou si la clé API n'a pas été configurée correctement) ou quota (votre application a dépassé son quota). Voir Utilisation les limites. des informations sur les quotas.
Les erreurs qui se produisent lorsque vous utilisez les commandes de saisie semi-automatique sont renvoyées dans la
Rappel onActivityResult()
. Appelez Autocomplete.getStatus()
pour obtenir l'état
pour le résultat.