Vous êtes prêt !

Pour passer à l'étape de développement, accédez à notre documentation pour les développeurs.

Activer Google Places API Web Service

Pour commencer, nous allons vous guider à travers la console Google Developers et effectuer deux ou trois petites choses :

  1. Créer ou choisir un projet
  2. Activer Google Places API Web Service
  3. Créer les clés appropriées
Continuer

Place Autocomplete

Le service Place Autocomplete (saisie-semi-automatique de lieu) est un service Web qui renvoie des prédictions de lieu 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 permet de fournir la fonctionnalité de saisie semi-automatique pour les recherches géographiques textuelles et renvoie des lieux tels que des entreprises, des adresses et des points d'intérêt au fur et à mesure de la saisie par l'utilisateur.

Requêtes Place Autocomplete

Le service Place Autocomplete (saisie semi-automatique de lieu) fait partie de Google Places API Web Service et partage une clé d'API et des quotas avec Google Places API Web Service.

Le service Place Autocomplete peut renvoyer aussi bien des mots complets que des chaînes partielles. Ainsi, les applications peuvent envoyer des requêtes lors de la frappe pour indiquer les lieux possibles à la volée.

Les prédictions renvoyées sont conçues pour être présentées à l'utilisateur afin de l'aider à sélectionner le lieu souhaité. Vous pouvez ajouter une requête de détails sur le lieu pour plus d'informations sur les lieux renvoyés.

Une requête Place Autocomplete est une URL HTTP utilisant le format suivant :

https://maps.googleapis.com/maps/api/place/autocomplete/output?parameters

output peut prendre l'une des valeurs suivantes :

  • json (recommandé) indique que la réponse doit être au format JSON (JavaScript Object Notation).
  • xml indique que la réponse doit être au format XML.

Certains paramètres sont obligatoires pour lancer une requête Place Autocomplete. Comme pour toutes les URL, les différents paramètres sont séparés par une esperluette (&). Vous trouverez ci-dessous la liste des paramètres et leurs différentes valeurs possibles.

Paramètres obligatoires

  • input - Chaîne de texte sur laquelle porte la recherche. Le service Place Autocomplete renvoie les résultats correspondant à cette chaîne et les classe en fonction de leur pertinence.
  • keyClé d'API de votre application. Cette clé identifie votre application à des fins de gestion des quotas. Pour plus d'informations, voir Obtenir une clé. Les clients Google Maps APIs Premium Plan doivent utiliser le projet d'API créé pour eux au moment de l'achat de Premium Plan.

Paramètres facultatifs

  • offset - Position, dans le terme saisi, du dernier caractère utilisé par le service pour renvoyer les prédictions. Par exemple, si l'entrée est « Google » et que le paramètre offset a la valeur 3, le service renvoie les valeurs contenant « Goo ». La chaîne concernée par le paramètre offset est comparée au premier mot du texte saisi uniquement. Par exemple, si le texte saisi est « Google abc » et que le paramètre offset a la valeur 3, le service renvoie les résultats correspondant à « Goo abc ». Si aucun paramètre offset n'est spécifié, le service se base sur le mot complet. Le paramètre offset doit généralement être défini sur la position du curseur.
  • location - Point autour duquel vous souhaitez extraire les informations de lieu. Doit être défini par latitude,longitude.
  • radius - Distance (en mètres) jusqu'à laquelle renvoyer les résultats de lieu. Notez que définir un paramètre radius affine les résultats à la zone indiquée, mais peut ne pas limiter entièrement les résultats à cette zone. Voir Limiter les résultats à une zone géographique et Restreindre les résultats à une zone géographique ci-dessous.
  • language - Code langue qui indique la langue dans laquelle les résultats doivent être renvoyés, si possible. Les recherches sont également affinées par rapport à la langue sélectionnée ; les résultats dans la langue sélectionnée peuvent obtenir un meilleur classement. Voir la liste des langues prises en charge et leurs codes. Notez que cette liste peut ne pas être exhaustive, car nous mettons régulièrement à jour les langues prises en charge. Si le paramètre language n'est pas fourni, le service Place Autocomplete tente d'utiliser la langue native du domaine à partir duquel la requête est envoyée.
  • types - Types des résultats de lieu à renvoyer. Voir Types de lieu ci-dessous. Si aucun type n'est spécifié, tous les types sont renvoyés.
  • components - Groupe de lieux auquel vous souhaitez limiter les résultats. Actuellement, vous pouvez utiliser le paramètre components pour appliquer un filtre par pays. Le pays doit être spécifié 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.
  • strictbounds - Renvoie uniquement les lieux qui se trouvent strictement dans la région définie par les paramètres location et radius. Il s'agit d'une restriction, plutôt que d'une préférence, ce que signifie que les résultats en dehors de cette région ne seront pas renvoyés, même s'ils correspondent à la saisie de l'utilisateur.

Limiter les résultats à une zone géographique

Vous pouvez affiner les résultats à un cercle donné en spécifiant les paramètres location et radius. Vous indiquez ainsi au service Place Autocomplete de privilégier les résultats situés à l'intérieur de ce cercle. Les résultats en-dehors de la zone définie peuvent toutefois être affichés. Vous pouvez utiliser le paramètre components pour filtrer les résultats afin de n'afficher que les lieux situés dans un pays donné.

Astuce : Les établissements n'ont pas une priorité assez élevée pour apparaître dans les résultats lorsque la zone de recherche est large. Pour afficher les établissements dans des résultats combinés établissement/géocode, vous pouvez réduire le rayon. Vous pouvez également utiliser le paramètre types=establishment pour limiter les résultats aux seuls établissements.

Restreindre les résultats à une zone géographique

Vous pouvez également restreindre les résultats à la région définie par les paramètres location et radius, en ajoutant le paramètre strictbounds. Cette configuration indique au service Place Autocomplete qu'il doit renvoyer uniquement les résultats au sein de cette région.

Types de lieu

Vous pouvez limiter les résultats d'une requête Place Autocomplete à un type donné en indiquant un paramètre types. Ce paramètre indique un type ou un groupe de types pris en charge, tels que ceux répertoriés ci-dessous. Si aucun paramètre n'est spécifié, tous les types sont renvoyés. En règle générale, un seul type est autorisé. Vous pouvez toutefois combiner les types geocode et establishment, mais notez que les résultats sont identiques à ceux renvoyés lorsque vous ne spécifiez aucun type. Les types pris en charge sont les suivants :

  • geocode indique au service Place Autocomplete de renvoyer uniquement les résultats de géocodage plutôt que des professionnels. Généralement, cette requête est utilisée pour affiner les résultats lorsque le point géographique spécifié est indéterminé.
  • address indique au service Place Autocomplete de renvoyer uniquement les résultats de géocodage ayant une adresse précise. En général, cette requête est utilisée lorsque l'on sait que l'utilisateur recherche une adresse spécifiée complète.
  • establishment indique au service Place Autocomplete de renvoyer uniquement les professionnels.
  • Le groupe de types (regions) indique au service Places de renvoyer tous les résultats correspondant aux types suivants :
    • locality
    • sublocality
    • postal_code
    • country
    • administrative_area_level_1
    • administrative_area_level_2
  • Le groupe de types (cities) indique au service Places de renvoyer les résultats correspondant au type locality ou administrative_area_level_3.

Exemples de requête Autocomplete

Requête d'établissements contenant la chaîne « Amoeba » dans une zone centrée à San Francisco, Californie :

https://maps.googleapis.com/maps/api/place/autocomplete/xml?input=Amoeba&types=establishment&location=37.76999,-122.44696&radius=500&key=YOUR_API_KEY

La même requête, limitée à des résultats dans un rayon de 500 mètres autour de Ashbury St & Haight St, San Francisco :

https://maps.googleapis.com/maps/api/place/autocomplete/xml?input=Amoeba&types=establishment&location=37.76999,-122.44696&radius=500&strictbounds&key=YOUR_API_KEY

Requête d'adresses contenant « Vict » dans les résultats en français :

https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Vict&types=geocode&language=fr&key=YOUR_API_KEY

Requête de villes contenant « Vict » dans les résultats en portugais brésilien :

https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Vict&types=(cities)&language=pt_BR&key=YOUR_API_KEY

Notez que vous devez remplacer la clé d'API dans ces exemples par votre propre clé.

Réponses de Place Autocomplete

Les réponses aux requêtes de saisie semi-automatique de lieu sont renvoyées au format défini par l'indicateur output dans le chemin URL de la requête. Les résultats ci-dessous indiquent la réponse à une requête contenant les paramètres suivants :

input=Paris&types=geocode

JSON
{
  "status": "OK",
  "predictions" : [
      {
         "description" : "Paris, France",
         "id" : "691b237b0322f28988f3ce03e321ff72a12167fd",
         "matched_substrings" : [
            {
               "length" : 5,
               "offset" : 0
            }
         ],
         "place_id" : "ChIJD7fiBh9u5kcRYJSMaMOCCwQ",
         "reference" : "CjQlAAAA_KB6EEceSTfkteSSF6U0pvumHCoLUboRcDlAH05N1pZJLmOQbYmboEi0SwXBSoI2EhAhj249tFDCVh4R-PXZkPK8GhTBmp_6_lWljaf1joVs1SH2ttB_tw",
         "terms" : [
            {
               "offset" : 0,
               "value" : "Paris"
            },
            {
               "offset" : 7,
               "value" : "France"
            }
         ],
         "types" : [ "locality", "political", "geocode" ]
      },
      {
         "description" : "Paris Avenue, Earlwood, New South Wales, Australia",
         "id" : "359a75f8beff14b1c94f3d42c2aabfac2afbabad",
         "matched_substrings" : [
            {
               "length" : 5,
               "offset" : 0
            }
         ],
         "place_id" : "ChIJrU3KAHG6EmsR5Uwfrk7azrI",
         "reference" : "CkQ2AAAARbzLE-tsSQPgwv8JKBaVtbjY48kInQo9tny0k07FOYb3Z_z_yDTFhQB_Ehpu-IKhvj8Msdb1rJlX7xMr9kfOVRIQVuL4tOtx9L7U8pC0Zx5bLBoUTFbw9R2lTn_EuBayhDvugt8T0Oo",
         "terms" : [
            {
               "offset" : 0,
               "value" : "Paris Avenue"
            },
            {
               "offset" : 14,
               "value" : "Earlwood"
            },
            {
               "offset" : 24,
               "value" : "New South Wales"
            },
            {
               "offset" : 41,
               "value" : "Australia"
            }
         ],
         "types" : [ "route", "geocode" ]
      },
      {
         "description" : "Paris Street, Carlton, New South Wales, Australia",
         "id" : "bee539812eeda477dad282bcc8310758fb31d64d",
         "matched_substrings" : [
            {
               "length" : 5,
               "offset" : 0
            }
         ],
         "place_id" : "ChIJCfeffMi5EmsRp7ykjcnb3VY",
         "reference" : "CkQ1AAAAAERlxMXkaNPLDxUJFLm4xkzX_h8I49HvGPvmtZjlYSVWp9yUhQSwfsdveHV0yhzYki3nguTBTVX2NzmJDukq9RIQNcoFTuz642b4LIzmLgcr5RoUrZhuNqnFHegHsAjtoUUjmhy4_rA",
         "terms" : [
            {
               "offset" : 0,
               "value" : "Paris Street"
            },
            {
               "offset" : 14,
               "value" : "Carlton"
            },
            {
               "offset" : 23,
               "value" : "New South Wales"
            },
            {
               "offset" : 40,
               "value" : "Australia"
            }
         ],
         "types" : [ "route", "geocode" ]
      },
  ...additional results ...
      
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>
  <place_id>ChIJD7fiBh9u5kcRYJSMaMOCCwQ</place_id>
  <reference>CiQRAAAAJm0CiCHIC8C4GOjREdm3QtHYhMyFaUXKWAbGSaZImQ8SECnHAhpcuZaoSr0_TKfeHvwaFHMIq_BmUccTC4mt6EWVNMa67Xuq</reference>
  <id>691b237b0322f28988f3ce03e321ff72a12167fd</id>
  <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>
 </prediction>
 <prediction>
  <description>Paris, TX, United States</description>
  <type>colloquial_area</type>
  <type>political</type>
  <type>geocode</type>
  <place_id>ChIJrU3KAHG6EmsR5Uwfrk7azrI</place_id>
  <reference>CiQcAAAArNRoGmiHh0PNVH5LSnJEbT5L7DfUE-APvTfYac9Ta5USEIfAOzXTkqTpioZX9qeevY8aFPgN_H6qcRnGLqPUq4zkOE-_g-ul</reference>
  <id>029556239a911839382f42ec36c5ce2b85be9be3</id>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>TX</value>
   <offset>7</offset>
  </term>
  <term>
   <value>United States</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
 </prediction>
 <prediction>
  <description>Paris, Ontario, Canada</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <place_id>ChIJCfeffMi5EmsRp7ykjcnb3VY</place_id>
  <reference>CiQaAAAApuD3Th6N5_EcJjKw0umu_IonagFPBo9idTf7WB8-cw8SEGS5wSvHzhuUvCqPH-uM5B8aFIedLGNSuh5M5eqWdBJCtc0Ibvd0</reference>
  <id>e7ac9c89d4a590305242b0cb5bf43064027223c9</id>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>Ontario</value>
   <offset>7</offset>
  </term>
  <term>
   <value>Canada</value>
   <offset>16</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
 </prediction>
</AutocompletionResponse>

Une réponse JSON contient deux éléments racine :

  • status contient des métadonnées sur la requête. Voir Codes de statut ci-dessous.
  • predictions contient un ensemble de lieux avec des informations sur les lieux. Pour plus d'informations sur ces résultats, voir Résultats de Place Autocomplete. Google Places API Web Service renvoie jusqu'à 5 résultats.

Particulièrement intéressant dans les résultats, les éléments place_id peuvent être utilisés pour demander des détails plus spécifiques sur le lieu dans une requête séparée. Voir Requêtes de détails de lieu.

Voir Traitement JSON avec Javascript pour obtenir de l'aide sur l'analyse des réponses JSON.

Une réponse XML se compose d'un élément unique <AutocompletionResponse> avec deux types d'éléments enfant :

  • Un élément unique <status> contient des métadonnées sur la requête. Voir Codes de statut ci-dessous.
  • Zéro, un ou plusieurs éléments <prediction> contenant chacun des informations sur un seul lieu. Pour plus d'informations sur ces résultats, voir Résultats de la saisie semi-automatique de lieu. Google Places API Web Service renvoie jusqu'à 5 résultats.

Nous recommandons d'utiliser json comme indicateur de sortie privilégié, sauf si l'application requiert xml pour une raison spécifique. Il peut s'avérer délicat de traiter les arborescences XML de manière à faire référence aux nœuds et aux éléments adéquats. Voir Analyse XML avec XPath pour obtenir de l'aide sur le traitement XML.

Codes de statut

Le champ status de l'objet de la réponse à Place Autocomplete contient le statut de la requête et peut contenir des informations de débogage qui vous aident à savoir pourquoi cette requête de saisie semi-automatique a échoué. Le champ status peut contenir les valeurs suivantes :

  • OK indique qu'aucune erreur n'est survenue et qu'au moins un résultat a été trouvé.
  • ZERO_RESULTS indique que la recherche a réussi mais n'a renvoyé aucun résultat. Cela peut se produire si la recherche a reçu un paramètre bounds dans un lieu distant.
  • OVER_QUERY_LIMIT indique que vous avez dépassé votre quota.
  • REQUEST_DENIED indique que votre requête a été rejetée, généralement du fait de l'absence d'un paramètre key valide.
  • INVALID_REQUEST indique généralement que le paramètre input est manquant.

Messages d'erreur

Lorsque le service Places renvoie un code de statut autre que OK, l'objet de la réponse peut comporter un champ supplémentaire error_message. Ce champ contient des informations plus détaillées sur le motif de ce code de statut.

Résultats de Place Autocomplete

Le service Places renvoie les résultats JSON sous forme de tableau d'éléments predictions. Même si le service ne renvoie aucun résultat (par exemple, si le paramètre location est un lieu distant), il renvoie malgré tout un tableau predictions vide. Les réponses XML sont composées de zéro, un ou plusieurs éléments <prediction>.

Chaque résultat proposé contient les champs suivants :

  • description contient le nom lisible du résultat renvoyé. Pour les résultats establishment, il s'agit généralement du nom du professionnel.
  • place_id est un identifiant texte qui identifie un lieu de façon unique. Pour extraire des informations sur le lieu, indiquez cet identifiant dans le champ placeId d'une requête Google Places API Web Service. Pour plus d'informations sur les identifiants de lieu, voir la présentation des identifiants de lieu.
  • reference contient un jeton unique que vous pouvez utiliser pour extraire des informations supplémentaires sur ce lieu dans une requête Place Details. Même si ce jeton identifie le lieu de manière unique, l'inverse n'est pas vrai. Un lieu peut être associé à plusieurs jetons de référence valides. Plusieurs recherches peuvent renvoyer plusieurs jetons différents pour un lieu donné. Remarque : La propriété reference est progressivement abandonnée au profit de place_id. Voir l'avis lié à l'abandon sur cette page.
  • id contient un identifiant fixe unique correspondant à ce lieu. Cet identifiant peut ne pas être utilisé pour extraire des informations sur ce lieu, mais pour regrouper des données qui lui sont associées et en vérifier l'identité dans plusieurs recherches séparées. Remarque : La propriété id est progressivement abandonnée au profit de place_id. Voir l'avis lié à l'abandon sur cette page.
  • terms contient un ensemble de termes qui identifient 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 est associée à un champ value, contenant le texte du terme, et un champ offset qui définit la position de départ de ce terme dans la description, exprimée en caractères Unicode.
  • types contient un ensemble de types qui s'appliquent à ce lieu. Par exemple : [ "political", "locality" ] ou [ "establishment", "geocode" ].
  • matched_substrings contient un tableau avec la valeur offset et length. Ces éléments décrivent l'emplacement du terme saisi dans les résultats proposés, pour pouvoir mettre ce terme en valeur, le cas échéant.

Paramètre sensor

Google Places API Web Service exigeait auparavant l'insertion du paramètre sensor pour savoir si votre application utilisait un capteur afin de déterminer la position géographique de l'utilisateur. Désormais, ce paramètre n'est plus obligatoire.

Envoyer des commentaires concernant…

location_on
Google Places API Web Service