Formato de Código Postal

Valide o campo de código postal sem uma ida e volta ao servidor

Os códigos postais não se parecem em nada entre países: cinco dígitos na Espanha, SW1A 1AA no Reino Unido, K1A 0B1 no Canadá. O endpoint /v1/places/postal-format fornece o formato, a expressão regular oficial e um valor de exemplo por país, para que seu formulário valide o campo no navegador e mostre um placeholder que faça sentido.

Endpoint

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

Parâmetros de Consulta

Exemplo de Requisição

curl "https://api.countrydataapi.com/v1/places/postal-format?apikey=sua-chave-api&country=ES&lang=pt"

Baixe todos os países uma vez e faça cache

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

// Indexar por ISO-2 para buscas instantâneas no formulário
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 da Resposta

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

O modelo format

Assim, @@# #@@ descreve um código postal britânico e produz o exemplo AB1 2CD.

example é gerado a partir de format e depois verificado contra regex. Se os dois não concordarem, example vale null em vez de um valor inventado no qual você não pode confiar. Países sem sistema postal retornam null nos três campos.

Uso em um formulário

function validatePostcode(value, iso2) {
  const postal = formats[iso2];
  if (!postal?.regex) return true; // sem padrão registrado: aceita qualquer coisa
  return new RegExp(postal.regex).test(value.trim());
}

// Também serve como placeholder
input.placeholder = formats[iso2]?.example ?? '';

Validar no navegador é uma melhoria de experiência do usuário, não uma garantia. Um código postal bem formado não é necessariamente um código real: confirme-o com /v1/places/validate antes de enviar qualquer coisa para esse endereço.

Consumo de Tokens

1 token por requisição, tanto se você pedir um país quanto se pedir todos.

Esses dados quase não mudam. Baixe a lista completa uma vez, faça cache e você não precisará deste endpoint por meses. Você é livre para conservá-la pelo tempo que quiser.

Endpoints Relacionados

• GET /v1/places/validate - Verificar se um código postal existe de verdade
• GET /v1/places/autocomplete - Buscar enquanto o usuário digita
• GET /v1/zipcodes/country - Lista completa de códigos postais de um país