Place Autocomplete (ancienne version) est un service Web qui renvoie des prédictions de lieux en réponse à une requête HTTP. La requête spécifie une chaîne de recherche textuelle et des limites géographiques facultatives. Le service peut être utilisé pour fournir une fonctionnalité de saisie semi-automatique pour les recherches géographiques textuelles, en renvoyant des lieux tels que des établissements, des adresses et des points d'intérêt à mesure que l'utilisateur saisit du texte.
Requêtes Place Autocomplete (ancienne version)
Place Autocomplete (ancienne version) fait partie de l'API Places et partage une clé API et des quotas avec l'API Places.
Place Autocomplete (ancienne version) peut établir une correspondance avec des mots complets et des sous-chaînes afin de trouver des noms de lieux, des adresses et des Plus Codes. Ainsi, les applications peuvent envoyer des requêtes lors de la frappe pour indiquer les lieux possibles à la volée.
Vous devez mettre en forme les Plus Codes correctement. Cela signifie que vous devez échapper le signe plus en %2B et les espaces en %20.
- Le code global est un indicatif de zone de quatre caractères et un code local à six caractères ou plus. Par exemple, le code global d'échappement d'URL
849VCWC8+R9est849VCWC8%2BR9. - Le code composé est un code local à six caractères (ou plus) associé à un emplacement explicite. Par exemple, le code plus composé avec échappement d'URL
CWC8+R9 Mountain View, CA, USAestCWC8%2BR9%20Mountain%20View%20CA%20USA.
Les prédictions renvoyées sont conçues pour être présentées à l'utilisateur afin de l'aider à sélectionner le lieu de son choix. Vous pouvez envoyer une requête Place Details (ancienne version) pour obtenir plus d'informations sur les lieux renvoyés.
Une requête Place Autocomplete (ancienne version) est une URL HTTP au format suivant :
https://maps.googleapis.com/maps/api/place/autocomplete/output?parameters
où output peut correspondre à l'une des valeurs suivantes :
json(recommandé) indique une sortie au format JSON (JavaScript Object Notation).xmlindique une sortie au format XML.
Certains paramètres sont obligatoires pour lancer une requête Place Autocomplete (ancienne version).
Comme c'est la norme pour les URL, les différents paramètres sont séparés par une esperluette (&). La liste des paramètres et de leurs valeurs possibles est énumérée ci-dessous.
Paramètres obligatoires
entrée
Chaîne de texte sur laquelle effectuer la recherche. Le service Place Autocomplete renvoie les résultats correspondant à cette chaîne et les classe en fonction de leur pertinence estimée.
Paramètres facultatifs
composants
Regroupement de lieux auxquels vous souhaitez limiter vos résultats.
Vous pouvez utiliser des composants pour filtrer jusqu'à cinq pays.
Les pays doivent être transmis sous la forme d'un code pays à deux caractères conforme à la norme ISO 3166-1 Alpha-2. Par exemple, components=country:fr limite les résultats aux lieux situés en France. Pour transmettre plusieurs pays, vous devez utiliser plusieurs filtres country:XX, en les séparant par une barre verticale |. Par exemple, components=country:us|country:pr|country:vi|country:gu|country:mp limite les résultats aux lieux situés aux États-Unis et dans ses territoires organisés non incorporés.
language
Langue dans laquelle les résultats doivent être renvoyés.
- Consultez la liste des langues acceptées. Google met souvent à jour les langues acceptées. Cette liste n'est donc pas exhaustive.
-
Si
languagen'est pas fourni, l'API tente d'utiliser la langue préférée spécifiée dans l'en-têteAccept-Language. - L'API s'efforce de fournir une adresse postale lisible à la fois pour l'utilisateur et pour les habitants. Pour atteindre cet objectif, elle renvoie les adresses postales dans la langue locale, translittérées dans un script lisible par l'utilisateur si nécessaire, en respectant la langue préférée. Toutes les autres adresses sont renvoyées dans la langue préférée. Les composants d'adresse sont tous renvoyés dans la même langue, qui est choisie à partir du premier composant.
- Si aucun nom n'est disponible dans la langue préférée, l'API utilise la correspondance la plus proche.
- La langue préférée a une légère influence sur l'ensemble des résultats que l'API choisit de renvoyer et sur l'ordre dans lequel ils sont renvoyés. Le geocoder interprète les abréviations différemment selon la langue, par exemple les abréviations des types de rues ou les synonymes qui peuvent être valides dans une langue, mais pas dans une autre. Par exemple, utca et tér sont des synonymes de "rue" en hongrois.
position
Point autour duquel récupérer les informations sur le lieu. Cette valeur doit être spécifiée en tant que latitude,longitude. Le paramètre radius doit également être fourni lorsque vous spécifiez un emplacement. Si radius n'est pas fourni, le paramètre location est ignoré.
locationbias
Privilégiez les résultats dans une zone spécifiée, en indiquant un rayon et une latitude/longitude, ou deux paires de latitude/longitude représentant les points d'un rectangle. Si ce paramètre n'est pas spécifié, l'API utilise par défaut la pondération par adresse IP.
-
Biais d'adresse IP : indique à l'API d'utiliser le biais d'adresse IP. Transmettez la chaîne
ipbias(cette option ne comporte aucun paramètre supplémentaire). -
Circulaire : chaîne spécifiant le rayon en mètres, ainsi que la latitude et la longitude en degrés décimaux. Utilisez le format suivant :
circle:radius@lat,lng. -
Rectangulaire : chaîne spécifiant deux paires de latitude/longitude en degrés décimaux, représentant les points sud/ouest et nord/est d'un rectangle. Utilisez le format suivant :
rectangle:south,west|north,east. Notez que les valeurs est/ouest sont comprises entre -180 et 180, et que les valeurs nord/sud sont comprises entre -90 et 90.
locationrestriction
Limitez les résultats à une zone spécifique en indiquant un rayon et une latitude/longitude, ou deux paires de latitude/longitude représentant les points d'un rectangle.
-
Circulaire : chaîne spécifiant le rayon en mètres, ainsi que la latitude et la longitude en degrés décimaux. Utilisez le format suivant :
circle:radius@lat,lng. -
Rectangulaire : chaîne spécifiant deux paires de latitude/longitude en degrés décimaux, représentant les points sud/ouest et nord/est d'un rectangle. Utilisez le format suivant :
rectangle:south,west|north,east. Notez que les valeurs est/ouest sont comprises entre -180 et 180, et que les valeurs nord/sud sont comprises entre -90 et 90.
offset
Position, dans le terme d'entrée, du dernier caractère utilisé par le service pour faire correspondre les prédictions. Par exemple, si l'entrée est Google et que le décalage est de 3, le service correspondra à Goo. La chaîne déterminée par le décalage est mise en correspondance uniquement avec le premier mot du terme d'entrée. Par exemple, si le terme d'entrée est Google abc et que le décalage est de 3, le service tentera de trouver une correspondance avec Goo abc. Si aucun décalage n'est fourni, le service utilisera l'intégralité du terme. Le décalage doit généralement être défini sur la position du curseur de saisie.
origin
Point d'origine à partir duquel calculer la distance en ligne droite jusqu'à la destination (renvoyée sous la forme distance_meters). Si cette valeur est omise, la distance en ligne droite ne sera pas renvoyée. Doit être spécifié sous la forme latitude,longitude.
rayon
Définit la distance (en mètres) dans laquelle renvoyer les résultats de lieux. Vous pouvez affiner les résultats à un cercle donné en transmettant les paramètres location et radius. Vous indiquez ainsi au service Places de privilégier les résultats situés à l'intérieur de ce cercle. Des résultats en dehors de la zone définie peuvent toutefois être affichés.
Le rayon est automatiquement limité à une valeur maximale en fonction du type de recherche et d'autres paramètres.
- Saisie semi-automatique : 50 000 mètres
-
Nearby Search :
- avec
keywordouname: 50 000 mètres -
sans
keywordniname-
Jusqu'à 50 000 mètres, ajusté de manière dynamique en fonction de la densité de la zone, indépendamment du paramètre
rankby. -
Lorsque vous utilisez
rankby=distance, le paramètre "radius" n'est pas accepté et génère une erreurINVALID_REQUEST.
-
Jusqu'à 50 000 mètres, ajusté de manière dynamique en fonction de la densité de la zone, indépendamment du paramètre
- avec
- Query Autocomplete : 50 000 mètres
- Text Search : 50 000 mètres
région
Code régional, 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").
sessiontoken
Chaîne aléatoire qui identifie une session de saisie semi-automatique à des fins de facturation.
La session commence lorsque l'utilisateur commence à saisir une requête et se termine lorsqu'il sélectionne un lieu et qu'un appel Place Details est effectué. Chaque session peut comporter plusieurs requêtes, suivies d'une sélection de lieu. La ou les clés API utilisées pour chaque requête d'une session doivent appartenir au même projet de la console Google Cloud. Lorsque la session prend fin, le jeton n'est plus valide. Votre application doit générer un nouveau jeton pour chaque session. Si vous omettez le paramètre sessiontoken ou si vous réutilisez un jeton de session, la session est facturée comme si aucun jeton n'était fourni (chaque requête est facturée séparément).
Nous vous recommandons de respecter les consignes suivantes:
- Utilisez des jetons de session pour toutes les sessions de saisie semi-automatique.
- Générez un nouveau jeton pour chaque session. Nous vous recommandons d'utiliser la version 4 de l'UUID.
- Assurez-vous que les clés API utilisées pour toutes les requêtes Place Autocomplete et Place Details d'une session appartiennent au même projet de la console Cloud.
- N'oubliez pas de transmettre un jeton de session unique pour chaque nouvelle session. Si vous utilisez le même jeton pour plusieurs sessions, chaque requête est facturée individuellement.
strictbounds
Renvoie uniquement les lieux qui se trouvent strictement dans la région définie par location et radius. Il s'agit d'une restriction, et non d'un biais, ce qui signifie que les résultats en dehors de cette région ne seront pas renvoyés, même s'ils correspondent à l'entrée utilisateur.
Types
Vous pouvez limiter les résultats d'une requête Place Autocomplete à un certain type en transmettant le paramètre types. Ce paramètre spécifie un type ou une collection de types, comme indiqué dans Types de lieux. Si aucun paramètre n'est spécifié, tous les types sont renvoyés.
Un lieu ne peut avoir qu'un seul type principal parmi les types listés dans le Tableau 1 ou le Tableau 2. Par exemple, un hôtel où des repas sont servis peut être renvoyé uniquement avec types=lodging et non avec types=restaurant.
Pour la valeur du paramètre types, vous pouvez spécifier soit :
-
Jusqu'à cinq valeurs du Tableau 1 ou du Tableau 2. Si vous avez plusieurs valeurs, séparez-les par une barre verticale (
|). Exemple :types=book_store|cafe -
un seul filtre compatible du Tableau 3. Vous ne pouvez pas combiner des collections de types.
La requête sera rejetée avec une erreur INVALID_REQUEST si :
- Plus de cinq types sont spécifiés.
- des types non reconnus sont présents ;
- Des types du Tableau 1 ou du Tableau 2 sont mélangés avec des filtres du Tableau 3.
Exemples de Place Autocomplete (ancienne version)
Une requête d'établissements contenant la chaîne "Amoeba" dans une zone centrée sur San Francisco, en Californie :
URL
https://maps.googleapis.com/maps/api/place/autocomplete/json ?input=amoeba &types=establishment &location=37.76999%2C-122.44696 &radius=500 &key=YOUR_API_KEY
curl
curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=amoeba&types=establishment&location=37.76999%2C-122.44696&radius=500&key=YOUR_API_KEY'La même requête, limitée aux résultats situés dans un rayon de 500 mètres autour de l'intersection Ashbury St et Haight St, à San Francisco :
URL
https://maps.googleapis.com/maps/api/place/autocomplete/json ?input=amoeba &types=establishment &location=37.76999%2C-122.44696&radius=500 &strictbounds=true &key=YOUR_API_KEY
curl
curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=amoeba&types=establishment&location=37.76999%2C-122.44696&radius=500&strictbounds=true&key=YOUR_API_KEY'Une requête d'adresses contenant "Vict" avec des résultats en français :
URL
https://maps.googleapis.com/maps/api/place/autocomplete/json ?input=Vict &types=geocode &language=fr &key=YOUR_API_KEY
curl
curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Vict&types=geocode&language=fr&key=YOUR_API_KEY'Une requête pour les villes contenant "Vict" avec des résultats en portugais brésilien :
URL
https://maps.googleapis.com/maps/api/place/autocomplete/json ?input=Vict &types=(cities) &language=pt_BR&key=YOUR_API_KEY
curl
curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Vict&types=(cities)&language=pt_BR&key=YOUR_API_KEY'Notez que vous devrez remplacer la clé API de ces exemples par votre propre clé.
Réponse Place Autocomplete (ancienne version)
Les réponses Place Autocomplete (ancienne version) sont renvoyées au format indiqué par l'option output dans le chemin d'URL de la requête. Les résultats ci-dessous sont indicatifs de ce qui peut être renvoyé pour une requête avec les paramètres suivants :
URL
https://maps.googleapis.com/maps/api/place/autocomplete/json ?input=Paris &types=geocode &key=YOUR_API_KEY
curl
curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Paris&types=geocode&key=YOUR_API_KEY'JSON
{ "predictions": [ { "description": "Paris, France", "matched_substrings": [{ "length": 5, "offset": 0 }], "place_id": "ChIJD7fiBh9u5kcRYJSMaMOCCwQ", "reference": "ChIJD7fiBh9u5kcRYJSMaMOCCwQ", "structured_formatting": { "main_text": "Paris", "main_text_matched_substrings": [{ "length": 5, "offset": 0 }], "secondary_text": "France", }, "terms": [ { "offset": 0, "value": "Paris" }, { "offset": 7, "value": "France" }, ], "types": ["locality", "political", "geocode"], }, { "description": "Paris, TX, USA", "matched_substrings": [{ "length": 5, "offset": 0 }], "place_id": "ChIJmysnFgZYSoYRSfPTL2YJuck", "reference": "ChIJmysnFgZYSoYRSfPTL2YJuck", "structured_formatting": { "main_text": "Paris", "main_text_matched_substrings": [{ "length": 5, "offset": 0 }], "secondary_text": "TX, USA", }, "terms": [ { "offset": 0, "value": "Paris" }, { "offset": 7, "value": "TX" }, { "offset": 11, "value": "USA" }, ], "types": ["locality", "political", "geocode"], }, { "description": "Paris, TN, USA", "matched_substrings": [{ "length": 5, "offset": 0 }], "place_id": "ChIJ4zHP-Sije4gRBDEsVxunOWg", "reference": "ChIJ4zHP-Sije4gRBDEsVxunOWg", "structured_formatting": { "main_text": "Paris", "main_text_matched_substrings": [{ "length": 5, "offset": 0 }], "secondary_text": "TN, USA", }, "terms": [ { "offset": 0, "value": "Paris" }, { "offset": 7, "value": "TN" }, { "offset": 11, "value": "USA" }, ], "types": ["locality", "political", "geocode"], }, { "description": "Paris, Brant, ON, Canada", "matched_substrings": [{ "length": 5, "offset": 0 }], "place_id": "ChIJsamfQbVtLIgR-X18G75Hyi0", "reference": "ChIJsamfQbVtLIgR-X18G75Hyi0", "structured_formatting": { "main_text": "Paris", "main_text_matched_substrings": [{ "length": 5, "offset": 0 }], "secondary_text": "Brant, ON, Canada", }, "terms": [ { "offset": 0, "value": "Paris" }, { "offset": 7, "value": "Brant" }, { "offset": 14, "value": "ON" }, { "offset": 18, "value": "Canada" }, ], "types": ["neighborhood", "political", "geocode"], }, { "description": "Paris, KY, USA", "matched_substrings": [{ "length": 5, "offset": 0 }], "place_id": "ChIJsU7_xMfKQ4gReI89RJn0-RQ", "reference": "ChIJsU7_xMfKQ4gReI89RJn0-RQ", "structured_formatting": { "main_text": "Paris", "main_text_matched_substrings": [{ "length": 5, "offset": 0 }], "secondary_text": "KY, USA", }, "terms": [ { "offset": 0, "value": "Paris" }, { "offset": 7, "value": "KY" }, { "offset": 11, "value": "USA" }, ], "types": ["locality", "political", "geocode"], }, ], "status": "OK", }
XML
<?xml version="1.0" encoding="UTF-8"?> <AutocompletionResponse> <status>OK</status> <prediction> <description>Paris, France</description> <type>locality</type> <type>political</type> <type>geocode</type> <reference>ChIJD7fiBh9u5kcRYJSMaMOCCwQ</reference> <term> <value>Paris</value> <offset>0</offset> </term> <term> <value>France</value> <offset>7</offset> </term> <matched_substring> <offset>0</offset> <length>5</length> </matched_substring> <place_id>ChIJD7fiBh9u5kcRYJSMaMOCCwQ</place_id> <structured_formatting> <description>Paris</description> <subdescription>France</subdescription> <description_matched_substring> <offset>0</offset> <length>5</length> </description_matched_substring> </structured_formatting> </prediction> <prediction> <description>Paris, TX, USA</description> <type>locality</type> <type>political</type> <type>geocode</type> <reference>ChIJmysnFgZYSoYRSfPTL2YJuck</reference> <term> <value>Paris</value> <offset>0</offset> </term> <term> <value>TX</value> <offset>7</offset> </term> <term> <value>USA</value> <offset>11</offset> </term> <matched_substring> <offset>0</offset> <length>5</length> </matched_substring> <place_id>ChIJmysnFgZYSoYRSfPTL2YJuck</place_id> <structured_formatting> <description>Paris</description> <subdescription>TX, USA</subdescription> <description_matched_substring> <offset>0</offset> <length>5</length> </description_matched_substring> </structured_formatting> </prediction> <prediction> <description>Paris, TN, USA</description> <type>locality</type> <type>political</type> <type>geocode</type> <reference>ChIJ4zHP-Sije4gRBDEsVxunOWg</reference> <term> <value>Paris</value> <offset>0</offset> </term> <term> <value>TN</value> <offset>7</offset> </term> <term> <value>USA</value> <offset>11</offset> </term> <matched_substring> <offset>0</offset> <length>5</length> </matched_substring> <place_id>ChIJ4zHP-Sije4gRBDEsVxunOWg</place_id> <structured_formatting> <description>Paris</description> <subdescription>TN, USA</subdescription> <description_matched_substring> <offset>0</offset> <length>5</length> </description_matched_substring> </structured_formatting> </prediction> <prediction> <description>Paris, Brant, ON, Canada</description> <type>neighborhood</type> <type>political</type> <type>geocode</type> <reference>ChIJsamfQbVtLIgR-X18G75Hyi0</reference> <term> <value>Paris</value> <offset>0</offset> </term> <term> <value>Brant</value> <offset>7</offset> </term> <term> <value>ON</value> <offset>14</offset> </term> <term> <value>Canada</value> <offset>18</offset> </term> <matched_substring> <offset>0</offset> <length>5</length> </matched_substring> <place_id>ChIJsamfQbVtLIgR-X18G75Hyi0</place_id> <structured_formatting> <description>Paris</description> <subdescription>Brant, ON, Canada</subdescription> <description_matched_substring> <offset>0</offset> <length>5</length> </description_matched_substring> </structured_formatting> </prediction> <prediction> <description>Paris, KY, USA</description> <type>locality</type> <type>political</type> <type>geocode</type> <reference>ChIJsU7_xMfKQ4gReI89RJn0-RQ</reference> <term> <value>Paris</value> <offset>0</offset> </term> <term> <value>KY</value> <offset>7</offset> </term> <term> <value>USA</value> <offset>11</offset> </term> <matched_substring> <offset>0</offset> <length>5</length> </matched_substring> <place_id>ChIJsU7_xMfKQ4gReI89RJn0-RQ</place_id> <structured_formatting> <description>Paris</description> <subdescription>KY, USA</subdescription> <description_matched_substring> <offset>0</offset> <length>5</length> </description_matched_substring> </structured_formatting> </prediction> </AutocompletionResponse>
PlacesAutocompleteResponse
| Champ | Obligatoire | Type | Description |
|---|---|---|---|
|
required | Array<PlaceAutocompletePrediction> |
Contient un tableau de prédictions. Pour en savoir plus, consultez PlaceAutocompletePrediction. |
|
required | PlacesAutocompleteStatus |
Contient l'état de la requête et éventuellement des informations de débogage qui vous aident à savoir pourquoi la requête a échoué. Pour en savoir plus, consultez PlacesAutocompleteStatus. |
|
facultatif | chaîne |
Lorsque le service renvoie un code d'état autre que |
|
facultatif | Array<string> |
Lorsque le service renvoie des informations supplémentaires sur la spécification de la requête, un champ |
Les éléments place_id sont particulièrement intéressants dans les résultats, car ils peuvent être utilisés pour demander des détails plus spécifiques sur le lieu à l'aide d'une requête distincte. Consultez Requêtes Place Details (ancienne version).
Une réponse XML se compose d'un seul élément <AutocompletionResponse> avec deux types d'éléments enfants :
- Un seul élément
<status>contient les métadonnées de la requête. Consultez la section Codes d'état ci-dessous. - Zéro ou plusieurs éléments
<prediction>, chacun contenant des informations sur un seul lieu. Pour en savoir plus sur ces résultats, consultez Résultats de Place Autocomplete (ancienne version). L'API Places renvoie jusqu'à cinq résultats.
Nous vous recommandons d'utiliser json comme indicateur de sortie préféré, sauf si votre application nécessite xml pour une raison quelconque.
Le traitement des arborescences XML nécessite une attention particulière, afin de référencer les nœuds et les éléments appropriés. Consultez Traiter du XML avec XPath pour obtenir de l'aide sur le traitement du XML.
PlacesAutocompleteStatus
Codes d'état renvoyés par le service.
OK, qui indique que la requête API a abouti ;-
ZERO_RESULTS, indiquant que la recherche a abouti, mais n'a renvoyé aucun résultat. Cela peut se produire si la recherche a reçu des limites dans un emplacement distant. -
INVALID_REQUEST, qui indique que la requête API n'a pas été rédigée correctement, généralement en raison de l'absence du paramètreinput. -
OVER_QUERY_LIMITindiquant l'un des éléments suivants :- Vous avez dépassé la limite de RPS.
- La facturation n'a pas été activée sur votre compte.
- Le crédit mensuel de 200 $ ou la limite d'utilisation que vous avez définie vous-même a été dépassé.
- Le mode de facturation fourni n'est plus valide (une carte de crédit est arrivée à expiration, par exemple).
-
REQUEST_DENIED, qui indique que votre requête a été rejetée, généralement pour l'une des raisons suivantes :- La requête ne contient pas de clé API.
- Le paramètre
keyn'est pas valide.
UNKNOWN_ERROR, qui indique une erreur inconnue.
Lorsque le service Places renvoie des résultats JSON à partir d'une recherche, il les place dans un tableau predictions. Même si le service ne renvoie aucun résultat (par exemple, si location est distant), il renvoie toujours un tableau predictions vide. Les réponses XML se composent de zéro ou plusieurs éléments <prediction>.
PlaceAutocompletePrediction
| Champ | Obligatoire | Type | Description |
|---|---|---|---|
|
required | chaîne |
Contient le nom lisible par l'humain du résultat renvoyé. Pour les résultats |
|
required | Tableau<PlaceAutocompleteMatchedSubstring> |
Liste de sous-chaînes décrivant l'emplacement du terme saisi dans le texte du résultat de la prédiction, afin que le terme puisse être mis en surbrillance s'il est choisi. Pour en savoir plus, consultez PlaceAutocompleteMatchedSubstring. |
|
required | PlaceAutocompleteStructuredFormat |
Fournit du texte préformaté qui peut être affiché dans les résultats de saisie semi-automatique. Ce contenu est destiné à être lu tel quel. N'analysez pas par programmation l'adresse formatée. Pour en savoir plus, consultez PlaceAutocompleteStructuredFormat. |
|
required | Tableau<PlaceAutocompleteTerm> |
Contient un tableau de termes identifiant chaque section de la description renvoyée (une section de la description se termine généralement par une virgule). Chaque entrée du tableau comporte un champ Pour en savoir plus, consultez PlaceAutocompleteTerm. |
|
facultatif | entier |
Distance en ligne droite en mètres depuis le point de départ. Ce champ n'est renvoyé que pour les requêtes effectuées avec un |
|
facultatif | chaîne |
Identifiant textuel qui identifie un lieu de manière unique. Pour récupérer des informations sur le lieu, transmettez cet identifiant dans le champ placeId d'une requête API Places. Pour en savoir plus sur les ID de lieu, consultez la présentation des ID de lieu. |
|
facultatif | chaîne |
Voir place_id. |
|
facultatif | Array<string> |
Contient un tableau des types qui s'appliquent à ce lieu. Par exemple, |
PlaceAutocompleteMatchedSubstring
| Champ | Obligatoire | Type | Description |
|---|---|---|---|
|
required | nombre |
Longueur de la sous-chaîne correspondante dans le texte du résultat de la prédiction. |
|
required | nombre |
Emplacement de début de la sous-chaîne correspondante dans le texte du résultat de la prédiction. |
PlaceAutocompleteStructuredFormat
| Champ | Obligatoire | Type | Description |
|---|---|---|---|
|
required | chaîne |
Contient le texte principal d'une prédiction, généralement le nom du lieu. |
|
required | Tableau<PlaceAutocompleteMatchedSubstring> |
Contient un tableau avec la valeur Pour en savoir plus, consultez PlaceAutocompleteMatchedSubstring. |
|
facultatif | chaîne |
Contient le texte secondaire d'une prédiction, généralement l'emplacement du lieu. |
|
facultatif | Tableau<PlaceAutocompleteMatchedSubstring> |
Contient un tableau avec la valeur Pour en savoir plus, consultez PlaceAutocompleteMatchedSubstring. |
PlaceAutocompleteTerm
| Champ | Obligatoire | Type | Description |
|---|---|---|---|
|
required | nombre |
Définit la position de départ de ce terme dans la description, mesurée en caractères Unicode. |
|
required | chaîne |
Texte du terme. |
Optimisation de Place Autocomplete (ancienne version)
Cette section décrit les bonnes pratiques pour vous aider à exploiter au mieux le service Place Autocomplete (ancien).
Voici quelques consignes générales :
- Le moyen le plus rapide de développer une interface utilisateur fonctionnelle consiste à utiliser le widget Place Autocomplete (ancien) de l'API Maps JavaScript, le widget Place Autocomplete (ancien) du SDK Places pour Android ou la commande d'interface utilisateur Place Autocomplete (ancienne) du SDK Places pour iOS.
- Développez dès le départ vos connaissances des champs de données Place Autocomplete (ancienne version) 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 exceptions 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 (ancienne version), utilisez des masques de champ dans les widgets Place Details (ancienne version) et Place Autocomplete (ancienne version) afin de ne renvoyer que les champs de données Place Autocomplete (ancienne version) dont vous avez besoin.
Optimisation avancée des coûts
Envisagez d'implémenter Place Autocomplete (ancienne version) de manière programmatique pour accéder au SKU : Autocomplete – Per Request et demander des résultats d'API Geocoding pour le lieu sélectionné plutôt que pour Place Details (ancienne version). 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 et de la 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 (ancienne version).
- Si les utilisateurs sélectionnent une prédiction de saisie semi-automatique toutes les quatre requêtes de prédiction Place Autocomplete (ancienne version) ou moins en moyenne, la tarification par requête peut être plus rentable que celle par session.
| Ce dont votre application a besoin | Nombre moyen de requêtes Place Autocomplete (ancienne version) avant qu'un utilisateur ne sélectionne une prédiction | Implémentation recommandée |
|---|---|---|
| Informations sur le lieu autres que l'adresse et l'emplacement, telles que le nom du lieu, l'état de l'établissement ou les horaires d'ouverture | N'importe quel nombre | Place Autocomplete basé sur des sessions (ancien) avec Place Details (ancien) |
| Uniquement l'adresse et la latitude/longitude de la prédiction sélectionnée | Quatre ou moins | Place Autocomplete (ancienne version) par requête avec l'API Geocoding |
| Uniquement l'adresse et la latitude/longitude de la prédiction sélectionnée | Plus de quatre | Place Autocomplete basé sur des sessions (ancien) pour les applications d'adresse uniquement |
L'API Geocoding peut être une option plus rentable que Place Details (ancienne version) pour votre application, en fonction de vos performances d'utilisation de Place Autocomplete (ancienne version). L'efficacité de Place Autocomplete (ancienne version) 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.
Pour trouver le nombre moyen de requêtes pour le tableau, analysez le nombre moyen de caractères saisis par un utilisateur avant qu'il sélectionne une prédiction Place Autocomplete (ancienne version) dans votre application.
Place Autocomplete basé sur des sessions (ancienne version) avec Place Details (ancienne version)
Utilisez Place Autocomplete (ancien) basé sur des sessions avec Place Details (ancien).
Étant donné que votre application nécessite Place Details (ancien), comme le nom du lieu, l'état de l'établissement ou les horaires d'ouverture, votre implémentation de Place Autocomplete (ancien) doit utiliser un jeton de session (de manière programmatique ou intégré aux widgets JavaScript, Android ou iOS) par session, ainsi que les SKU de données Places applicables, en fonction des champs de données de lieu que vous demandez.1
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 (ancienne version) et la requête Place Details (ancienne version) 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 Place Autocomplete (ancienne version) dont vous avez besoin.
Implémentation programmatique
Utilisez un jeton de session avec vos requêtes Place Autocomplete (ancienne version). Lorsque vous demandez des détails sur un lieu (ancien) concernant la prédiction sélectionnée, incluez les paramètres suivants :
- ID de lieu figurant dans la réponse Place Autocomplete (ancienne version)
- Jeton de session utilisé dans la requête Place Autocomplete (ancienne version)
- Le paramètre
fieldsspécifiant les champs de données Place Autocomplete (ancienne version) dont vous avez besoin
Place Autocomplete (ancienne version) par requête avec l'API Geocoding
Implémentez Place Autocomplete (ancien) 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.
Le coût de quatre requêtes Autocomplete – Par requête plus un appel de l'API Geocoding pour la prédiction de lieu sélectionnée est inférieur au coût par session de Place Autocomplete (ancien)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.
Place Autocomplete basé sur des sessions (ancien) pour les applications d'adresse uniquement
Utilisez Place Autocomplete (ancien) basé sur des sessions avec Place Details (ancien).
É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 (ancienne version) dépasse le coût de la tarification par session, votre implémentation de Place Autocomplete (ancienne version) doit utiliser un jeton de session pour les requêtes Place Autocomplete (ancienne version) et la requête Place Details (ancienne version) associée
par session.
1
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 (ancienne version) et la requête Place Details (ancienne version) pour la prédiction sélectionnée. Veillez à spécifier le paramètre fields pour vous assurer de ne demander que les champs dont vous avez besoin.
Implémentation programmatique
Utilisez un jeton de session avec vos requêtes Place Autocomplete (ancienne version).
Lorsque vous demandez des détails sur un lieu (ancien) concernant la prédiction sélectionnée, incluez les paramètres suivants :
- ID de lieu figurant dans la réponse Place Autocomplete (ancienne version)
- Jeton de session utilisé dans la requête Place Autocomplete (ancienne version)
- Paramètre
fieldsspécifiant les champs de données de base comme l'adresse et la géométrie
Envisagez de reporter les requêtes Place Autocomplete (ancienne version)
Vous pouvez appliquer des stratégies telles que le report d'une requête Place Autocomplete (ancienne version) 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 envoyez des requêtes Place Autocomplete (ancienne version) pour chaque caractère après que l'utilisateur a saisi le troisième caractère, et que l'utilisateur saisit sept caractères, puis sélectionne une prédiction pour laquelle vous envoyez une requête API Geocoding, le coût total correspondra à quatre requêtes Place Autocomplete (ancienne version) par requête + Geocoding1.
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 (ancienne version) à 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.
-
Pour connaître les coûts, consultez les listes de prix de 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 (ancienne version) :
- 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 (ancienne version). La préférence linguistique n'est pas obligatoire pour les widgets, car ils sélectionnent les préférences de langue dans le navigateur ou l'appareil mobile de l'utilisateur.
- Si Place Autocomplete (ancienne version) 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 Place Autocomplete (ancienne version), 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 (ancienne version). Si les résultats ne sont attendus que dans une région spécifique, utilisez la pondération géographique.
- Utilisateurs saisissant des adresses de sous-locaux, telles que 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 Place Autocomplete (ancienne version).
- 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ï.
Pondération géographique
Limitez les résultats à une zone spécifique en transmettant les paramètres location et radius. Cela indique à Place Autocomplete (ancienne version) de privilégier l'affichage des 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 includedRegionCodes pour filtrer les résultats et n'afficher que les lieux situés dans un pays spécifié.
Restriction d'emplacement
Limitez les résultats à une zone spécifiée 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 strictbounds. Cela indique à Place Autocomplete (ancienne version) de ne renvoyer que les résultats de cette région.