API EvoDATA

Começando

Todos os recursos vivem sob um único host, em uma versão fixada no caminho. Não há SDK: qualquer cliente HTTP serve.

Primeira chamada

curl "https://evodata.app/api/v1/empresas?uf=DF&situacao=02&por_pagina=1"

Autenticação

Existem dois regimes, conforme a sensibilidade do dado:

Obtendo a chave

Emita em Chaves de API, no painel. A chave em claro aparece uma única vez, no momento da criação: o sistema guarda apenas um SHA-256, então nem o suporte consegue recuperá-la. Perdeu, revogue e emita outra. Cada conta pode manter até 5 chaves ativas — use uma por integração, para poder revogar uma sem derrubar as demais.

Enviando a chave

curl -H "Authorization: Bearer evd_SUA_CHAVE" \
  "https://evodata.app/api/v1/pessoas?nome=MARIA&uf=SP"

O cabeçalho X-API-Key é aceito como alternativa. A chave não é lida da query string, de propósito: parâmetro de URL vaza em log de servidor, histórico de navegador e cabeçalho Referer.

Recusas possíveis

Limites de uso

O custo real de cada chamada é uma consulta em um PostgreSQL de ~118 GB compartilhado com outro sistema em produção. O limite protege o banco, não o servidor de aplicação.

Endereços, IP, mapa e produtos têm limitador próprio: são leituras por chave no MySQL, em milissegundos, e não tocam o PostgreSQL compartilhado. Para volume, prefira os endpoints de lote — 100 itens valem uma requisição.

Cache HTTP

As consultas GET de endereço e de IP trazem Cache-Control: public, max-age=3600 e ETag. Repita a chamada com If-None-Match: <etag> e, se nada mudou, a resposta é 304 sem corpo. /ips/meu é a exceção: depende de quem pergunta e vem com private, no-store.

Cabeçalhos em toda resposta

Convenções

Listas

Parâmetros marcados como lista aceitam duas formas equivalentes. Valores repetidos são deduplicados e a ordem é irrelevante.

?uf=SP,RJ,MG          # separados por vírgula
?uf[]=SP&uf[]=RJ      # repetindo a chave

Valores fora do domínio

Filtros com domínio fechado — uf, situacao, porte, size_class, buscar_em, ordenar — descartam em silêncio o que não reconhecem, em vez de devolver erro. Uma UF digitada errado simplesmente não filtra. Se a lista inteira for inválida, o padrão do campo volta a valer.

Booleanos

Campos boolean ativam com 1, true, on ou yes; qualquer outra coisa desativa. Os campos marcados boolean³ são ternários: aceitam 1/true/S para sim, 0/false/N para não, e tratam a ausência como “indiferente”, que é diferente de “não”.

Números e datas

Valores monetários aceitam ponto ou vírgula decimal: 1500.50 e 1.500,50 chegam ao mesmo lugar. Datas usam AAAA-MM-DD e passam por validação de calendário — 2025-02-30 é descartada silenciosamente.

Datas com hora saem em ISO 8601 e em UTC (2026-11-16T04:52:10Z). Na entrada, alterado_desde aceita data ou data e hora; sem fuso, vale UTC (2026-11-01 é 2026-11-01T00:00:00Z, ou 21h do dia 31 em Brasília).

Buscar empresas

GET https://evodata.app/api/v1/empresas

Busca paginada sobre estabelecimentos. Ao menos um filtro é obrigatório — uma consulta irrestrita sobre dezenas de milhões de linhas não é atendida e devolve 422.

Parâmetros

Identificação

Localização

Atividade econômica

Situação e porte

Presença de contato

Enriquecimento

Paginação e ordenação

Resposta

{
  "dados": [ { /* objeto Empresa, ver abaixo */ } ],
  "paginacao": {
    "pagina": 1,
    "por_pagina": 25,
    "total": 482163,
    "total_exato": false,
    "tem_proxima": true
  },
  "avisos": []
}

avisos é um array de strings. Hoje ele só recebe uma mensagem, quando a ordenação pedida em ordenar foi descartada: classificar um conjunto muito grande faz o planejador trocar o índice correto por uma varredura ordenada da tabela inteira. Nesse caso os resultados voltam na ordem natural do índice e a requisição segue sendo 200.

Objeto Empresa

Exemplo

curl -G "https://evodata.app/api/v1/empresas" \
  --data-urlencode "uf=SP,RJ" \
  --data-urlencode "cnae=4721102" \
  --data-urlencode "abertura_de=2024-01-01" \
  --data-urlencode "com_email=1" \
  --data-urlencode "ordenar=abertura_desc" \
  --data-urlencode "por_pagina=50"

Ficha de empresa

GET https://evodata.app/api/v1/empresas/{cnpj}

Retorna um único estabelecimento com todo o detalhamento. O CNPJ pode vir com ou sem máscara e é validado pelos dígitos verificadores antes de qualquer consulta — um CNPJ malformado devolve 422 sem tocar o banco.

curl "https://evodata.app/api/v1/empresas/62.170.939/0001-51"
curl "https://evodata.app/api/v1/empresas/62170939000151"   # equivalente

A resposta é { "dados": { … } } com todos os campos do objeto Empresa, mais os seguintes:

Objeto sócio

{
  "nome": "FULANO DE TAL",
  "documento": "***040852**",        # PF sempre parcial
  "tipo": "Pessoa física",
  "eh_pessoa_juridica": false,
  "qualificacao": "Sócio-Administrador",
  "entrada": "2019-03-12",
  "faixa_etaria": "41 a 50 anos",
  "representante": null
}

Objeto simples

{
  "optante": true,
  "desde": "2020-01-01",
  "excluido_em": null,
  "mei": true,
  "mei_desde": "2020-01-01",
  "mei_excluido_em": null
}

Objeto unidade

Lista com todas as unidades que compartilham a mesma raiz de CNPJ, incluindo a própria consultada. Útil para navegar de uma filial à matriz.

{
  "cnpj": "62170939000151",
  "cnpj_formatado": "62.170.939/0001-51",
  "nome_fantasia": null,
  "tipo": "Matriz",
  "eh_matriz": true,
  "situacao": "Ativa",
  "ativa": true,
  "uf": "DF",
  "municipio": "BRASILIA",
  "cnae": "Cabeleireiros, manicure e pedicure",
  "abertura": "2025-08-11"
}

Fichas em lote

POST https://evodata.app/api/v1/empresas/lote

Até 100 CNPJs por chamada, cada um devolvido com a mesma ficha de GET /empresas/{cnpj} — é o caminho para buscar os dados das chaves que /empresas/alteracoes devolve. A ficha é cobrada como a avulsa, uma vez por CNPJ na competência; CNPJ inválido ou inexistente não cobra e sai com erro na própria linha, sem derrubar o lote.

curl -X POST "https://evodata.app/api/v1/empresas/lote" \
  -H "Authorization: Bearer evd_SUA_CHAVE" -H "Content-Type: application/json" \
  -d '{"cnpjs": ["00000000000191", "60701190000104"]}'

{
  "resultados": [
    { "cnpj": "00000000000191", "dados": { … a ficha … },
      "cobranca": { "creditos": 1, "ja_paga_na_competencia": false } },
    { "cnpj": "60701190000104", "erro": "nao_encontrado", "mensagem": "…" }
  ],
  "resumo": { "total": 2, "sucesso": 1, "creditos_debitados": 1, "saldo": 499 }
}

cobranca, creditos_debitados e saldo só vêm quando a chamada leva chave de API.

Buscar pessoas

GET https://evodata.app/api/v1/pessoas chave + plano pago

Busca sobre 233 milhões de pessoas físicas. Ao menos um filtro é obrigatório. Diferente da busca de empresas, aqui não há paginação: o parâmetro por_pagina define quantas linhas voltam, e tem_mais indica se existem outras. Percorrer profundamente um conjunto de centenas de milhões de linhas não é uma operação que esta base sustente — o caminho é refinar até o recorte caber.

Parâmetros

Resposta

{
  "dados": [
    {
      "id": 2091705,
      "nome": "MARIA APARECIDA SILVA",
      "cpf": "***.456.789-**",
      "nome_mae": "ROSA MARIA BELLONI",
      "sexo": "F",
      "sexo_descricao": "Feminino",
      "nascimento": "1975-03-22",
      "idade": 51,
      "estado_civil": "C",
      "estado_civil_descricao": "Casado(a)",
      "cbo": "2521",
      "cidade": "SAO PAULO",
      "uf": "SP",
      "ddd": 11,
      "telefone": 999998888
    }
  ],
  "paginacao": {
    "por_pagina": 25,
    "retornados": 25,
    "tem_mais": true,
    "amostra": false
  },
  "consulta": {
    "condutor": "pessoas",
    "ms": 32
  }
}

O bloco consulta é diagnóstico: condutor revela por qual tabela a consulta entrou, o que explica por que uma combinação ficou lenta. Filtros exatos — CPF, telefone, e-mail, CEP, PIS — conduzem por índice único e respondem em milissegundos; uf ou sexo sozinhos conduzem mal e tendem a virar amostra ou 503.

Exemplo

curl -H "Authorization: Bearer evd_SUA_CHAVE" -G "https://evodata.app/api/v1/pessoas" \
  --data-urlencode "nome=MARIA" \
  --data-urlencode "nome_mae=ANA" \
  --data-urlencode "uf=SP" \
  --data-urlencode "por_pagina=50"

Ficha de pessoa

GET https://evodata.app/api/v1/pessoas/{id} chave + plano pago

O id é o identificador interno devolvido no campo id da busca — não é o CPF, que nunca sai em claro por nenhum endpoint.

A resposta traz todos os campos da linha de busca, mais os blocos:

Pessoas em lote

POST https://evodata.app/api/v1/pessoas/lote chave + plano pago

Até 100 ids por chamada, cada um com a ficha completa — o caminho para os dados das chaves de /pessoas/alteracoes. Cobrança e erros por linha como no lote de empresas.

curl -X POST "https://evodata.app/api/v1/pessoas/lote" \
  -H "Authorization: Bearer evd_SUA_CHAVE" -H "Content-Type: application/json" \
  -d '{"ids": [1048576, 2097152]}'

Tabelas de referência

Os filtros cnae e municipio esperam códigos. Estes dois endpoints resolvem nome para código e servem bem a campos de autocompletar.

Buscar CNAE

GET https://evodata.app/api/v1/referencias/cnae?q={termo}

Busca textual na descrição das atividades. Termos com menos de 2 caracteres devolvem lista vazia e 200 — não é erro.

curl "https://evodata.app/api/v1/referencias/cnae?q=padaria"

{
  "dados": [
    { "codigo": 1091102, "descricao": "Fabricação de produtos de padaria e confeitaria com predominância de produção própria" },
    { "codigo": 4721101, "descricao": "Padaria e confeitaria com predominância de produção própria" },
    { "codigo": 4721102, "descricao": "Padaria e confeitaria com predominância de revenda" }
  ]
}

Municípios por UF

GET https://evodata.app/api/v1/referencias/municipios/{uf}

Todos os municípios de um estado, com o código que o filtro municipio espera. A sigla não diferencia maiúsculas.

curl "https://evodata.app/api/v1/referencias/municipios/df"

{ "dados": [ { "codigo": "9701", "nome": "BRASILIA" } ] }

Endereços e CEP

A base de endereçamento é o eDNE, o Diretório Nacional de Endereços dos Correios: 1,57 milhão de CEPs, 11,5 mil localidades e 83 mil bairros. Os endpoints são públicos, como as tabelas de referência, e não debitam crédito.

Nem todo CEP é de rua. O campo tipo diz de onde ele vem, e muda quais campos vêm preenchidos:

Consultar CEP

GET https://evodata.app/api/v1/ceps/{cep}

Aceita o CEP com ou sem máscara. Sete dígitos ganham o zero à esquerda: é o CEP de São Paulo, de 01000-000 a 09999-999, depois de passar por uma planilha que o guardou como número. Nenhum CEP começa com 00, então menos de sete dígitos é recusado com 422 cep_invalido.

curl "https://evodata.app/api/v1/ceps/01310-200"

{
  "dados": {
    "cep": "01310200",
    "cep_formatado": "01310-200",
    "tipo": "logradouro",
    "nome": null,
    "endereco": "Avenida Paulista",
    "tipo_logradouro": "Avenida",
    "logradouro": "Paulista",
    "complemento": "- de 1512 a 2132 - lado par",
    "numeracao": { "inicial": 1512, "final": 2132, "lado": "par" },
    "bairro": "Bela Vista",
    "distrito": null,
    "cidade": "São Paulo",
    "uf": "SP",
    "codigo_ibge": "3550308",
    "localidade_id": 9668,
    "caixas_postais": []
  }
}

Objeto endereço

Numeração

Rua longa tem um CEP por trecho. numeracao diz qual trecho: de inicial a final, do lado par, impar, ambos, direito ou esquerdo. final de 99999 ou mais significa “até o fim da rua”. Em rodovia a numeração é o quilômetro e pode ter fração: 116.302 é o km 116,302.

CEPs em lote

POST https://evodata.app/api/v1/ceps/lote

Até 100 CEPs por chamada, resolvidos numa consulta só. Cada item volta na mesma posição em que foi enviado, com dados ou com erro — um CEP inválido não derruba os outros.

curl -X POST "https://evodata.app/api/v1/ceps/lote" \
  -H "Content-Type: application/json" \
  -d '{"ceps": ["01310-100", "1310100", "99999999", "123"]}'

{
  "resultados": [
    { "cep": "01310100", "dados": { /* objeto endereço */ } },
    { "cep": "01310100", "dados": { /* o mesmo: 7 dígitos, zero completado */ } },
    { "cep": "99999999", "erro": "nao_encontrado", "mensagem": "CEP não consta no eDNE dos Correios." },
    { "cep": "123", "erro": "cep_invalido", "mensagem": "CEP deve ter 8 dígitos." }
  ],
  "resumo": { "total": 4, "sucesso": 2 }
}

Endereço → CEP

GET https://evodata.app/api/v1/ceps?uf=&cidade=&logradouro=

O caminho inverso: descobrir o CEP de um endereço. Devolve só CEPs de logradouro.

Com numero, cada rua traz só o CEP do trecho que contém o número; rua sem seccionamento (numeracao: null) entra sempre, porque o CEP dela vale para qualquer número. Por isso o exemplo abaixo traz, além da Avenida Paulista, outras ruas cujo nome começa por “Paulista”.

Acento e caixa não importam: sao paulo encontra São Paulo. O tipo digitado à frente do nome — Av., R, Travessa — é tentado com e sem, porque o eDNE guarda o nome sem ele e há logradouros cujo nome começa pelo tipo.

curl -G "https://evodata.app/api/v1/ceps" \
  --data-urlencode "uf=SP" \
  --data-urlencode "cidade=sao paulo" \
  --data-urlencode "logradouro=Av. Paulista" \
  --data-urlencode "numero=1578"
# resposta abreviada

{
  "dados": [
    { "cep": "01310200", "endereco": "Avenida Paulista", "complemento": "- de 1512 a 2132 - lado par",
      "numeracao": { "inicial": 1512, "final": 2132, "lado": "par" }, /* … */ },
    { "cep": "08190461", "endereco": "Viela Paulista", "numeracao": null, /* … */ },
    { "cep": "05440001", "endereco": "Rua Paulistânia", "complemento": "- de 453/454 ao fim", /* … */ }
  ],
  "paginacao": { "por_pagina": 25, "retornados": 3, "tem_mais": false }
}

Localidades e bairros

GET https://evodata.app/api/v1/localidades?uf={uf}

Municípios, distritos e povoados de um estado, com código IBGE e faixas de CEP. Filtre com nome (início do nome, sem distinção de acento) e tipo (municipio, distrito ou povoado).

curl "https://evodata.app/api/v1/localidades?uf=AC"

{
  "dados": [
    {
      "id": 1,
      "nome": "Acrelândia",
      "nome_abreviado": "Acrelândia",
      "tipo": "municipio",
      "uf": "AC",
      "codigo_ibge": "1200013",
      "cep": "69945000",
      "codificacao": "cep_unico",
      "municipio": null,
      "faixas_cep": [ { "inicial": "69945000", "final": "69949999", "abrangencia": "total" } ]
    },
    {
      "id": 11059,
      "nome": "Campinas",
      "tipo": "distrito",
      "uf": "AC",
      "codigo_ibge": "1200385",        # o do município, Plácido de Castro
      "cep": "69929000",
      "codificacao": "cep_unico",
      "municipio": { "id": 13, "nome": "Plácido de Castro" },
      /* … */
    }
  ]
}

GET https://evodata.app/api/v1/localidades/{id}

Uma localidade, com outras_denominacoes: nomes anteriores e grafias que os Correios aceitam (S C do Sul para São Caetano do Sul). Serve para casar endereço antigo ou digitado de outro jeito.

GET https://evodata.app/api/v1/localidades/{id}/bairros

Bairros da localidade em ordem alfabética, com id, nome, nome_abreviado e faixas_cep. As faixas de um bairro raramente são contínuas — Barcelona, em São Caetano do Sul, tem dez. 14% dos bairros não têm faixa própria no eDNE e saem com a lista vazia.

curl "https://evodata.app/api/v1/localidades/9642/bairros"

{
  "localidade": { "id": 9642, "nome": "São Caetano do Sul", "uf": "SP" },
  "dados": [
    {
      "id": 24379,
      "nome": "Barcelona",
      "nome_abreviado": "Barcelona",
      "faixas_cep": [
        { "inicial": "09550001", "final": "09550010" },
        { "inicial": "09550050", "final": "09550051" },
        /* … */
      ]
    }
  ]
}

GET https://evodata.app/api/v1/localidades/{id}/logradouros

Em 4.128 municípios os Correios têm um CEP para a cidade inteira (e às vezes um por distrito), e o eDNE não traz o nome de rua nenhuma. Para eles, este endpoint lista as ruas do OpenStreetMap — cerca de 458 mil, atualizadas toda semana —, cada uma com o CEP da localidade em que está, a coordenada e cep_criterio:

• cep_unico_do_municipio — o município tem um CEP só; não há o que errar.
• poligono_do_distrito — a rua está dentro do limite do distrito no OpenStreetMap.
• distrito_mais_proximo — o OpenStreetMap não desenha os distritos dali, e vale o mais próximo da rua. É estimativa: confira.

Conferido contra as ruas que trazem etiqueta de CEP no próprio OpenStreetMap: 98% de acerto pelo polígono, 97% pela proximidade. Aceita nome (início do nome da rua), pagina e por_pagina. Município com CEP por rua responde 422 — ali quem responde é /ceps, que nesses mesmos municípios também passa a devolver as ruas do OpenStreetMap, com fonte: "openstreetmap".

curl "https://evodata.app/api/v1/localidades/1/logradouros?nome=Avenida&por_pagina=1"

{
  "localidade": { "id": 1, "nome": "Acrelândia", "uf": "AC", "codigo_ibge": "1200013" },
  "dados": [
    {
      "cep": "69945000",
      "endereco": "Avenida 1",
      "tipo": "localidade",
      "distrito": null,
      "cidade": "Acrelândia",
      "fonte": "openstreetmap",
      "cep_criterio": "cep_unico_do_municipio",
      "coordenadas": { "latitude": -10.0727304, "longitude": -67.0622937, "precisao": "logradouro", "raio_m": 25 },
      /* … os demais campos de um CEP */
    }
  ],
  "paginacao": { "pagina": 1, "por_pagina": 1, "retornados": 1, "total": 125, "tem_mais": true },
  "fonte": { "nome": "OpenStreetMap", "atribuicao": "© colaboradores do OpenStreetMap — dados sob a licença ODbL (openstreetmap.org/copyright)" }
}

Alterações desde uma data

Para alimentar uma base própria e mantê-la em dia sem baixar tudo de novo: cada conjunto tem a lista do que entrou, mudou ou saiu desde uma data. Funciona para empresas, CEPs, localidades e pessoas.

GET https://evodata.app/api/v1/empresas/alteracoes

GET https://evodata.app/api/v1/ceps/alteracoes

GET https://evodata.app/api/v1/localidades/alteracoes

GET https://evodata.app/api/v1/pessoas/alteracoes chave + plano pago

Por que não um filtro por updated_at: nenhuma das fontes diz quando um registro mudou. O cadastro de CNPJ é regravado inteiro a cada carga mensal, e o dos Correios a cada importação — filtrar por essa data devolveria tudo ou nada. A data é produzida aqui, comparando cada carga da fonte com a anterior; alterado_em é quando essa comparação foi publicada.

Parâmetros

Um dos dois, alterado_desde ou cursor, é obrigatório. Formatos aceitos na data: 2026-11-01, 2026-11-01T03:00:00Z, 2026-11-01T00:00:00-03:00. Uma data posterior à última comparação devolve a lista vazia — e um proximo_cursor que já serve para as próximas.

Resposta

curl "https://evodata.app/api/v1/empresas/alteracoes?alterado_desde=2026-11-01&por_pagina=2"

{
  "dados": [
    { "cnpj": "00000000000191", "tipo": "alteracao", "partes": ["estabelecimento", "socios"],
      "alterado_em": "2026-11-16T04:52:10Z", "base_de": "2026-11-15T18:26:17Z" },
    { "cnpj": "60701190000104", "tipo": "inclusao", "partes": ["estabelecimento"],
      "alterado_em": "2026-11-16T04:52:10Z", "base_de": "2026-11-15T18:26:17Z" }
  ],
  "paginacao": { "por_pagina": 2, "retornados": 2, "tem_mais": true, "proximo_cursor": "1843" },
  "registro": { "inicio": "2026-10-14T18:26:17Z", "ultima_comparacao": "2026-11-16T04:52:10Z",
                "base_de": "2026-11-15T18:26:17Z" },
  "dados_completos": "POST /v1/empresas/lote"
}

Sincronizar uma base própria

1. Carga inicial pela consulta completa (busca, exportação ou lote). Anote quando ela começou.
2. Primeira sincronização com alterado_desde = essa data. Se a sua carga é anterior a registro.inicio, use registro.inicio — o que mudou entre as duas não está no registro.
3. Siga proximo_cursor até tem_mais ser false, e guarde o último cursor.
4. Nas próximas, só o cursor guardado: continua exatamente de onde parou, sem repetir nem pular, mesmo que uma comparação nova tenha sido publicada no meio.
5. Para cada chave, busque os dados no /lote do conjunto e grave por cima (upsert) — ou apague, em exclusao. A lista não cobra crédito; a ficha cobra, como sempre.

# 1. primeira vez: pela data
curl "https://evodata.app/api/v1/empresas/alteracoes?alterado_desde=2026-11-01T00:00:00Z&por_pagina=5000"

# 2. páginas seguintes, e toda sincronização depois: pelo cursor guardado
curl "https://evodata.app/api/v1/empresas/alteracoes?cursor=1843&por_pagina=5000"

# 3. os dados das chaves, até 100 por chamada
curl -X POST "https://evodata.app/api/v1/empresas/lote" -H "Authorization: Bearer evd_SUA_CHAVE" \
  -H "Content-Type: application/json" -d '{"cnpjs": ["00000000000191", "60701190000104"]}'

# pessoas: o mesmo, com a chave de API
curl -H "Authorization: Bearer evd_SUA_CHAVE" "https://evodata.app/api/v1/pessoas/alteracoes?alterado_desde=2026-11-01"

O laço inteiro, em Python

import requests

API = "https://evodata.app/api/v1"
H = {"Authorization": "Bearer evd_SUA_CHAVE"}

def sincronizar(cursor=None, desde="2026-11-01"):
    while True:
        q = {"cursor": cursor} if cursor else {"alterado_desde": desde}
        r = requests.get(f"{API}/empresas/alteracoes", params={**q, "por_pagina": 5000}, headers=H).json()
        apagar = [d["cnpj"] for d in r["dados"] if d["tipo"] == "exclusao"]
        buscar = [d["cnpj"] for d in r["dados"] if d["tipo"] != "exclusao"]
        for i in range(0, len(buscar), 100):
            lote = requests.post(f"{API}/empresas/lote", json={"cnpjs": buscar[i:i+100]}, headers=H).json()
            gravar([x for x in lote["resultados"] if "dados" in x])   # upsert na sua base
        remover(apagar)
        cursor = r["paginacao"]["proximo_cursor"]
        guardar_cursor(cursor)                                       # só depois de gravar a página
        if not r["paginacao"]["tem_mais"]:
            return cursor

Geolocalização por IP

País, estado, cidade e coordenadas aproximadas de um IPv4 ou IPv6, a partir do GeoLite2-City: 5,8 milhões de redes, atualizadas automaticamente a cada release. No Brasil a cidade vem com codigo_ibge, que liga o IP ao município do eDNE — de um IP se chega às faixas de CEP e aos bairros da cidade em /localidades.

Consultar um IP

GET https://evodata.app/api/v1/ips/{ip}

curl "https://evodata.app/api/v1/ips/177.52.140.1"

{
  "dados": {
    "ip": "177.52.140.1",
    "versao": 4,
    "rede": "177.52.140.0/22",
    "continente_codigo": "SA",
    "continente": "América do Sul",
    "pais_codigo": "BR",
    "pais": "Brasil",
    "pais_uniao_europeia": false,
    "pais_registro_codigo": "BR",
    "subdivisao_codigo": "MG",
    "subdivisao": "Minas Gerais",
    "cidade": "Sete Lagoas",
    "cidade_geoname_id": 3447624,
    "codigo_ibge": "3167202",
    "codigo_postal": "35700",
    "latitude": -19.4352,
    "longitude": -44.2815,
    "raio_precisao_km": 5,
    "fuso_horario": "America/Sao_Paulo",
    "anycast": false
  },
  "fonte": {
    "base": "GeoLite2-City",
    "release": "2026.09.25",
    "gerada_em": "2026-09-22T20:59:22+00:00",
    "atribuicao": "This product includes GeoLite2 Data created by MaxMind, available from https://www.maxmind.com."
  }
}

IPv4 escrito como IPv6 (::ffff:177.52.140.1) é consultado como IPv4. IP de rede privada ou reservada recebe 422 ip_reservado, e IP público fora das redes do GeoLite2, 404 nao_encontrado.

O IP de quem chama

GET https://evodata.app/api/v1/ips/meu

A mesma resposta, para o IP com que a requisição chegou. Útil no navegador, para pré-preencher estado e cidade num formulário.

Vários IPs

POST https://evodata.app/api/v1/ips/lote

curl -X POST "https://evodata.app/api/v1/ips/lote" \
  -H "Content-Type: application/json" \
  -d '{"ips": ["177.52.140.1", "2804:14c::1", "10.0.0.1", "abc"]}'

{
  "resultados": [
    { "ip": "177.52.140.1", "dados": { /* … */ } },
    { "ip": "2804:14c::1", "dados": { /* … */ } },
    { "ip": "10.0.0.1", "erro": "ip_reservado", "mensagem": "…" },
    { "ip": "abc", "erro": "ip_invalido", "mensagem": "…" }
  ],
  "resumo": { "total": 4, "sucesso": 2 },
  "fonte": { /* … */ }
}

Mapa e distâncias

Sobre o OpenStreetMap do Brasil, recarregado toda semana: 1,5 milhão de logradouros, 1,6 milhão de endereços com número, 800 mil pontos de interesse (comércio, serviços, saúde, educação, transporte) e os polígonos de município, distrito e bairro. Todo ponto pode ser dado como CEP ou como coordenada "lat,lon".

A ponte é o CEP: cada CEP do eDNE ganhou uma coordenada, e /ceps/{cep} passou a trazer o campo coordenadas. Como um CEP é uma rua ou um trecho dela — não uma porta —, a coordenada vem sempre com precisao e raio_m:

Distância e matriz

GET https://evodata.app/api/v1/distancia?origem=…&destino=…

curl "https://evodata.app/api/v1/distancia?origem=01310-100&destino=20040-002"

{
  "dados": {
    "origem": {
      "status": "ok", "entrada": "01310-100", "tipo": "cep", "cep": "01310100",
      "latitude": -23.5649616, "longitude": -46.6517717,
      "precisao": "numero", "raio_m": 517,
      "endereco": "Avenida Paulista, Bela Vista, São Paulo/SP", "codigo_ibge": "3550308"
    },
    "destino": { /* … Avenida Rio Branco, Centro, Rio de Janeiro/RJ */ },
    "km_linha_reta": 362.443,
    "incerteza_km": 0.559,
    "rumo_graus": 79
  },
  "fonte": {
    "base": "OpenStreetMap (extrato Brasil, Geofabrik)",
    "dados_de": "2026-10-07T20:20:35+00:00",
    "atribuicao": "© colaboradores do OpenStreetMap — dados sob a licença ODbL (openstreetmap.org/copyright)"
  }
}

POST https://evodata.app/api/v1/distancia/matriz

curl -X POST "https://evodata.app/api/v1/distancia/matriz" \
  -H "Content-Type: application/json" \
  -d '{"origens": ["01310100"], "destinos": ["20040002", "-15.7939,-47.8828"]}'

Até 100 origens × 100 destinos. distancias[i][j] é de origens[i] a destinos[j], ou null quando um dos dois não foi resolvido — cada ponto traz o próprio status.

Ponto → endereço

GET https://evodata.app/api/v1/mapa/reverso?lat=…&lon=…

curl "https://evodata.app/api/v1/mapa/reverso?lat=-23.5614&lon=-46.6559"

{
  "dados": {
    "municipio": { "nome": "São Paulo", "uf": "SP", "codigo_ibge": "3550308", "populacao": 11451999, "area_km2": 1531.22 },
    "distrito": "Bela Vista",
    "bairro": null,
    "endereco_mais_proximo": { "logradouro": "Av. Paulista", "numero": "1578", "cep": "01310200", "distancia_m": 13 },
    "cep_mais_proximo": { "cep": "01332040", "precisao": "logradouro", "distancia_m": 47,
                          "endereco": "Rua Professor Otávio Mendes, Bela Vista, São Paulo/SP" },
    "lugar_mais_proximo": { "tipo": "suburb", "nome": "Jardim Paulista", "distancia_m": 609 }
  }
}

Município, distrito e bairro vêm dos polígonos do OSM — bairro só onde a cidade tem os limites mapeados. O endereço mais próximo vale até 150 m e o CEP até 400 m; além disso o campo vem null, em vez de um palpite distante.

O que há perto

GET https://evodata.app/api/v1/mapa/proximos?cep=…&raio_km=…&categoria=…&tipo=…

curl "https://evodata.app/api/v1/mapa/proximos?cep=01310100&raio_km=0.5&tipo=pharmacy&limite=1"

{
  "dados": {
    "centro": { "cep": "01310100", "latitude": -23.5649616, "longitude": -46.6517717, /* … */ },
    "raio_km": 0.5,
    "pontos": [{
      "osm": "node/3621336511", "categoria": "amenity", "tipo": "pharmacy", "rotulo": "Farmácia",
      "nome": "Drogasil", "marca": "Drogasil", "cnpj": null,
      "telefone": "+55 11 3286-0114;+55 11 3253-2501", "site": "https://www.drogasil.com.br/",
      "horario": "Mo-Sa 07:00-23:00; Su 08:00-22:00",
      "endereco": { "logradouro": "Avenida Paulista", "numero": "995", "cep": "01311100", /* … */ },
      "latitude": -23.5654273, "longitude": -46.6520986, "distancia_m": 62
    }],
    "tem_mais": true
  }
}

O ponto de referência é lat+lon, ponto=lat,lon ou cep. Raio de até 50 km; até 200 itens, do mais perto ao mais longe. categoria: amenity, shop, healthcare, office, tourism, leisure, craft, public_transport, railway, aeroway, emergency, historic. tipo é o valor do OSM (pharmacy, supermarket, fuel, school, bank…).

GET https://evodata.app/api/v1/mapa/entorno?cep=…&raio_km=…

Contagem por tipo num raio de até 10 km — "quantas farmácias, escolas e pontos de ônibus há a 1 km deste CEP". É a pergunta de análise de ponto comercial, numa chamada.

Empresas num raio

GET https://evodata.app/api/v1/mapa/empresas?cep=…&raio_km=…&divisao_cnae=…

curl "https://evodata.app/api/v1/mapa/empresas?cep=01310100&raio_km=0.5&divisao_cnae=56&limite=1"

{
  "dados": {
    "centro": { "cep": "01310100", /* … */ },
    "raio_km": 0.5,
    "empresas": [{
      "cnpj": "…", "nome_exibicao": "…", "cnae": "Lanchonetes, casas de chá, de sucos e similares",
      /* os mesmos campos da busca de empresas */
      "distancia_m": 64,
      "ponto": { "latitude": -23.5653, "longitude": -46.6522, "precisao": "numero", "raio_m": 517 }
    }],
    "ceps_no_raio": 111, "ceps_consultados": 100, "tem_mais": true, "incompleto": false
  }
}

Estabelecimentos ativos da Receita perto do ponto, do mais perto ao mais longe. A Receita não publica onde fica a porta: a posição é a do ponto do CEP de cada empresa, e empresas do mesmo CEP aparecem à mesma distância. Por padrão só entram CEPs resolvidos até a rua (precisao_minima=rua). Filtros: cnae (7 dígitos), divisao_cnae (2 dígitos), nome, inclui_inativas. Raio de até 10 km, até 200 empresas.

Ao contrário do resto do mapa, esta rota consulta a base da Receita, e fica no limitador api — o mesmo de /empresas.

Endereço → ponto

GET https://evodata.app/api/v1/mapa/geocodificar?uf=…&cidade=…&logradouro=…&numero=…

curl "https://evodata.app/api/v1/mapa/geocodificar?uf=SP&cidade=São Paulo&logradouro=Av. Paulista&numero=1578"

{
  "dados": {
    "latitude": -23.5614968, "longitude": -46.6559649,
    "precisao": "numero", "raio_m": 15,
    "codigo_ibge": "3550308", "logradouro_encontrado": "Av. Paulista", "cep": null
  }
}

Do mais fino ao mais grosso: numero (o número existe no OSM), interpolado (entre os vizinhos de mesmo lado da rua), cep (o CEP seccionado que cobre o número), logradouro (o meio da rua, com homonimos quando há outra via de mesmo nome na cidade) e municipio (a sede).

Erros

Respostas de erro trazem erro, um código estável seguro para comparar em código, e quase sempre mensagem, texto em português voltado a quem lê — sujeito a mudar de redação. Compare pelo erro, nunca pela mensagem.

{
  "erro": "filtros_ausentes",
  "mensagem": "Informe ao menos um filtro. A base tem 72 milhões de estabelecimentos e uma consulta irrestrita não é atendida."
}

O 503 consulta_expirada merece tratamento próprio: ele não indica indisponibilidade, e sim que aquela combinação de filtros é ampla demais para o tempo limite do banco. Repetir a mesma chamada tende a falhar de novo — o caminho é acrescentar um recorte mais estreito, como UF ou município. Vale notar que a consulta expirada não fica em cache: se o cache do PostgreSQL esquentar por outra via, a mesma chamada pode passar depois.

Enumerações

uf

AC AL AP AM BA CE DF ES GO MA MT MS MG PA PB PR PE PI RJ RN RS RO RR SC SP SE TO EX

EX designa estabelecimento sediado no exterior.

Limitações conhecidas

Nem tudo que a interface web faz está exposto por HTTP. Vale conhecer as fronteiras antes de desenhar a integração.

• O CPF nunca sai em claro. Nenhum endpoint devolve o número completo — busca, ficha e vínculos trazem sempre a forma mascarada ***.XXX.XXX-**. A busca por CPF exige os 11 dígitos, de modo que a API confirme uma identidade que você já tem, em vez de permitir descobri-las.
• Não há exportação em massa. O teto é 100 itens por página, e a paginação profunda fica cara porque o banco precisa descartar tudo que veio antes. Para volumes grandes, use a exportação da interface, que percorre o conjunto por chave e não repete nem omite registros.
• Não há ordenação garantida. Qualquer valor de ordenar pode ser recusado em conjuntos grandes — a resposta continua 200, com a explicação em avisos. Um cliente que dependa de ordem precisa checar esse array.
• Não há webhooks: a mudança é puxada, não empurrada. O que mudou desde uma data sai em /alteracoes, mas só a partir de registro.inicio de cada conjunto, e como chaves — os dados vêm do /lote. Exclusão de CNPJ quase não aparece, porque a base não apaga empresa: a baixada vem como alteração.
• Respostas são cacheadas. Buscas e fichas passam por cache de curta duração. Duas chamadas idênticas em sequência podem devolver exatamente o mesmo corpo mesmo que a base tenha mudado no meio.