Autocomplétion de Lieux

Recherchez pays, états et villes pendant que l'utilisateur tape

L'endpoint /v1/places/autocomplete est le moteur du champ d'adresse d'un tunnel de commande, d'un formulaire d'inscription ou d'un calculateur de frais de port. Vous envoyez ce que l'utilisateur a saisi jusqu'à présent et vous recevez des suggestions classées par pertinence, chacune avec sa hiérarchie complète déjà résolue pour que vous puissiez afficher Madrid, Communauté de Madrid, Espagne sans un second appel.

Il couvre les niveaux pays, état et ville. Il ne couvre pas les adresses au niveau de la rue ni les points d'intérêt tels que les commerces, les horaires d'ouverture ou les avis.

Endpoint

GET https://api.countrydataapi.com/v1/places/autocomplete

Paramètres de Requête

Comment fonctionne la correspondance

La requête est normalisée avant la recherche, pour que l'utilisateur n'ait pas à se battre avec son clavier :

• Insensible à la casse et aux accents — avila trouve Ávila, munchen trouve München.
• Insensible à la ponctuation — hospitalet trouve L'Hospitalet de Llobregat.
• N'importe quel mot correspond — york trouve New York, et pas seulement les noms commençant par York.

Les résultats sont classés selon la qualité de la correspondance (nom exact, puis début du nom, puis début d'un mot interne), ensuite du niveau administratif le plus large au plus précis, et enfin par longueur du nom. Le champ match de chaque suggestion indique quelle règle s'est appliquée, ce qui est pratique pour mettre le texte en surbrillance.

Exemple de Requête

curl "https://api.countrydataapi.com/v1/places/autocomplete?apikey=votre-cle-api&q=mad&country=ES&limit=5&lang=fr"

JavaScript

const API_KEY = 'votre-cle-api';

async function search(query, sessionToken) {
  const params = new URLSearchParams({
    apikey: API_KEY,
    q: query,
    limit: '5',
    lang: 'fr',
    sessiontoken: sessionToken,
  });

  const response = await fetch(
    `https://api.countrydataapi.com/v1/places/autocomplete?${params}`
  );
  return response.json();
}

Python

import requests

response = requests.get(
    'https://api.countrydataapi.com/v1/places/autocomplete',
    params={
        'apikey': 'votre-cle-api',
        'q': 'mad',
        'country': 'ES',
        'limit': 5,
        'lang': 'fr',
    },
)
data = response.json()

SDK TypeScript

import { CountryDataApi, Places } from '@countrydataapi/sdk';

const api = new CountryDataApi({ apiKey: 'votre-cle-api' });
const session = Places.createSession();

const { suggestions } = await api.places.autocomplete({
  q: 'mad',
  country: 'ES',
  lang: 'fr',
  sessiontoken: session,
});

Format de Réponse

{
  "success": true,
  "query": "mad",
  "suggestions": [
    {
      "id": "66c7a6c9e4bda21f4ab1a0f1",
      "type": "city",
      "name": "Madrid",
      "description": "Madrid, Communauté de Madrid, Espagne",
      "match": "prefix",
      "components": {
        "city": { "id": "66c7a6c9e4bda21f4ab1a0f1", "name": "Madrid" },
        "state": { "id": "66c7a6c9e4bda21f4ab10a22", "name": "Communauté de Madrid" },
        "country": {
          "id": "66c7a6c9e4bda21f4ab10ef2",
          "name": "Espagne",
          "iso2": "ES",
          "iso3": "ESP",
          "phone_code": "+34",
          "flag": "🇪🇸"
        }
      }
    }
  ],
  "count": 1,
  "session": { "token": "6f9e...", "billed": true, "ttl_seconds": 180 },
  "tokens_used": 1,
  "remaining_tokens": 4871
}

Champs de la Réponse

Consommation de Jetons : on paie par session, pas par frappe

Une autocomplétion déclenche une requête à chaque touche. Facturer à la requête ferait qu'un seul champ d'adresse coûterait 8 à 10 jetons et transformerait votre facture en une fonction de la vitesse de frappe de vos utilisateurs.

Envoyez un sessiontoken — n'importe quel UUID, généré au moment où le champ prend le focus — et la session entière coûte 1 jeton, quel que soit le nombre de requêtes nécessaires :

1. Générez un jeton quand le champ d'adresse prend le focus.
2. Envoyez-le à chaque appel de /autocomplete. Seul le premier est facturé.
3. Envoyez-le lors de l'appel à /details pour la suggestion choisie par l'utilisateur. Cet appel est gratuit et clôt la session.
4. Générez un nouveau jeton pour le champ d'adresse suivant.

Les sessions expirent au bout de 3 minutes. Sans sessiontoken, chaque requête coûte 1 jeton.

// Une session par champ d'adresse
let session = crypto.randomUUID();

input.addEventListener('focus', () => { session = crypto.randomUUID(); });

// ...chaque frappe réutilise `session`, donc le champ entier coûte 1 jeton

Réponse d'Erreur

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Parameter \"q\" is required and must be at least 2 characters long.",
    "status": 400
  },
  "message": "Parameter \"q\" is required and must be at least 2 characters long."
}

Contrairement aux endpoints plus anciens, /v1/places/* retourne un vrai code HTTP (400, 401, 402, 404) accompagné d'un error.code stable. Consultez la documentation des codes d'erreur.

Appels depuis le navigateur

/v1/* envoie Access-Control-Allow-Origin: *, vous pouvez donc appeler l'autocomplétion directement depuis votre frontend sans proxy. Gardez à l'esprit que la clé API est alors visible pour quiconque ouvre les outils de développement : utilisez une clé dont le budget vous convient d'exposer, ou passez par votre propre backend si cela compte pour vous.

Conseils pratiques

1. Appliquez un debounce d'environ 150 ms. Moins de requêtes, même ressenti.
2. Exigez 2 à 3 caractères avant de lancer la recherche. Les requêtes plus courtes ne sont pas utiles.
3. Passez country quand vous le connaissez déjà. Moins de suggestions, et meilleures.
4. Passez types=city si le champ concerne spécifiquement une ville.
5. Ne mettez rien en cache par utilisateur — mais vous êtes libre de stocker et de mettre en cache les données retournées aussi longtemps que vous le souhaitez. Aucune restriction ne pèse sur leur conservation.

Endpoints Connexes

• GET /v1/places/details - Fiche complète d'une suggestion
• GET /v1/places/validate - Valider une adresse complète
• GET /v1/places/postal-format - Format de code postal par pays

Guide d'Intégration Complet

• Autocomplétion d'adresses, de bout en bout