Documentação

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

Parâmetro Tipo Obrigatório Descrição
apikey string Sim Sua chave de autenticação da API
country string Não Id interno, ISO-2, ISO-3 ou nome. Omita para obter todos os países
lang string Não Idioma dos nomes dos países. Padrão: en

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

Símbolo Significado
# Um dígito
@ Uma letra
qualquer outro Um caractere literal (espaço, hífen, prefixo do país...)

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