Documentazione API - Endpoint ed Esempi

Formato del Codice Postale

Valida il campo del codice postale senza un giro sul server

I codici postali non si somigliano affatto da un paese all'altro: cinque cifre in Spagna, SW1A 1AA nel Regno Unito, K1A 0B1 in Canada. L'endpoint /v1/places/postal-format ti dà il formato, l'espressione regolare ufficiale e un valore di esempio per ogni paese, così il tuo modulo può validare il campo nel browser e mostrare un placeholder sensato.

Endpoint

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

Parametri di Query

Parametro Tipo Obbligatorio Descrizione
apikey string Sì La tua chiave di autenticazione API
country string No Id interno, ISO-2, ISO-3 o nome. Omettilo per ottenere tutti i paesi
lang string No Lingua dei nomi dei paesi. Predefinito: en

Esempio di Richiesta

curl "https://api.countrydataapi.com/v1/places/postal-format?apikey=la-tua-chiave-api&country=ES&lang=it"

Scarica tutti i paesi una volta e mettili in cache

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

// Indicizzare per ISO-2 per ricerche istantanee nel modulo
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}$"

Formato della Risposta

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

Il modello format

Simbolo Significato
# Una cifra
@ Una lettera
qualsiasi altro Un carattere letterale (spazio, trattino, prefisso del paese...)

Quindi @@# #@@ descrive un codice postale britannico e produce l'esempio AB1 2CD.

example viene generato da format e poi verificato contro regex. Se i due non concordano, example vale null invece di un valore inventato di cui non potresti fidarti. I paesi senza sistema postale restituiscono null in tutti e tre i campi.

Uso in un modulo

function validatePostcode(value, iso2) {
  const postal = formats[iso2];
  if (!postal?.regex) return true; // nessuna espressione registrata: accetta tutto
  return new RegExp(postal.regex).test(value.trim());
}

// Serve anche come placeholder
input.placeholder = formats[iso2]?.example ?? '';

Validare nel browser è un miglioramento dell'esperienza d'uso, non una garanzia. Un codice postale ben formato non è necessariamente reale: confermalo con /v1/places/validate prima di spedire qualcosa a quell'indirizzo.

Consumo di Token

1 token per richiesta, sia che tu chieda un paese sia che li chieda tutti.

Questi dati non cambiano quasi mai. Scarica l'elenco completo una volta, mettilo in cache e non ti servirà questo endpoint per mesi. Sei libero di conservarlo per tutto il tempo che vuoi.

Endpoint Correlati