Country Data API

Validation d'Adresses

Vérifiez qu'une adresse existe, et récupérez-la sous forme canonique

L'endpoint /v1/places/validate reçoit le pays, l'état, la ville et le code postal saisis par un utilisateur et vous indique si cette combinaison existe réellement — composant par composant —, en retournant l'orthographe canonique et, lorsque quelque chose ne colle pas, la correction la plus proche.

C'est la dernière étape avant d'enregistrer une adresse de livraison : l'autocomplétion guide l'utilisateur, ceci confirme ce sur quoi il a fini par s'arrêter, y compris les adresses saisies à la main ou importées d'ailleurs.

Endpoint

GET  https://api.countrydataapi.com/v1/places/validate
POST https://api.countrydataapi.com/v1/places/validate

Les deux acceptent les mêmes champs. GET est une requête CORS simple, elle fonctionne donc depuis le navigateur sans preflight ; POST les reçoit dans un corps JSON.

Paramètres

Paramètre Type Requis Description
apikey string Oui Votre clé d'authentification API
country string Oui Id interne, ISO-2, ISO-3 ou nom
state string Non Nom de l'état ou de la province
city string Non Nom de la ville
zipcode string Non Code postal
lang string Non Langue des noms retournés. Par défaut en

Les composants que vous n'envoyez pas reviennent avec le verdict not_provided : rien de ce que vous omettez ne peut invalider l'adresse.

Exemple de Requête

curl "https://api.countrydataapi.com/v1/places/validate?apikey=votre-cle-api&country=ES&state=Madrid&city=Madrid&zipcode=28001&lang=fr"

POST avec un corps JSON

const response = await fetch(
  'https://api.countrydataapi.com/v1/places/validate',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      apikey: 'votre-cle-api',
      country: 'ES',
      state: 'Madrid',
      city: 'Madrid',
      zipcode: '28001',
      lang: 'fr',
    }),
  }
);
const { result } = await response.json();

SDK TypeScript

const { result } = await api.places.validate({
  country: 'ES',
  zipcode: '28001',
  lang: 'fr',
});

result.normalized.state?.name; // "Communauté de Madrid"

Format de Réponse

{
  "success": true,
  "result": {
    "valid": true,
    "has_corrections": false,
    "verdict": {
      "country": "confirmed",
      "state": "confirmed",
      "city": "confirmed",
      "zipcode": "confirmed"
    },
    "normalized": {
      "country": {
        "id": "66c7a6c9e4bda21f4ab10ef2",
        "name": "Espagne",
        "iso2": "ES",
        "iso3": "ESP",
        "phone_code": "+34",
        "flag": "🇪🇸"
      },
      "state": { "id": "66c7a6c9e4bda21f4ab10a22", "name": "Communauté de Madrid" },
      "city": { "id": "66c7a6c9e4bda21f4ab1a0f1", "name": "Madrid" },
      "zipcode": "28001"
    },
    "corrections": [],
    "postal": {
      "format": "#####",
      "regex": "^\\d{5}$",
      "example": "12345",
      "matches_format": true
    }
  },
  "tokens_used": 1,
  "remaining_tokens": 4870
}

Verdicts

Verdict Signification
confirmed La valeur existe et correspond exactement à ce qui a été envoyé
corrected Le composant a été résolu, mais pas à partir de ce qui a été envoyé — voir corrections
unconfirmed La valeur n'a pas pu être vérifiée
not_provided Vous n'avez pas envoyé ce composant

valid ne vaut true que lorsque tous les composants que vous avez envoyés sont revenus en confirmed. Utilisez has_corrections pour décider s'il faut afficher à l'utilisateur un « vouliez-vous dire... ? » plutôt qu'une erreur.

Un code postal seul résout l'état

Le cas courant d'un tunnel de commande : vous n'avez demandé qu'un code postal et une ville.

curl "https://api.countrydataapi.com/v1/places/validate?apikey=votre-cle-api&country=ES&zipcode=28001&lang=fr"

La réponse remplit normalized.state à partir du code postal, vous pouvez donc compléter le champ province à la place de l'utilisateur au lieu de le lui demander. Cela fonctionne aussi dans l'autre sens : envoyez une ville et l'état revient résolu.

Quand le code postal n'est pas dans notre liste

La couverture des codes postaux n'est pas complète pour tous les pays. Si un code n'est pas répertorié mais correspond au format officiel du pays, le verdict est corrected plutôt que unconfirmed, et postal.matches_format vaut true. Traitez cela comme « plausible, acceptez-le », sauf si votre cas d'usage exige une certitude.

matches_format vaut null lorsque le pays n'a pas de motif officiel enregistré.

Exemple de correction

{
  "valid": false,
  "has_corrections": true,
  "verdict": { "country": "confirmed", "state": "unconfirmed", "city": "confirmed", "zipcode": "not_provided" },
  "corrections": [
    { "component": "state", "input": "Cataluna", "suggestion": "Cataluña" }
  ]
}

Consommation de Jetons

Cet endpoint consomme 1 jeton par requête, quel que soit le nombre de composants envoyés.

Endpoints Connexes