Country Data API

Format de Code Postal

Validez le champ code postal sans aller-retour serveur

Les codes postaux ne se ressemblent pas d'un pays à l'autre : cinq chiffres en Espagne, SW1A 1AA au Royaume-Uni, K1A 0B1 au Canada. L'endpoint /v1/places/postal-format vous donne le format, l'expression régulière officielle et une valeur d'exemple par pays, pour que votre formulaire valide le champ dans le navigateur et affiche un placeholder qui a du sens.

Endpoint

GET https://api.countrydataapi.com/v1/places/postal-format

Paramètres de Requête

Paramètre Type Requis Description
apikey string Oui Votre clé d'authentification API
country string Non Id interne, ISO-2, ISO-3 ou nom. Omettez-le pour obtenir tous les pays
lang string Non Langue des noms de pays. Par défaut en

Exemple de Requête

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

Récupérez tous les pays une fois et mettez-les en cache

const response = await fetch(
  'https://api.countrydataapi.com/v1/places/postal-format?apikey=votre-cle-api&lang=fr'
);
const { data } = await response.json();

// Indexer par ISO-2 pour des recherches instantanées dans le formulaire
const formats = Object.fromEntries(
  data.map(({ country, postal }) => [country.iso2, postal])
);

localStorage.setItem('postal_formats', JSON.stringify(formats));

SDK TypeScript

const { data } = await api.places.postalFormat({ country: 'ES' });
data[0].postal.regex; // "^\\d{5}$"

Format de Réponse

{
  "success": true,
  "data": [
    {
      "country": {
        "id": "66c7a6c9e4bda21f4ab10ef2",
        "name": "Espagne",
        "iso2": "ES",
        "iso3": "ESP",
        "phone_code": "+34",
        "flag": "🇪🇸"
      },
      "postal": {
        "format": "#####",
        "regex": "^\\d{5}$",
        "example": "12345"
      }
    }
  ],
  "count": 1,
  "tokens_used": 1,
  "remaining_tokens": 4869
}

Le modèle format

Symbole Signification
# Un chiffre
@ Une lettre
tout autre Un caractère littéral (espace, tiret, préfixe pays...)

Ainsi, @@# #@@ décrit un code postal britannique et produit l'exemple AB1 2CD.

example est généré à partir de format puis vérifié contre regex. Si les deux ne concordent pas, example vaut null plutôt qu'une valeur inventée à laquelle vous ne pourriez pas vous fier. Les pays sans système postal retournent null dans les trois champs.

Utilisation dans un formulaire

function validatePostcode(value, iso2) {
  const postal = formats[iso2];
  if (!postal?.regex) return true; // aucun motif enregistré : on accepte tout
  return new RegExp(postal.regex).test(value.trim());
}

// Sert aussi de placeholder
input.placeholder = formats[iso2]?.example ?? '';

Valider dans le navigateur est un confort d'utilisation, pas une garantie. Un code postal bien formé n'est pas nécessairement un code réel : confirmez-le avec /v1/places/validate avant d'expédier quoi que ce soit à cette adresse.

Consommation de Jetons

1 jeton par requête, que vous demandiez un seul pays ou tous.

Ces données ne changent quasiment jamais. Récupérez la liste complète une fois, mettez-la en cache et vous n'aurez plus besoin de cet endpoint pendant des mois. Vous êtes libre de la conserver aussi longtemps que vous le souhaitez.

Endpoints Connexes