Cette page a été traduite par l'API Cloud Translation.

Saisie semi-automatique (nouveau)

Sélectionnez une plate-forme: Android iOS JavaScript Service Web

Le service Autocomplete (nouveau) 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.

Le service Autocomplete (nouveau) peut établir une correspondance avec des mots complets et des sous-chaînes de l'entrée, ce qui permet de trouver des noms de lieux, des adresses et des plus codes. Les applications peuvent donc envoyer des requêtes lors de la frappe pour fournir des prédictions de lieux et de requêtes à la volée.

La réponse de l'API Autocomplete (nouvelle version) peut contenir deux types de prédictions:

Prédictions de lieu: 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 spécifiée et de la zone de recherche. Les prédictions de lieu sont renvoyées par défaut.
Prédictions de requête: chaînes de requête correspondant à la chaîne de texte d'entrée et à la zone de recherche. Les prédictions de requête 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 l'API en utilisant comme entrée une chaîne contenant une entrée utilisateur partielle, "Sicilian piz", avec la zone de recherche limitée à San Francisco, en Californie. La réponse contient ensuite une liste de prédictions de lieux correspondant à la chaîne de recherche et à la zone de recherche, par exemple le restaurant nommé "Sicilian Pizza Kitchen", ainsi que des détails sur le lieu.

Les prédictions de lieu 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 lieu renvoyées.

La réponse peut également contenir une liste de prédictions de requête qui correspondent à 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 dans Text Search (nouvelle version) pour effectuer une recherche plus détaillée.

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

Essayer

Requêtes Autocomplete (nouvelle)

Une requête Autocomplete (New) est une requête HTTP POST adressé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 dans 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

À propos de la réponse

La saisie semi-automatique (nouveau) renvoie un objet JSON en tant que réponse. Dans la réponse :

Le tableau suggestions contient tous les lieux et requêtes prédits dans l'ordre en fonction de leur pertinence estimée. Chaque lieu est représenté par un champ placePrediction et chaque requête est représentée par un champ queryPrediction.
Un champ placePrediction contient des informations détaillées sur une prédiction de lieu unique, y compris l'ID de lieu et une description textuelle.
Un champ queryPrediction contient des informations détaillées sur une prédiction de requête unique.

Remarque:La saisie semi-automatique (nouvelle version) renvoie cinq prédictions au total, sous la forme placePredictions, queryPredictions ou une combinaison des deux, en fonction de la requête. Par exemple, si la requête ne définit pas includeQueryPredictions, le corps de la réponse inclut jusqu'à cinq placePredictions. Si la requête définit includeQueryPredictions, le corps de la réponse inclut jusqu'à cinq prédictions dans une combinaison de placePredictions et queryPredictions.

L'objet JSON complet se présente sous la forme suivante:

{
  "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 dans 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 de saisie semi-automatique (nouveau) renvoie les résultats correspondant à cette chaîne et les classe en fonction de leur pertinence estimée.

Paramètres facultatifs

includedPrimaryTypes

Un lieu ne peut avoir qu'un seul type principal parmi les types répertoriés dans le Tableau A ou dans 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 de type principal associée au lieu. Limitez les résultats à un certain type principal 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, (regions) ou (cities). La collection de type (regions) filtre les zones ou les départements, tels que les quartiers et les codes postaux. Le type de filtre (cities) permet de filtrer les lieux que Google identifie en tant que ville.

La requête est rejetée avec une erreur INVALID_REQUEST dans les cas suivants:
- Plus de cinq types sont spécifiés.
- Tous les types sont spécifiés en plus de (cities) ou (regions).
- Tous les types non reconnus sont spécifiés.
Remarque:Le paramètre includedPrimaryTypes ne fonctionne que sur le type principal du lieu, et non sur tous les types qui lui sont associés. Bien que chaque lieu dispose d'un type principal, tous ne sont pas compatibles avec l'API Places (nouvelle version). Les types compatibles incluent ceux listés dans le Tableau A ou le Tableau B.
includeQueryPredictions

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

N'incluez que les résultats de la liste des régions spécifiées, sous la forme d'un tableau comportant jusqu'à 15 valeurs ccTLD ("domaine de premier niveau") à deux caractères. Si cette valeur 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 sont situés dans la zone d'intersection des deux paramètres.
inputOffset

Décalage du caractère Unicode de base 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 longueur par défaut est input.

Remarque : Dans la version preview privée initiale, cette propriété était appelée predictionTermOffset.
languageCode

Langue préférée dans laquelle les résultats doivent être renvoyés. Les résultats peuvent être rédigés dans différentes langues si la langue utilisée dans input est différente de la valeur spécifiée par languageCode, ou si le lieu renvoyé ne dispose pas d'une traduction de la langue locale vers languageCode.
- Vous devez utiliser les codes de langue IETF BCP-47 pour indiquer 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 de ces valeurs 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 petite 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.
- L'API tente de fournir une adresse postale lisible par l'utilisateur et la population locale, tout en reflétant les données saisies par l'utilisateur. Les prédictions de lieu sont formatées différemment en fonction de l'entrée utilisateur dans chaque requête.
  - Les termes correspondants dans le paramètre input sont choisis en premier, avec des noms alignés sur la préférence de langue indiquée par le paramètre languageCode lorsqu'il est disponible. Sinon, ils utilisent les noms qui correspondent le mieux à l'entrée utilisateur.
  - Les adresses postales sont formatées dans la langue locale, dans un script lisible par l'utilisateur si 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, une fois que les termes correspondants ont été choisis pour qu'ils correspondent à ceux du paramètre input. Si un nom n'est pas 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 locationRestriction comme spécifiant la région dans laquelle les résultats doivent se trouver, et locationBias comme spécifiant la région dans laquelle les résultats doivent se trouver, mais qui peuvent se trouver en dehors de cette zone.

Remarque : Si vous omettez à la fois locationBias et locationRestriction, l'API utilise la pondération de l'adresse IP par défaut. Avec la pondération de l'adresse IP, l'API utilise l'adresse IP de l'appareil pour pondérer les résultats.
- locationBias
  
  Spécifie une zone de recherche. Cet emplacement sert de biais, ce qui signifie que des résultats à proximité du lieu spécifié peuvent être renvoyés, y compris des résultats situés en dehors de cette zone.
- locationRestriction
  
  Spécifie une zone de recherche. Les résultats situés en dehors de la zone spécifiée ne sont pas renvoyés.
Spécifiez la région locationBias ou locationRestriction en tant que fenêtre d'affichage rectangulaire ou cercle.
- Un cercle est défini par le point central et le 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 en fonction de la latitude et de la longitude, représentée par deux points haut et low opposés en diagonale. Une fenêtre d'affichage est considérée comme une région fermée, ce qui signifie qu'elle inclut ses limites. Les limites de latitude doivent être comprises entre -90 et 90 degrés inclus, et les limites de longitude entre -180 et 180 degrés inclus:
  - Si low = high, la fenêtre d'affichage est constituée de ce seul point.
  - Si low.longitude > high.longitude, la plage de longitudes est inversée (la fenêtre d'affichage traverse la ligne de longitude à 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 longitudes est vide.
  Les champs low et high doivent tous les deux être renseignés, et la zone représentée ne peut pas être vide. Une fenêtre d'affichage vide entraîne une erreur.
  
  Par exemple, cette fenêtre d'affichage englobe entièrement New York:
```
"locationBias": {
  "rectangle": {
    "low": {
      "latitude": 40.477398,
      "longitude": -74.259087
    },
    "high": {
      "latitude": 40.91618,
      "longitude": -73.70018
    }
  }
}
```
origine

Point de départ à partir duquel calculer la distance en ligne droite jusqu'à la destination (renvoyé sous la forme distanceMeters). Si cette valeur est omise, la distance en ligne droite n'est pas renvoyée. Doit être spécifié en tant que 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 à deux caractères ccTLD ("domaine de premier niveau"). 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").

Si vous spécifiez un code de région non valide, l'API renvoie une erreur INVALID_ARGUMENT. Ce paramètre peut avoir un impact sur les résultats en fonction du droit applicable.
sessionToken

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

Exemples de saisie semi-automatique (nouveau)

Utiliser locationRestriction et locationBias

Par défaut, l'API utilise la pondération de l'adresse IP pour contrôler la zone de recherche. Avec la pondération de l'adresse IP, l'API utilise l'adresse IP de l'appareil pour pondérer les résultats. Vous pouvez éventuellement utiliser locationRestriction ou locationBias, mais pas les deux, pour spécifier une zone à rechercher.

locationRestriction spécifie la zone à rechercher. Les résultats situés 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 autour de San Francisco:

curl -X POST -d '{
  "input": "Amoeba",
  "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/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",
          "store",
          "point_of_interest",
          "electronics_store"
        ]
      }
    }
  ]
}

Avec locationBias, la localisation sert de biais, ce qui signifie que des résultats autour du lieu 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 modifiez la requête pour qu'elle utilise locationBias:

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"
        ]
      }
    },
    ...
  ]
}

Utiliser includePrimaryTypes

Utilisez le paramètre includedPrimaryTypes pour spécifier jusqu'à cinq valeurs de type parmi les suivantes : Table A, Tableau B, (regions) ou (cities) uniquement. 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 dont vous ne voulez pas, tels que "athletic_field".

Demander des prédictions de requête

Les prédictions de requête 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 des prédictions de lieu et de requête, comme indiqué ci-dessus dans la section À 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 effectuer une requête Text Search (New) pour obtenir plus d'informations sur les prédictions de requête renvoyées.

Remarque:Les prédictions de requête ne sont pas renvoyées lorsque le paramètre includedRegionCodes est défini.

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, l'API inclut le champ distanceMeters dans la réponse qui contient la distance en ligne droite entre origin et la destination. Dans l'exemple ci-dessous, le point de départ est défini 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
      }
    }
  ]
}

Essayer

APIs Explorer vous permet de créer des exemples de requêtes afin que vous puissiez vous familiariser avec l'API et ses options.

Sélectionnez l'icône API sur le côté droit de la page.
Vous pouvez également développer Afficher les paramètres standards et définir le paramètre fields sur le masque de champ.
Vous pouvez également modifier le corps de la requête.
Sélectionnez le bouton Execute (Exécuter). Dans la fenêtre pop-up, sélectionnez le compte à utiliser pour effectuer la demande.
Dans le panneau APIs Explorer, sélectionnez l'icône de développement pour développer la fenêtre de l'explorateur d'API.

Saisie semi-automatique (nouveau)

Requêtes Autocomplete (nouvelle)

À propos de la réponse

Paramètres obligatoires

entrée

Paramètres facultatifs

includedPrimaryTypes

includeQueryPredictions

includedRegionCodes

inputOffset

languageCode

locationBias ou locationRestriction

locationBias

locationRestriction

origine

regionCode

sessionToken

Exemples de saisie semi-automatique (nouveau)

Utiliser locationRestriction et locationBias

Utiliser includePrimaryTypes

Demander des prédictions de requête

Utiliser l'origine

Essayer