Documentación de la API - Endpoints y Ejemplos

Formato de Código Postal

Valida el campo de código postal sin una ida y vuelta al servidor

Los códigos postales no se parecen en nada entre países: cinco dígitos en España, SW1A 1AA en Reino Unido, K1A 0B1 en Canadá. El endpoint /v1/places/postal-format te da el formato, la expresión regular oficial y un valor de ejemplo por país, para que tu formulario valide el campo en el navegador y muestre un placeholder que tenga sentido.

Endpoint

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

Parámetros de Consulta

Parámetro Tipo Requerido Descripción
apikey string Sí Tu clave de autenticación API
country string No Id interno, ISO-2, ISO-3 o nombre. Omítelo para obtener todos los países
lang string No Idioma de los nombres de país. Por defecto en

Ejemplo de Solicitud

curl "https://api.countrydataapi.com/v1/places/postal-format?apikey=tu-clave-api&country=ES&lang=es"

Descarga todos los países una vez y cachéalos

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

// Indexar por ISO-2 para búsquedas instantáneas en el formulario
const formats = Object.fromEntries(
  data.map(({ country, postal }) => [country.iso2, postal])
);

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

SDK de TypeScript

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

Formato de Respuesta

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

La plantilla format

Símbolo Significado
# Un dígito
@ Una letra
cualquier otro Un carácter literal (espacio, guion, prefijo de país...)

Así, @@# #@@ describe un código postal británico y produce el ejemplo AB1 2CD.

example se genera a partir de format y después se verifica contra regex. Si ambos no concuerdan, example vale null en lugar de un valor inventado en el que no puedes confiar. Los países sin sistema postal devuelven null en los tres campos.

Uso en un formulario

function validatePostcode(value, iso2) {
  const postal = formats[iso2];
  if (!postal?.regex) return true; // sin patrón registrado: se acepta cualquier cosa
  return new RegExp(postal.regex).test(value.trim());
}

// También sirve como placeholder
input.placeholder = formats[iso2]?.example ?? '';

Validar en el navegador es una mejora de experiencia de usuario, no una garantía. Un código postal bien formado no es necesariamente uno real: confírmalo con /v1/places/validate antes de enviar nada a esa dirección.

Consumo de Tokens

1 token por petición, tanto si pides un país como si los pides todos.

Estos datos apenas cambian. Descarga la lista completa una vez, cachéala y no necesitarás este endpoint en meses. Eres libre de conservarla todo el tiempo que quieras.

Endpoints Relacionados