Saisie semi-automatique (nouveau)

Sélectionnez une plate-forme : Android iOS JavaScript Services Web
Développeurs de l'Espace économique européen (EEE)

Introduction

Autocomplete (New) est un service Web qui renvoie des prédictions de lieux et de requêtes en réponse à une requête HTTP. Dans la requête, spécifiez une chaîne de recherche textuelle et des limites géographiques qui contrôlent la zone de recherche.

Autocomplete (New) peut établir une correspondance avec des mots complets et des sous-chaînes de l'entrée 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 et les requêtes possibles à la volée.

La réponse de la saisie semi-automatique (New) peut contenir deux types de prédictions :

  • Prédictions de lieux : lieux, tels que des établissements, des adresses et des points d'intérêt, en fonction de la chaîne de texte d'entrée et de la zone de recherche spécifiées. Les prédictions de lieux sont renvoyées par défaut.
  • Prédictions de requêtes : chaînes de requête correspondant à la chaîne de texte d'entrée et à la zone de recherche. Les prédictions de requêtes ne sont pas renvoyées par défaut. Utilisez le paramètre de requête includeQueryPredictions pour ajouter des prédictions de requête à la réponse.

Par exemple, vous appelez Autocomplete (New) en utilisant comme entrée une chaîne contenant une saisie utilisateur partielle, "Sicilian piz", avec la zone de recherche limitée à San Francisco, CA. La réponse contient ensuite une liste de prédictions de lieux correspondant à la chaîne et à la zone de recherche, comme le restaurant "Sicilian Pizza Kitchen", ainsi que des détails sur le lieu.

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

La réponse peut également contenir une liste de prédictions de requêtes correspondant à la chaîne de recherche et à la zone de recherche, par exemple "Sicilian Pizza & Pasta". Chaque prédiction de requête dans la réponse inclut le champ text contenant une chaîne de recherche textuelle recommandée. Utilisez cette chaîne comme entrée pour Text Search (New) afin d'effectuer une recherche plus détaillée.

APIs Explorer vous permet d'effectuer des requêtes en direct afin de vous familiariser avec l'API et ses options :

Requêtes Autocomplete (New)

Une requête Autocomplete (New) est une requête POST HTTP envoyée à une URL au format suivant :

https://places.googleapis.com/v1/places:autocomplete

Transmettez tous les paramètres dans le corps de la requête JSON ou dans les en-têtes de la requête POST. Exemple :

curl -X POST -d '{
  "input": "pizza",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Paramètres possibles

Paramètre

Description

input*

Chaîne de texte à rechercher (mots complets, sous-chaînes, noms de lieux, adresses, Plus Codes).

FieldMask (en-tête HTTP)

Liste d'éléments séparés par une virgule spécifiant les champs à renvoyer dans la réponse.

includedPrimaryTypes

Limite les résultats aux lieux correspondant à l'un des types principaux spécifiés (cinq au maximum).

includePureServiceAreaBusinesses

Si la valeur est "true", inclut les établissements sans emplacement physique (établissements de services de proximité). Valeur par défaut : "false".

includeQueryPredictions

Si la valeur est "true", inclut les prédictions de lieu et de requête dans la réponse. Valeur par défaut : "false".

includedRegionCodes

Tableau de 15 codes pays à deux caractères maximum auxquels limiter les résultats.

inputOffset

Décalage de caractères Unicode basé sur zéro de la position du curseur dans la chaîne d'entrée, influençant les prédictions. La valeur par défaut est la longueur de l'entrée.

languageCode

Langue préférée (code IETF BCP-47) pour les résultats. La valeur par défaut est l'en-tête Accept-Language ou "en".

locationBias

Spécifie une zone (cercle ou rectangle) pour pondérer les résultats de recherche, tout en autorisant les résultats en dehors de la zone. Ne peut pas être utilisé avec locationRestriction.

locationRestriction

Spécifie une zone (cercle ou rectangle) dans laquelle limiter les résultats de recherche. Les résultats en dehors de cette zone sont exclus. Ne peut pas être utilisé avec locationBias.

origin

Point de départ (latitude, longitude) utilisé pour calculer la distance en ligne droite (distanceMeters) jusqu'aux destinations prévues.

regionCode

Code de région utilisé pour mettre en forme la réponse et orienter les suggestions (par exemple, "uk", "fr").

sessionToken

Chaîne générée par l'utilisateur pour regrouper les appels Autocomplete dans une session à des fins de facturation.

* Indique un champ obligatoire.

À propos de la réponse

Autocomplete (New) renvoie un objet JSON en réponse. Dans la réponse :

  • Le tableau suggestions contient tous les lieux et requêtes prédits, classés par ordre de pertinence perçue. Chaque lieu est représenté par un champ placePrediction et chaque requête par un champ queryPrediction.
  • Un champ placePrediction contient des informations détaillées sur une seule prédiction de lieu, y compris l'ID de lieu et la description textuelle.
    • Pour correspondre plus précisément à la saisie de l'utilisateur fournie dans le paramètre input, la description textuelle d'une prédiction de lieu peut inclure d'autres noms pour les lieux, les rues et d'autres composants d'adresse. Ces noms alternatifs peuvent différer des noms renvoyés dans les champs displayName et d'adresse des résultats Place Details pour le même ID de lieu.
    • Dans ce contexte, les noms alternatifs de certains lieux peuvent être dans une langue différente de celle attendue en fonction du paramètre languageCode, selon les noms qui correspondent le mieux à la saisie de l'utilisateur.
  • Un champ queryPrediction contient des informations détaillées sur une seule prédiction de requête.

L'objet JSON complet est au format suivant :

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }]
        },
      ...
    },
    {
      "queryPrediction": {
        "text": {
          "text": "Amoeba Music",
          "matches": [
            {
              "endOffset": 6
            }]
        },
        ...
    }
  ...]
}

Paramètres obligatoires

entrée

Chaîne de texte sur laquelle effectuer la recherche. Spécifiez des mots complets et des sous-chaînes, des noms de lieux, des adresses et des Plus Codes. Le service Autocomplete (New) renvoie les résultats correspondant à cette chaîne et les classe en fonction de leur pertinence estimée.

Paramètres facultatifs

FieldMask

Spécifiez la liste des champs à renvoyer dans la réponse en créant un masque de champ de réponse. Transmettez le masque de champ de réponse à la méthode à l'aide de l'en-tête HTTP X-Goog-FieldMask.

Spécifiez une liste de champs de suggestion à renvoyer, séparés par une virgule. Par exemple, pour récupérer les éléments suggestions.placePrediction.text.text et suggestions.queryPrediction.text.text de la suggestion.

  X-Goog-FieldMask: suggestions.placePrediction.text.text,suggestions.queryPrediction.text.text

Utilisez * pour récupérer tous les champs.

  X-Goog-FieldMask: *

includeFutureOpeningBusinesses

Si la valeur est true, renvoie les établissements dont l'ouverture est prévue à l'avenir. La valeur par défaut est false.

includedPrimaryTypes

Un lieu ne peut avoir qu'un seul type principal parmi les types listés dans le tableau A ou le tableau B. Par exemple, le type principal peut être "mexican_restaurant" ou "steak_house".

Par défaut, l'API renvoie tous les lieux en fonction du paramètre input, quelle que soit la valeur du type principal associée au lieu. Limitez les résultats à un ou plusieurs types principaux spécifiques en transmettant le paramètre includedPrimaryTypes.

Utilisez ce paramètre pour spécifier jusqu'à cinq valeurs de type du tableau A ou du tableau B. Un lieu doit correspondre à l'une des valeurs de type principal spécifiées pour être inclus dans la réponse.

Ce paramètre peut également inclure, à la place, l'un des éléments (regions) ou (cities). Le type (regions) filtre les collections pour les zones ou les divisions, telles que les quartiers et les codes postaux. La collection de types (cities) filtre les lieux que Google identifie comme une ville.

La requête est rejetée avec une erreur INVALID_REQUEST si :

  • Plus de cinq types sont spécifiés.
  • Un type est spécifié en plus de (cities) ou (regions).
  • Des types non reconnus sont spécifiés.

includePureServiceAreaBusinesses

Si la valeur est définie sur true, la réponse inclut les établissements qui se rendent directement chez les clients ou qui proposent un service de livraison, mais qui ne disposent pas d'un établissement physique. Si la valeur est définie sur false, l'API ne renvoie que les établissements disposant d'une adresse physique.

includeQueryPredictions

Si la valeur est true, la réponse inclut à la fois des prédictions de lieux et de requêtes. La valeur par défaut est false, ce qui signifie que la réponse n'inclut que les prédictions de lieux.

includedRegionCodes

Incluez uniquement les résultats de la liste des régions spécifiées, sous la forme d'un tableau de 15 valeurs ccTLD (domaine de premier niveau) à deux caractères maximum. Si elle est omise, aucune restriction n'est appliquée à la réponse. Par exemple, pour limiter les régions à l'Allemagne et à la France :

    "includedRegionCodes": ["de", "fr"]

Si vous spécifiez à la fois locationRestriction et includedRegionCodes, les résultats se trouvent dans la zone d'intersection des deux paramètres.

inputOffset

Décalage de caractères Unicode basé sur zéro indiquant la position du curseur dans input. La position du curseur peut influencer les prédictions renvoyées. Si ce champ est vide, la valeur par défaut est la longueur de input.

languageCode

Langue préférée dans laquelle renvoyer les résultats. Les résultats peuvent être dans plusieurs langues si la langue utilisée dans input est différente de la valeur spécifiée par languageCode, ou si le lieu renvoyé n'a pas de traduction de la langue locale vers languageCode.

  • Vous devez utiliser les codes de langue IETF BCP-47 pour spécifier la langue préférée.
  • Si languageCode n'est pas fourni, l'API utilise la valeur spécifiée dans l'en-tête Accept-Language. Si aucune valeur n'est spécifiée, la valeur par défaut est en. Si vous spécifiez un code de langue non valide, l'API renvoie une erreur INVALID_ARGUMENT.
  • 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. Cela affecte également la capacité de l'API à corriger les fautes d'orthographe.
  • Les prédictions de lieux sont formatées différemment selon l'entrée utilisateur dans chaque requête.
    • Les termes correspondants dans le paramètre input sont choisis en premier, en utilisant des noms alignés sur la préférence de langue indiquée par le paramètre languageCode lorsqu'il est disponible, ou en utilisant les noms qui correspondent le mieux à la saisie de l'utilisateur.
    • Les noms de lieux peuvent être formatés à l'aide d'autres noms pour correspondre aux termes du paramètre input, y compris les noms dans des langues autres que celle indiquée par le paramètre languageCode.
    • Les adresses postales sont formatées dans la langue locale, dans un script lisible par l'utilisateur lorsque cela est possible, uniquement après que les termes correspondants ont été sélectionnés pour correspondre aux termes du paramètre input.
    • Toutes les autres adresses sont renvoyées dans la langue préférée, après que les termes correspondants ont été choisis pour correspondre aux termes du paramètre input. Si aucun nom n'est disponible dans la langue préférée, l'API utilise la correspondance la plus proche.

locationBias ou locationRestriction

Vous pouvez spécifier locationBias ou locationRestriction, mais pas les deux, pour définir la zone de recherche. Considérez que locationRestriction spécifie la région dans laquelle les résultats doivent se trouver, et que locationBias spécifie la région dont les résultats doivent être proches, mais qui peuvent se trouver en dehors de la zone.

  • locationBias

    Spécifie une zone de recherche. Cet emplacement sert de pondération, ce qui signifie que des résultats autour de l'emplacement spécifié peuvent être renvoyés, y compris des résultats en dehors de la zone spécifiée.

  • locationRestriction

    Spécifie une zone de recherche. Les résultats en dehors de la zone spécifiée ne sont pas renvoyés.

Spécifiez la région locationBias ou locationRestriction sous la forme d'une fenêtre d'affichage rectangulaire ou d'un cercle.

  • Un cercle est défini par un point central et un rayon en mètres. Le rayon doit être compris entre 0,0 et 50 000,0 inclus. La valeur par défaut est 0.0. Pour locationRestriction, vous devez définir le rayon sur une valeur supérieure à 0,0. Sinon, la requête ne renvoie aucun résultat.

    Exemple :

    "locationBias": {
      "circle": {
        "center": {
          "latitude": 37.7937,
          "longitude": -122.3965
        },
        "radius": 500.0
      }
    }
  • Un rectangle est une fenêtre d'affichage de latitude/longitude, représentée par deux points low et élevés diagonalement opposés. Un viewport est considéré comme une région fermée, ce qui signifie qu'il inclut sa limite. Les limites de latitude doivent être comprises entre -90 et 90 degrés inclus, et les limites de longitude doivent être comprises entre -180 et 180 degrés inclus :

    • Si low = high, la fenêtre d'affichage se compose de ce point unique.
    • Si low.longitude > high.longitude, la plage de longitude est inversée (la fenêtre d'affichage traverse la ligne de longitude de 180 degrés).
    • Si low.longitude = -180 degrés et high.longitude = 180 degrés, la fenêtre d'affichage inclut toutes les longitudes.
    • Si low.longitude = 180 degrés et high.longitude = -180 degrés, la plage de longitude est vide.

    low et high doivent être renseignés, et la zone représentée ne peut pas être vide. Un viewport vide génère une erreur.

    Par exemple, cette fenêtre d'affichage englobe entièrement la ville de New York :

    "locationBias": {
      "rectangle": {
        "low": {
          "latitude": 40.477398,
          "longitude": -74.259087
        },
        "high": {
          "latitude": 40.91618,
          "longitude": -73.70018
        }
      }
    }

origin

Point d'origine à partir duquel calculer la distance en ligne droite jusqu'à la destination (renvoyée sous la forme distanceMeters). Si cette valeur est omise, la distance en ligne droite n'est pas renvoyée. Doit être spécifié sous forme de coordonnées de latitude et de longitude :

"origin": {
    "latitude": 40.477398,
    "longitude": -74.259087
}

regionCode

Code régional utilisé pour mettre en forme la réponse, 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").

Les suggestions sont également biaisées en fonction des codes régionaux. Google recommande de définir regionCode en fonction des préférences régionales de l'utilisateur.

Si vous spécifiez un code de région non valide, l'API renvoie une erreur INVALID_ARGUMENT. Le paramètre peut affecter les résultats en fonction de la législation applicable.

Lorsque vous définissez regionCode, les prédictions dans cette région peuvent omettre le nom du pays dans le texte de suggestion, ce qui signifie que structuredFormat.secondaryText peut ne pas être présent. Par conséquent, assurez-vous que votre application gère les cas où secondaryText n'est pas défini ou est manquant.

sessionToken

Les jetons de session sont des chaînes générées par l'utilisateur qui suivent les appels Autocomplete (New) en tant que "sessions". Autocomplete (New) utilise des jetons de session pour regrouper les phases de requête et de sélection d'une recherche de saisie semi-automatique d'un utilisateur dans une session distincte à des fins de facturation. Pour en savoir plus, consultez Jetons de session.

Choisir des paramètres pour biaiser les résultats

Les paramètres Autocomplete (New) peuvent influencer les résultats de recherche de différentes manières. Le tableau suivant fournit des recommandations d'utilisation des paramètres en fonction du résultat souhaité.
Paramètre Recommandation d'utilisation
regionCode Définie en fonction des préférences régionales de l'utilisateur.
includedRegionCodes Définissez cette option pour limiter les résultats à la liste des régions spécifiées.
locationBias Utilisez cette option lorsque vous souhaitez obtenir des résultats dans une région ou à proximité. Le cas échéant, définissez la région comme la fenêtre d'affichage de la carte que l'utilisateur consulte.
locationRestriction Utilisez uniquement lorsque les résultats en dehors d'une région ne doivent pas être renvoyés.
origin À utiliser lorsqu'une distance en ligne droite par rapport à chaque prédiction est prévue.

Exemples d'Autocomplete (New)

Restreindre la recherche à une zone à l'aide de locationRestriction

locationRestriction spécifie la zone à rechercher. Les résultats en dehors de la zone spécifiée ne sont pas renvoyés. Dans l'exemple suivant, vous utilisez locationRestriction pour limiter la requête à un cercle de 5 000 mètres de rayon centré sur San Francisco :

curl -X POST -d '{
  "input": "Art museum",
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Tous les résultats des zones spécifiées sont contenus dans le tableau suggestions :

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "text": {
            "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 6,
                "endOffset": 16
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Asian Art Museum",
              "matches": [
                {
                  "startOffset": 6,
                  "endOffset": 16
                }
              ]
            },
            "secondaryText": {
              "text": "Larkin Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "establishment",
            "museum",
            "point_of_interest"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJI7NivpmAhYARSuRPlbbn_2w",
          "placeId": "ChIJI7NivpmAhYARSuRPlbbn_2w",
          "text": {
            "text": "de Young Museum, Hagiwara Tea Garden Drive, San Francisco, CA, USA",
            "matches": [
              {
                "endOffset": 15
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "de Young Museum",
              "matches": [
                {
                  "endOffset": 15
                }
              ]
            },
            "secondaryText": {
              "text": "Hagiwara Tea Garden Drive, San Francisco, CA, USA"
            }
          },
          "types": [
            "establishment",
            "point_of_interest",
            "tourist_attraction",
            "museum"
          ]
        }
      },
      /.../
    ]
  }

Vous pouvez également utiliser locationRestriction pour limiter les recherches à une fenêtre d'affichage rectangulaire. L'exemple suivant limite la requête au centre-ville de San Francisco :

  curl -X POST -d '{
    "input": "Art museum",
    "locationRestriction": {
      "rectangle": {
        "low": {
          "latitude": 37.7751,
          "longitude": -122.4219
        },
        "high": {
          "latitude": 37.7955,
          "longitude": -122.3937
        }
      }
    }
  }' \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  https://places.googleapis.com/v1/places:autocomplete

Les résultats sont contenus dans le tableau suggestions :

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "text": {
            "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 6,
                "endOffset": 16
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Asian Art Museum",
              "matches": [
                {
                  "startOffset": 6,
                  "endOffset": 16
                }
              ]
            },
            "secondaryText": {
              "text": "Larkin Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "museum",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJyQNK-4SAhYARO2DZaJleWRc",
          "placeId": "ChIJyQNK-4SAhYARO2DZaJleWRc",
          "text": {
            "text": "International Art Museum of America, Market Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 14,
                "endOffset": 24
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "International Art Museum of America",
              "matches": [
                {
                  "startOffset": 14,
                  "endOffset": 24
                }
              ]
            },
            "secondaryText": {
              "text": "Market Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "museum",
            "point_of_interest",
            "tourist_attraction",
            "art_gallery",
            "establishment"
          ]
        }
      }
    ]
  }

Pondérer la recherche sur une zone à l'aide de locationBias

Avec locationBias, l'emplacement sert de pondération, ce qui signifie que des résultats situés autour de l'emplacement spécifié peuvent être renvoyés, y compris des résultats situés en dehors de la zone spécifiée. Dans l'exemple suivant, vous orientez la requête vers le centre-ville de San Francisco :

curl -X POST -d '{
  "input": "Amoeba",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Les résultats contiennent désormais beaucoup plus d'éléments, y compris des résultats situés en dehors du rayon de 5 000 mètres :

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "store",
          "establishment",
          "home_goods_store"
        ]
      }
    },
    {
      "placePrediction": {
        "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw",
        "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw",
        "text": {
          "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Telegraph Avenue, Berkeley, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "establishment",
          "home_goods_store",
          "store"
        ]
      }
    },
    ...
  ]
}

Vous pouvez également utiliser locationBias pour orienter les recherches vers une fenêtre d'affichage rectangulaire. L'exemple suivant limite la requête au centre-ville de San Francisco :

  curl -X POST -d '{
    "input": "Amoeba",
    "locationBias": {
      "rectangle": {
        "low": {
          "latitude": 37.7751,
          "longitude": -122.4219
        },
        "high": {
          "latitude": 37.7955,
          "longitude": -122.3937
        }
      }
    }
  }' \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  https://places.googleapis.com/v1/places:autocomplete

Bien que les résultats de recherche dans la fenêtre d'affichage rectangulaire apparaissent dans la réponse, certains résultats se trouvent en dehors des limites définies, en raison de la pondération. Les résultats sont également contenus dans le tableau suggestions :

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
          "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
          "text": {
            "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Haight Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw",
          "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw",
          "text": {
            "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Telegraph Avenue, Berkeley, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJRdmfADq_woARYaVhnfQSUTI",
          "placeId": "ChIJRdmfADq_woARYaVhnfQSUTI",
          "text": {
            "text": "Amoeba Music, Hollywood Boulevard, Los Angeles, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Hollywood Boulevard, Los Angeles, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
    /.../
    ]
  }

Utiliser includedPrimaryTypes

Utilisez le paramètre includedPrimaryTypes pour spécifier jusqu'à cinq valeurs de type du tableau A, du tableau B, ou seulement (regions), ou seulement (cities). Un lieu doit correspondre à l'une des valeurs de type principal spécifiées pour être inclus dans la réponse.

Dans l'exemple suivant, vous spécifiez une chaîne input "Soccer" et utilisez le paramètre includedPrimaryTypes pour limiter les résultats aux établissements de type "sporting_goods_store" :

curl -X POST -d '{
  "input": "Soccer",
  "includedPrimaryTypes": ["sporting_goods_store"],
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Si vous omettez le paramètre includedPrimaryTypes, les résultats peuvent inclure des établissements d'un type que vous ne souhaitez pas, comme "athletic_field".

Demander des prédictions de requête

Les prédictions de requêtes ne sont pas renvoyées par défaut. Utilisez le paramètre de requête includeQueryPredictions pour ajouter des prédictions de requête à la réponse. Exemple :

curl -X POST -d '{
  "input": "Amoeba",
  "includeQueryPredictions": true,
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Le tableau suggestions contient désormais à la fois des prédictions de lieux et des prédictions de requêtes, comme indiqué ci-dessus dans À propos de la réponse. Chaque prédiction de requête inclut le champ text contenant une chaîne de recherche textuelle recommandée. Vous pouvez envoyer une requête Text Search (New) pour obtenir plus d'informations sur les prédictions de requête renvoyées.

Utiliser l'origine

Dans cet exemple, incluez origin dans la requête en tant que coordonnées de latitude et de longitude. Lorsque vous incluez origin, Autocomplete (New) inclut le champ distanceMeters dans la réponse, qui contient la distance en ligne droite entre origin et la destination. Cet exemple définit l'origine sur le centre de San Francisco :

curl -X POST -d '{
  "input": "Amoeba",
  "origin": {
    "latitude": 37.7749,
    "longitude": -122.4194
  },
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

La réponse inclut désormais distanceMeters :

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "home_goods_store",
          "establishment",
          "point_of_interest",
          "store",
          "electronics_store"
        ],
        "distanceMeters": 3012
      }
    }
  ]
}

Trouver des établissements qui ouvriront prochainement

L'exemple suivant montre une requête Autocomplete (New) pour les établissements qui ouvriront à l'avenir à New Meadows, dans l'Idaho :

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "input": "Roberts Greenhouse and Tree Farm",
  "includeFutureOpeningBusinesses": true,
  "locationBias": {
    "circle": {
      "center": {"latitude": 44.9755100, "longitude": -116.2842180},
      "radius": 20
    }
  }
}' \
"https://places.googleapis.com/v1/places:autocomplete"

La réponse inclut des informations sur le lieu, mais pas la date d'ouverture.

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJp1-VoKWJplQRMz8g-7Wa3Do",
        "placeId": "ChIJp1-VoKWJplQRMz8g-7Wa3Do",
        "text": {
          "text": "Roberts Greenhouse and Tree Farm, McLain Street, New Meadows, ID, USA",
          "matches": [
            {
              "endOffset": 32
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Roberts Greenhouse and Tree Farm",
            "matches": [
              {
                "endOffset": 32
              }
            ]
          },
          "secondaryText": {
            "text": "McLain Street, New Meadows, ID, USA"
          }
        },
        "types": [
          "garden_center",
          "establishment",
          "service",
          "store",
          "point_of_interest"
        ]
      }
    }
  ]
}

Distance manquante dans la réponse

Dans certains cas, distanceMeters est manquant dans le corps de la réponse, même lorsque origin est inclus dans la requête. Cela peut se produire dans les scénarios suivants :

  • distanceMeters n'est pas inclus pour les prédictions route.
  • distanceMeters n'est pas inclus lorsque sa valeur est 0, ce qui est le cas pour les prédictions situées à moins d'un mètre de l'emplacement origin fourni.

Les bibliothèques clientes qui tentent de lire le champ distanceMeters d'un objet analysé renvoient un champ avec la valeur 0. Pour éviter d'induire les utilisateurs en erreur, n'affichez pas une distance nulle.

Optimisation de la saisie semi-automatique (nouvelle version)

Cette section décrit les bonnes pratiques pour vous aider à exploiter au mieux le service Autocomplete (New).

Voici quelques consignes générales :

  • Le moyen le plus rapide de développer une interface utilisateur fonctionnelle consiste à utiliser le widget Autocomplete (New) de l'API Maps JavaScript, le widget Autocomplete (New) du SDK Places pour Android ou le widget Autocomplete (New) du SDK Places pour iOS.
  • Développez dès le départ vos connaissances des champs de données Autocomplete (New) 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 Autocomplete (New), utilisez des masques de champ dans les widgets Place Details (New) et Autocomplete (New) afin de ne renvoyer que les champs de données Autocomplete (New) dont vous avez besoin.

Optimisation avancée des coûts

Envisagez d'implémenter Autocomplete (New) de manière programmatique pour accéder au tarif du SKU Autocomplete Request et demander des résultats d'API Geocoding pour le lieu sélectionné plutôt que pour Place Details (New). 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 (New).
  • Si les utilisateurs sélectionnent une prédiction de saisie semi-automatique toutes les quatre requêtes de prédiction Autocomplete (New) ou moins en moyenne, la tarification par requête peut être plus rentable que celle par session.
Pour choisir l'implémentation de la saisie semi-automatique (New) la moins coûteuse pour votre application, recherchez la ligne du tableau suivant qui correspond aux besoins de votre application.
Ce dont votre application a besoin Nombre moyen de requêtes Autocomplete (New) 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 Autocomplete (New) basé sur des sessions avec Place Details (New)
Uniquement l'adresse et la latitude/longitude de la prédiction sélectionnée Quatre ou moins Autocomplete (New) par requête avec l'API Geocoding
Uniquement l'adresse et la latitude/longitude de la prédiction sélectionnée Plus de quatre Autocomplete (New) basé sur des sessions pour les applications d'adresse uniquement

L'API Geocoding peut être une option plus rentable que Place Details (New) pour votre application, en fonction de vos performances d'utilisation d'Autocomplete (New). L'efficacité de la saisie semi-automatique (New) 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 Autocomplete (New) dans votre application.

Autocomplete basé sur des sessions (New) avec Place Details (New)

Utilisez Autocomplete (New) basé sur des sessions avec Place Details (New).
Étant donné que votre application nécessite Place Details (New), comme le nom du lieu, l'état de l'établissement ou les horaires d'ouverture, votre implémentation d'Autocomplete (New) 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 Places applicables, 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 Autocomplete (New) et la requête Place Details (New) 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 Autocomplete (New) dont vous avez besoin.

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

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

Autocomplete (New) par requête avec l'API Geocoding

Implémentez Autocomplete (New) 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 plus un appel de l'API Geocoding pour la prédiction de lieu sélectionnée est inférieur au coût par session d'Autocomplete (New)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.

Autocomplete (New) basé sur des sessions pour les applications d'adresse uniquement

Utilisez Autocomplete (New) basé sur des sessions avec Place Details (New).
É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 Autocomplete (New) dépasse le coût de la tarification par session, votre implémentation d'Autocomplete (New) doit utiliser un jeton de session pour les requêtes Autocomplete (New) et la requête Place Details (New) 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 Autocomplete (New) et la requête Place Details (New) 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 Autocomplete (New). Lorsque vous demandez des détails sur un lieu (nouvelle version) concernant la prédiction sélectionnée, incluez les paramètres suivants :

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

Envisagez de reporter les requêtes Autocomplete (New)
Vous pouvez appliquer des stratégies telles que le report d'une requête Autocomplete (New) 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 Autocomplete (New) 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 effectuez une requête API Geocoding, le coût total correspondra à quatre requêtes Autocomplete (New) 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 Autocomplete (New) à 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.


  1. 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 la saisie semi-automatique (New) :

  • Ajoutez des restrictions locales applicables, une pondération géographique et des préférences de langue (pour les implémentations programmatiques) à votre implémentation Autocomplete (New). 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 Autocomplete (New) 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 (New), 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 (New). Si les résultats ne sont attendus que dans une région spécifique, utilisez la pondération géographique.
    Voici d'autres scénarios dans lesquels il est préférable de revenir à l'API Geocoding :
    • 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 Autocomplete (New).
    • 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ï.

Orientation géographique

Limitez les résultats à une zone spécifique en transmettant les paramètres location et radius. Cela indique à Autocomplete (New) 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 locationRestriction. Cela indique à Autocomplete (New) de ne renvoyer que les résultats situés dans cette région.

Essayer

APIs Explorer vous permet d'effectuer des exemples de requêtes afin de vous familiariser avec l'API et ses options.

  1. Sélectionnez l'icône API api sur le côté droit de la page.

  2. Vous pouvez modifier les paramètres de la requête.

  3. Sélectionnez le bouton Exécuter. Dans la boîte de dialogue, choisissez le compte que vous souhaitez utiliser pour effectuer la requête.

  4. Dans le panneau APIs Explorer, sélectionnez l'icône Plein écran fullscreen pour agrandir la fenêtre APIs Explorer.