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

Saisie semi-automatique de requête

Le service Query Autocomplete (saisie semi-automatique de requête) permet de fournir une prédiction de requête pour les recherches géographiques textuelles en suggérant des requêtes au fur et à mesure de la saisie.

Requêtes Query Autocomplete

Le service Query Autocomplete (saisie semi-automatique de requête) 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 Query Autocomplete permet d'ajouter des prédictions de requête géographique à la volée dans votre application. Au lieu de rechercher un lieu spécifique, un utilisateur peut saisir une catégorie, telle que « pizza proche de New York » et le service répond avec une liste de requêtes suggérées correspondant à la chaîne. Le service Query Autocomplete pouvant faire la recherche sur des mots complets et partiels, les applications peuvent envoyer des requêtes lors de la frappe pour indiquer des prédictions à la volée.

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

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

output peut prendre la valeur json ou xml.

Certains paramètres sont obligatoires pour lancer une requête Query 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 Places 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 du caractère, dans le terme saisi, jusqu'auquel le service se base pour renvoyer les prédictions. Par exemple, si l'entrée est « Googl » et que le paramètre saisi a la valeur 3, le service renvoie les valeurs contenant « Goo ». Le paramètre de décalage offset doit généralement être défini sur la position du curseur. Si aucun paramètre de décalage n'est spécifié, le service se base sur le mot complet.
  • 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. Pour plus d'informations, voir Limiter les résultats à une zone géographique.
  • 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. Si le paramètre de langue n'est pas fourni, le service Places tente d'utiliser la langue native du domaine à partir duquel la requête est envoyée.

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 Places de privilégier l'affichage des résultats dans ce cercle. Les résultats en-dehors de la zone définie peuvent toutefois être affichés.

Exemples de requête Query Autocomplete

Requête« Pizza near Par » :

https://maps.googleapis.com/maps/api/place/queryautocomplete/json?key=YOUR_API_KEY&input=pizza+near%20par

Requête « Pizza near Par » avec des résultats en français :

  https://maps.googleapis.com/maps/api/place/queryautocomplete/json?key=YOUR_API_KEY&language=fr&input=pizza+near%20par

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

Réponses aux requêtes Query Autocomplete

Les réponses aux requêtes Query Autocomplete (saisie semi-automatique de requête) sont renvoyées au format défini par l'indicateur output dans le chemin de la requête URL. Les résultats ci-dessous sont renvoyés pour une requête avec les paramètres suivants :

https://maps.googleapis.com/maps/api/place/queryautocomplete/xml?&key=YOUR_API_KEY&input=pizza+near+sydne

JSON
{
   "predictions" : [
      {
         "description" : "pizza near Sydney, New South Wales, Australia",
         "matched_substrings" : [
            {
               "length" : 5,
               "offset" : 0
            },
            {
               "length" : 4,
               "offset" : 6
            },
            {
               "length" : 5,
               "offset" : 11
            }
         ],
         "terms" : [
            {
               "offset" : 0,
               "value" : "pizza"
            },
            {
               "offset" : 6,
               "value" : "near"
            },
            {
               "offset" : 11,
               "value" : "Sydney"
            },
            {
               "offset" : 19,
               "value" : "New South Wales"
            },
            {
               "offset" : 36,
               "value" : "Australia"
            }
         ]
      },
      {
         "description" : "pizza near Sydney, NS, Canada",
         "matched_substrings" : [
            {
               "length" : 5,
               "offset" : 0
            },
            {
               "length" : 4,
               "offset" : 6
            },
            {
               "length" : 5,
               "offset" : 11
            }
         ],
         "terms" : [
            {
               "offset" : 0,
               "value" : "pizza"
            },
            {
               "offset" : 6,
               "value" : "near"
            },
            {
               "offset" : 11,
               "value" : "Sydney"
            },
            {
               "offset" : 19,
               "value" : "NS"
            },
            {
               "offset" : 23,
               "value" : "Canada"
            }
         ]
      },
        ...additional results ...
      {
         "description" : "Bondi Pizza, Campbell Parade, Sydney, New South Wales, Australia",
         "id" : "c478ed4e7cb075b307fdce4ad4f6c9d15cab01d7",
         "matched_substrings" : [
            {
               "length" : 5,
               "offset" : 6
            },
            {
               "length" : 5,
               "offset" : 30
            }
         ],
         "place_id" : "ChIJv0wpwp6tEmsR0Glcf5tugrk",
         "reference" : "ClRPAAAAYozD2iM3dQvDMrvrLDIALGoHO7v6pWhxn5vIm18pOyLLqToyikFov34qJoe4NnpoaLtGIWd5LWm5hOpWU1BT-SEI2jGZ8WXuDvYiFtQtjGMSEIR4thVlMws1tnNuE3hE2k0aFCqP_yHWRNSLqaP_vQFzazO-D7Hl",
         "terms" : [
            {
               "offset" : 0,
               "value" : "Bondi Pizza"
            },
            {
               "offset" : 13,
               "value" : "Campbell Parade"
            },
            {
               "offset" : 30,
               "value" : "Sydney"
            },
            {
               "offset" : 38,
               "value" : "New South Wales"
            },
            {
               "offset" : 55,
               "value" : "Australia"
            }
         ],
         "types" : [ "establishment" ]
      }
   ],
     "status" : "OK"
  }
      

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

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

XML
<?xml version="1.0" encoding="UTF-8"?>
<AutocompletionResponse>
 <status>OK</status>
 <prediction>
  <description>pizza near Sydney, New South Wales, Australia</description>
  <term>
   <value>pizza</value>
   <offset>0</offset>
  </term>
  <term>
   <value>near</value>
   <offset>6</offset>
  </term>
  <term>
   <value>Sydney</value>
   <offset>11</offset>
  </term>
  <term>
   <value>New South Wales</value>
   <offset>19</offset>
  </term>
  <term>
   <value>Australia</value>
   <offset>36</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <matched_substring>
   <offset>6</offset>
   <length>4</length>
  </matched_substring>
  <matched_substring>
   <offset>11</offset>
   <length>5</length>
  </matched_substring>
 </prediction>
 <prediction>
  <description>pizza near Sydney, NS, Canada</description>
  <term>
   <value>pizza</value>
   <offset>0</offset>
  </term>
  <term>
   <value>near</value>
   <offset>6</offset>
  </term>
  <term>
   <value>Sydney</value>
   <offset>11</offset>
  </term>
  <term>
   <value>NS</value>
   <offset>19</offset>
  </term>
  <term>
   <value>Canada</value>
   <offset>23</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <matched_substring>
   <offset>6</offset>
   <length>4</length>
  </matched_substring>
  <matched_substring>
   <offset>11</offset>
   <length>5</length>
  </matched_substring>
 </prediction>
...additional results ...
 <prediction>
  <description>Bondi Pizza, Campbell Parade, Sydney, New South Wales, Australia</description>
  <type>establishment</type>
  <place_id>ChIJv0wpwp6tEmsR0Glcf5tugrk</place_id>
  <reference>ClRPAAAADqzkHp7ZNKcaFxP-foYYI5dix_sSaqfkUgxEYaJrB0ntyg704tMG8sEJjebhIVLW4viCsKtnlxiBrrFk9fxq0ruf4oUdQDfv7zwmS4P68KQSEPKUkFNTgit63QOGRYeElv4aFJnD0wN2thFO6XFRq2JsHzQEirvC</reference>
  <id>c478ed4e7cb075b307fdce4ad4f6c9d15cab01d7</id>
  <term>
   <value>Bondi Pizza</value>
   <offset>0</offset>
  </term>
  <term>
   <value>Campbell Parade</value>
   <offset>13</offset>
  </term>
  <term>
   <value>Sydney</value>
   <offset>30</offset>
  </term>
  <term>
   <value>New South Wales</value>
   <offset>38</offset>
  </term>
  <term>
   <value>Australia</value>
   <offset>55</offset>
  </term>
  <matched_substring>
   <offset>6</offset>
   <length>5</length>
  </matched_substring>
  <matched_substring>
   <offset>30</offset>
   <length>5</length>
  </matched_substring>
 </prediction>
</AutocompletionResponse>

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 une prédiction de requête unique. Pour plus d'informations sur ces résultats, voir Résultats de Query Autocomplete.

Nous recommandons d'utiliser json comme indicateur de sortie privilégié, sauf si l'application requiert xml. 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 à Query Autocomplete contient le statut de la requête et peut contenir des informations de débogage qui vous aident à savoir pourquoi la requête 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 Query 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.
  • 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.
  • matched_substring contient une valeur offset et un paramètre 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.

Notez que certaines prédictions peuvent correspondre à des lieux et que les champs place_id, reference et type sont inclus dans ces prédictions. Pour plus d'informations sur ces résultats, voir Résultats de Place Autocomplete.

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