Pular para o conteúdo
MyCEP
Menu

Referência da API

MyCEP API

Consulta de CEPs e endereços do Brasil, enriquecimento geográfico/fiscal, autocomplete, geocoding reverso e consultas cadastrais. Autenticação por chave Bearer do assinante — sem necessidade de IP fixo.

Fontes dos dados. Coordenadas geográficas: Cadastro Nacional de Endereços para Fins Estatísticos (CNEFE), Censo Demográfico 2022 — IBGE. Códigos e divisões territoriais: IBGE. Base de CEPs: Correios.

Documento OpenAPI: /openapi.json · Crie sua chave em /account/api-keys

A chave fica apenas nesta aba do navegador: ela é enviada no cabeçalho da requisição de teste e não é gravada nem registrada em log. Prefira uma chave cep_test_.

Em produção, a chave fica no servidor: nunca a embuta no código do navegador nem em repositório público. Os exemplos aqui são ilustrativos — ver a seção 12 dos Termos.

Endereço por CEP

GET /api/v1/search/cep/{cep}

Sem chave, a rota responde ao limite público de 5 consultas/min por IP e sem campos de enriquecimento.

Respostas
  • 200 — Endereço encontrado.
  • 400 — CEP fora do formato de 8 dígitos (`invalid_cep`).
  • 404 — CEP não encontrado.
  • 401 — Chave ausente, inválida ou revogada.
  • 429 — Cota do plano atingida, limite público por minuto excedido ou IP temporariamente bloqueado.

CEPs por logradouro

GET /api/v1/search/address/{cidade}/{logradouro}

UTF-8 percent-encoded (ex.: "Peçanha" vira "Pe%C3%A7anha"). Byte cru ou sequência que não é UTF-8 válido (ex.: ISO-8859-1) é recusado com 400, e "%" literal precisa virar %25.

UTF-8 percent-encoded (ex.: "Peçanha" vira "Pe%C3%A7anha"). Byte cru ou sequência que não é UTF-8 válido (ex.: ISO-8859-1) é recusado com 400, e "%" literal precisa virar %25.

Respostas
  • 200 — Lista de endereços (até 50).
  • 400 — Cidade ou logradouro curtos demais (`invalid_query`), ou caminho que não é UTF-8 percent-encoded válido.
  • 401 — Chave ausente, inválida ou revogada.
  • 429 — Cota do plano atingida, limite público por minuto excedido ou IP temporariamente bloqueado.

Sugestões de logradouro (Growth+)

GET /api/v1/search/autocomplete

Menos de 3 caracteres retorna lista vazia, não erro. UTF-8 percent-encoded (ex.: "Peçanha" vira "Pe%C3%A7anha"). Byte cru ou sequência que não é UTF-8 válido (ex.: ISO-8859-1) é recusado com 400, e "%" literal precisa virar %25.

Respostas
  • 200 — Até 5 sugestões.
  • 401 — Chave ausente, inválida ou revogada.
  • 403 — O plano da chave não inclui este recurso (`plan_upgrade_required`).
  • 429 — Cota do plano atingida, limite público por minuto excedido ou IP temporariamente bloqueado.

Endereço mais próximo de uma coordenada (Business+)

GET /api/v1/search/reverse

Respostas
  • 200 — Endereço ou cidade mais próxima.
  • 400 — Coordenadas inválidas (`invalid_coordinates`).
  • 404 — Nada dentro do raio configurado.
  • 401 — Chave ausente, inválida ou revogada.
  • 403 — O plano da chave não inclui este recurso (`plan_upgrade_required`).
  • 429 — Cota do plano atingida, limite público por minuto excedido ou IP temporariamente bloqueado.

Consulta cadastral de CNPJ (Business+)

GET /api/v1/registry/cnpj/{cnpj}

Servido a partir de base local carregada de dados abertos/licenciados. Enquanto a base não estiver carregada, responde 503 `dataset_unavailable`.

Respostas
  • 200 — Empresa encontrada.
  • 400 — CNPJ inválido (dígitos verificadores).
  • 404 — CNPJ não consta na base.
  • 503 — Base cadastral ainda não carregada.
  • 401 — Chave ausente, inválida ou revogada.
  • 403 — O plano da chave não inclui este recurso (`plan_upgrade_required`).
  • 429 — Cota do plano atingida, limite público por minuto excedido ou IP temporariamente bloqueado.

Feriados nacionais, estaduais e municipais (Business+)

GET /api/v1/registry/holidays

Padrão: ano corrente.

Respostas
  • 200 — Feriados do período.
  • 400 — Ano (`invalid_year`) ou código IBGE (`invalid_ibge`) inválido.
  • 401 — Chave ausente, inválida ou revogada.
  • 403 — O plano da chave não inclui este recurso (`plan_upgrade_required`).
  • 429 — Cota do plano atingida, limite público por minuto excedido ou IP temporariamente bloqueado.

Validadores locais de CEP, CPF, CNPJ, telefone e chave PIX (Growth+)

GET /api/v1/validate/{kind}

Verifica formato e dígitos verificadores. NÃO afirma que o número está emitido nem que a chave PIX está registrada em algum banco.

Respostas
  • 200 — Resultado da validação.
  • 400 — Tipo (`invalid_kind`) ou valor (`invalid_value`) ausente ou inválido.
  • 401 — Chave ausente, inválida ou revogada.
  • 403 — O plano da chave não inclui este recurso (`plan_upgrade_required`).
  • 429 — Cota do plano atingida, limite público por minuto excedido ou IP temporariamente bloqueado.