Documentação

Validação de Endereços

Verifique se um endereço existe e recupere-o em forma canônica

O endpoint /v1/places/validate recebe o país, o estado, a cidade e o código postal que um usuário digitou e informa se essa combinação realmente existe — componente por componente —, retornando a grafia canônica e, quando algo não confere, a correção mais próxima.

É o último passo antes de você salvar um endereço de entrega: o autocompletar orienta o usuário, e isto confirma no que ele acabou parando, incluindo endereços digitados à mão ou importados de outro lugar.

Endpoint

GET  https://api.countrydataapi.com/v1/places/validate
POST https://api.countrydataapi.com/v1/places/validate

Ambos aceitam os mesmos campos. GET é uma requisição CORS simples, então funciona a partir do navegador sem preflight; POST os recebe em um corpo JSON.

Parâmetros

Parâmetro Tipo Obrigatório Descrição
apikey string Sim Sua chave de autenticação da API
country string Sim Id interno, ISO-2, ISO-3 ou nome
state string Não Nome do estado ou província
city string Não Nome da cidade
zipcode string Não Código postal
lang string Não Idioma dos nomes retornados. Padrão: en

Os componentes que você não envia retornam com o veredito not_provided: nada que você omita pode invalidar o endereço.

Exemplo de Requisição

curl "https://api.countrydataapi.com/v1/places/validate?apikey=sua-chave-api&country=ES&state=Madrid&city=Madrid&zipcode=28001&lang=pt"

POST com corpo JSON

const response = await fetch(
  'https://api.countrydataapi.com/v1/places/validate',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      apikey: 'sua-chave-api',
      country: 'ES',
      state: 'Madrid',
      city: 'Madrid',
      zipcode: '28001',
      lang: 'pt',
    }),
  }
);
const { result } = await response.json();

SDK de TypeScript

const { result } = await api.places.validate({
  country: 'ES',
  zipcode: '28001',
  lang: 'pt',
});

result.normalized.state?.name; // "Comunidade de Madri"

Formato da Resposta

{
  "success": true,
  "result": {
    "valid": true,
    "has_corrections": false,
    "verdict": {
      "country": "confirmed",
      "state": "confirmed",
      "city": "confirmed",
      "zipcode": "confirmed"
    },
    "normalized": {
      "country": {
        "id": "66c7a6c9e4bda21f4ab10ef2",
        "name": "Espanha",
        "iso2": "ES",
        "iso3": "ESP",
        "phone_code": "+34",
        "flag": "🇪🇸"
      },
      "state": { "id": "66c7a6c9e4bda21f4ab10a22", "name": "Comunidade de Madri" },
      "city": { "id": "66c7a6c9e4bda21f4ab1a0f1", "name": "Madri" },
      "zipcode": "28001"
    },
    "corrections": [],
    "postal": {
      "format": "#####",
      "regex": "^\\d{5}$",
      "example": "12345",
      "matches_format": true
    }
  },
  "tokens_used": 1,
  "remaining_tokens": 4870
}

Vereditos

Veredito Significado
confirmed O valor existe e corresponde exatamente ao que foi enviado
corrected O componente foi resolvido, mas não a partir do que foi enviado — veja corrections
unconfirmed O valor não pôde ser verificado
not_provided Você não enviou este componente

valid só é true quando todos os componentes que você enviou retornaram como confirmed. Use has_corrections para decidir se mostra ao usuário um "você quis dizer...?" em vez de um erro.

Um código postal sozinho resolve o estado

O caso comum em um checkout: você só pediu código postal e cidade.

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

A resposta preenche normalized.state a partir do código postal, então você pode completar o campo de província pelo usuário em vez de pedi-lo. Funciona igualmente no sentido inverso: envie uma cidade e o estado retorna resolvido.

Quando o código postal não está na nossa lista

A cobertura de códigos postais não é completa para todos os países. Se um código não está listado mas corresponde ao formato oficial do país, o veredito é corrected em vez de unconfirmed, e postal.matches_format vale true. Trate isso como "plausível, aceite" a menos que seu caso de uso exija certeza.

matches_format é null quando o país não tem um padrão oficial registrado.

Exemplo de correção

{
  "valid": false,
  "has_corrections": true,
  "verdict": { "country": "confirmed", "state": "unconfirmed", "city": "confirmed", "zipcode": "not_provided" },
  "corrections": [
    { "component": "state", "input": "Cataluna", "suggestion": "Cataluña" }
  ]
}

Consumo de Tokens

Este endpoint consome 1 token por requisição, independentemente de quantos componentes você enviar.

Endpoints Relacionados