Country Data API

Détail du Lieu

Tout ce dont vous avez besoin dès que l'utilisateur choisit une suggestion

L'endpoint /v1/places/details reçoit l'id d'une suggestion d'autocomplétion et retourne la fiche complète : toute la hiérarchie, le format de code postal du pays et les données dont un formulaire a généralement besoin ensuite — indicatif téléphonique, devise, fuseaux horaires.

Endpoint

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

Paramètres de Requête

Paramètre Type Requis Description
apikey string Oui Votre clé d'authentification API
id string Oui L'id retourné par /v1/places/autocomplete
type string Oui country, state ou city — le type de la suggestion
lang string Non Langue des noms retournés. Par défaut en
sessiontoken string Non Le jeton de session utilisé pendant l'autocomplétion. Rend cet appel gratuit

Exemple de Requête

curl "https://api.countrydataapi.com/v1/places/details?apikey=votre-cle-api&id=66c7a6c9e4bda21f4ab1a0f1&type=city&lang=fr"

JavaScript

async function getDetails(suggestion, sessionToken) {
  const params = new URLSearchParams({
    apikey: 'votre-cle-api',
    id: suggestion.id,
    type: suggestion.type,
    lang: 'fr',
    sessiontoken: sessionToken,
  });

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

SDK TypeScript

const { place } = await api.places.details({
  id: suggestion.id,
  type: suggestion.type,
  sessiontoken: session,
});

place.components.country?.phone_code; // "+34"
place.postal.regex;                   // "^\\d{5}$"

Format de Réponse

{
  "success": true,
  "place": {
    "id": "66c7a6c9e4bda21f4ab1a0f1",
    "type": "city",
    "name": "Madrid",
    "description": "Madrid, Communauté de Madrid, Espagne",
    "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": "🇪🇸"
      }
    },
    "postal": {
      "format": "#####",
      "regex": "^\\d{5}$",
      "example": "12345"
    },
    "location": null,
    "country_info": {
      "currencies": [{ "code": "EUR", "name": "Euro", "symbol": "€" }],
      "languages": ["Espagnol"],
      "timezones": ["UTC+01:00"],
      "continent": "EU",
      "region": "Europe"
    }
  },
  "tokens_used": 0,
  "remaining_tokens": 4871
}

Champs de la Réponse

Champ Type Description
place.components object Hiérarchie complète : city, state, country
place.postal.format string Modèle : # est un chiffre, @ est une lettre
place.postal.regex string Motif officiel de code postal du pays
place.postal.example string Valeur d'exemple dérivée de format et vérifiée contre regex
place.location object Coordonnées — voir la note ci-dessous
place.country_info object Devises, langues, fuseaux horaires, continent et région

À propos de location

location n'est renseigné que pour type=country, où il porte le centroïde du pays et "precision": "country".

Pour les états et les villes, il vaut null. Le jeu de données est administratif et ne contient pas de coordonnées par ville ; retourner le centroïde du pays en le présentant comme la ville serait pire que de ne rien retourner. Si vous avez besoin de coordonnées au niveau de la ville ou de géocodage, cet endpoint n'est pas le bon outil.

Consommation de Jetons

  • 0 jeton quand sessiontoken correspond à une session d'autocomplétion ouverte. La session a déjà été facturée à la première frappe, et cet appel la clôt.
  • 1 jeton dans les autres cas.

Autrement dit, un champ d'adresse complet — toutes les frappes nécessaires plus la consultation finale du détail — coûte un seul jeton.

Réponse d'Erreur

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "No city found with id \"abc\".",
    "status": 404
  },
  "message": "No city found with id \"abc\"."
}

Endpoints Connexes