Saisie semi-automatique (nouveau)

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

Le service Autocomplete (New) peut rechercher des correspondances avec des mots complets et des sous-chaînes de l'entrée, afin de résoudre les noms de lieux, les adresses et les plus codes. Ainsi, les applications peuvent envoyer des requêtes lors de la frappe pour indiquer les lieux et les requêtes à la volée.

La réponse de l'API Autocomplete (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 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, "piz sicilien", la zone de recherche étant limitée à San Francisco, Californie. La réponse contient ensuite une liste de prédictions de lieu correspondant à la chaîne de recherche et à la zone de recherche, comme le restaurant nommé "Sicilian Pizza Kitchen", ainsi que des informations 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 envoyer 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 correspondant à la chaîne de recherche et à la zone de recherche, par exemple "Pizza sicilienne et pâtes". 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 de Text Search (New) pour effectuer une recherche plus détaillée.

Requêtes Autocomplete (New)

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 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

Envoyer une requête à l'aide de la saisie semi-automatique (nouveau)

L'API Places est compatible avec les API Autocomplete et Query Autocomplete existantes. Si vous connaissez ces API, la version preview d'Autocomplete (Nouveau) apporte les modifications suivantes:

• La nouvelle fonctionnalité Autocomplete utilise des requêtes HTTP POST. Transmettez des paramètres dans le corps de la requête ou dans des en-têtes dans une requête HTTP POST. En revanche, avec les API existantes, vous transmettez les paramètres d'URL à l'aide d'une requête HTTP GET.
• La nouvelle fonctionnalité de saisie semi-automatique est compatible avec les clés API et les jetons OAuth en tant que mécanisme d'authentification.
• Seul le format JSON est accepté comme format de réponse dans la nouvelle fonctionnalité de saisie semi-automatique.

Le tableau suivant répertorie les paramètres des API Autocomplete et Query Autocomplete existantes qui ont été renommés ou modifiés pour la nouvelle fonctionnalité Autocomplete, ou qui ne sont plus acceptés.

Paramètre actuel	Nouveau paramètre	Remarques
components	includedRegionCodes
language	languageCode
location	locationBias
ipbias		Si vous omettez à la fois locationBias et locationRestriction, l'API utilise la pondération de l'adresse IP par défaut.
offset	inputOffset
radius	locationBias ou locationRestriction
region	regionCode
stricbounds	locationRestriction
sessiontoken	sessionToken
types	includedPrimaryTypes

Limites d'utilisation

Dans la version preview, vous êtes limité à un maximum de 600 requêtes par minute et par projet.

Options d'assistance pour les versions preview

Google n'est pas tenu de fournir une assistance pour les versions preview, fonctions ou fonctionnalités des Services, mais nous prenons en compte les demandes à ces étapes de développement au cas par cas.

• Les versions préliminaires ne sont pas couvertes par le Contrat de niveau de service de Google Maps Platform.
• L'utilisation de mécanismes de remplacement est recommandée, en particulier si vous utilisez une version préliminaire dans un environnement de production. Voici quelques exemples de situations de remplacement: quota dépassé, codes de réponse et latence inattendus, ou réponses inattendues par rapport à la saisie semi-automatique existante.

Vous pouvez utiliser Issue Tracker pour demander de nouvelles fonctionnalités ou suggérer des modifications à apporter aux fonctionnalités existantes. Veuillez décrire la fonctionnalité spécifique que vous souhaiteriez voir ajoutée, ainsi que les raisons pour lesquelles vous la trouvez importante. Si possible, incluez des détails spécifiques sur votre cas d'utilisation et les nouvelles possibilités que cette fonctionnalité vous offrirait:

• Signaler un bug
• Envoyer une demande de fonctionnalité

Pour toute autre question sur les fonctionnalités, veuillez envoyer un e-mail à newplacesapi@google.com.

À 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 l'ensemble des lieux et requêtes prédits dans l'ordre en fonction de leur pertinence perçue. Chaque lieu est représenté par un champ placePrediction et chaque requête est représentée par un champ queryPrediction.
• Le champ placePrediction contient des informations détaillées sur la prédiction de lieu, y compris l'ID de lieu et une description textuelle.
• Le champ queryPrediction contient des informations détaillées sur la prédiction d'une seule requête.

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 sur laquelle doit porter 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 classe les résultats en fonction de leur pertinence estimée.

Paramètres facultatifs

• includedPrimaryTypes

  Un lieu ne peut avoir qu'un seul type principal parmi les types Table A ou Table B qui lui sont associés. 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 ou plusieurs types principaux 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.

  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 non reconnus sont spécifiés.

• 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 les prédictions de lieu.

• includedRegionCodes

  Incluez uniquement les résultats de la liste des régions spécifiées, sous la forme d'un tableau de 15 ccTLD ("domaine de premier niveau") maximum à 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 de ces deux paramètres.

• inputOffset

  Décalage des 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, il est défini par défaut sur la longueur input.

• languageCode

  Langue préférée dans laquelle renvoyer les résultats. Les résultats peuvent être affichés 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 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 de 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 à la fois par l'utilisateur et par la population locale, tout en reflétant l'entrée 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, à l'aide de 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 mises en forme dans la langue locale à l'aide d'un script lisible par l'utilisateur si possible, uniquement après que les termes correspondants ont été sélectionnés pour correspondre à ceux 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é sélectionnés pour correspondre à ceux du paramètre input. Si un nom n'est pas disponible dans la langue préférée, l'API utilise le nom le 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 être à proximité, mais peuvent se trouver en dehors de la zone.

  • locationBias

    Spécifie une zone à rechercher. Cette position sert de pondération : les résultats situés autour du lieu spécifié peuvent être renvoyés, y compris ceux situés en dehors de la zone spécifiée.

  • locationRestriction

    Spécifie une zone à rechercher. 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 sous forme de cercle.

  • Un cercle est défini par son point central et son 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 opposés en diagonale et des points hauts. 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 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 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.

    low et high doivent être renseignés, et la zone représentée ne peut pas être vide. Une fenêtre d'affichage vide génère une erreur.

    Par exemple, la fenêtre d'affichage suivante inclut 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ée en tant que distanceMeters). Si cette valeur est omise, la distance en ligne droite n'est pas renvoyée. Elles doivent être spécifiées 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 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").

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

• 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 (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 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 de recherche.

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 centré sur 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, le lieu sert de pondération, ce qui signifie que les résultats situés autour du lieu spécifié peuvent être renvoyés, y compris les résultats situés en dehors de la zone spécifiée. Dans l'exemple suivant, vous allez modifier 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 de ce 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 limiter les résultats d'une requête d'un certain type, comme indiqué dans les tableaux A et B. Vous pouvez spécifier un tableau comportant jusqu'à cinq valeurs. Si cette valeur est omise, tous les types sont renvoyés.

Dans l'exemple suivant, vous spécifiez une chaîne input de "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 utiliser, 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 des prédictions 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.

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 cet exemple, 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
      }
    }
  ]
}