# Consulta CEP em Lote — Endereço por CEP (ViaCEP + BrasilAPI) (`gangary/consulta-cep-lote`) Actor

Consulte milhares de CEPs de uma vez e receba endereço completo: rua, bairro, cidade, UF, código IBGE e DDD. Multi-fonte com fallback automático (ViaCEP, BrasilAPI, OpenCEP) — se uma fonte cair, a próxima responde. Ideal para higienizar cadastros, logística e e-commerce.

- **URL**: https://apify.com/gangary/consulta-cep-lote.md
- **Developed by:** [Gangary](https://apify.com/gangary) (community)
- **Categories:** Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 per cep founds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

![consulta-cep-lote](https://empresas-por-cnae.vercel.app/covers/consulta-cep-lote.png)

## Consulta CEP em Lote — Endereço por CEP (ViaCEP + BrasilAPI)

Consulte **centenas ou milhares de CEPs de uma vez** e receba o endereço completo de cada um: logradouro, bairro, cidade, UF, código IBGE e DDD. Ideal pra higienizar cadastros de clientes, calcular frete por região, validar endereços em e-commerce e enriquecer bases de leads.

**Multi-fonte com fallback automático:** cada CEP é consultado no ViaCEP e, se a fonte estiver fora do ar ou não conhecer o CEP, o actor tenta BrasilAPI e OpenCEP na sequência. Você não fica refém de uma API só.

### O que você recebe

Exemplo real de saída (CEP 01001-000):

```json
{
  "input": "01001-000",
  "cep": "01001-000",
  "found": true,
  "street": "Praça da Sé",
  "complement": "lado ímpar",
  "neighborhood": "Sé",
  "city": "São Paulo",
  "state": "SP",
  "ibge": "3550308",
  "ddd": "11",
  "source": "viacep",
  "error": null
}
```

| Campo | O que é |
|---|---|
| `input` | O CEP exatamente como você enviou |
| `cep` | CEP normalizado (00000-000) |
| `found` | `true` se alguma fonte encontrou o endereço |
| `street` / `complement` / `neighborhood` | Logradouro, complemento e bairro |
| `city` / `state` | Cidade e UF |
| `ibge` | Código IBGE do município (útil pra integrações governamentais) |
| `ddd` | DDD da região (quando a fonte informa) |
| `source` | Qual fonte respondeu (viacep, brasilapi, opencep) |
| `error` | Motivo quando `found` é `false` |

CEPs mal digitados voltam com `error: "CEP invalido"` — nada é descartado silenciosamente. Duplicados são consultados uma vez só (você não paga duas vezes).

### Como usar

1. Cole sua lista de CEPs no campo **CEPs** (com ou sem hífen, tanto faz).
2. Rode o actor.
3. Baixe o dataset em CSV, JSON ou Excel — ou consuma via API.

Também funciona por API e por agendamento (ex.: higienização semanal do CRM).

### Quanto custa

Você paga por evento: uma taxa pequena de início + um valor por CEP **encontrado** (CEP inválido ou não encontrado não é cobrado).

| Cenário | Custo aproximado |
|---|---|
| 100 CEPs | ~US$ 0,10 |
| 1.000 CEPs | ~US$ 1,00 |
| 5.000 CEPs (máximo por run) | ~US$ 5,00 |

### Perguntas frequentes

**É legal consultar CEPs assim?**
Sim. Os dados de CEP são informação pública de endereçamento, servidos por APIs públicas (ViaCEP, BrasilAPI, OpenCEP). O actor não acessa nenhum dado pessoal.

**O que acontece se uma das fontes estiver fora do ar?**
O fallback é automático: a próxima fonte da fila responde. Só quando todas falham o CEP volta com `error: "fontes indisponiveis"` — e nesse caso você não paga por ele.

**Tem limite?**
Até 5.000 CEPs por execução. Precisa de mais? Rode em lotes ou agende execuções.

### Limitações honestas

- CEPs de grandes clientes corporativos (caixa postal própria) às vezes não têm logradouro — o registro vem com os campos que a fonte tiver.
- O DDD só vem quando a fonte que respondeu informa (ViaCEP informa; as demais não).

### From the same maker

- **[Consulta CNPJ (dados de empresas)](https://apify.com/gangary/cnpj-lookup)** — razão social, CNAE, situação e sócios por CNPJ.
- **[B2B Leads Brazil](https://apify.com/gangary/b2b-leads-brazil)** — leads B2B brasileiros prontos: descoberta + dados cadastrais + score, num actor só.
- **[Tabela FIPE](https://apify.com/gangary/tabela-fipe)** — preço de carros, motos e caminhões em lote.
- **[Empresas novas do Brasil](https://apify.com/gangary/new-brazilian-companies)** — empresas abertas nos últimos dias, por CNAE e UF.

***

*Palavras-chave: consulta CEP, CEP em lote, buscar endereço por CEP, API CEP, ViaCEP em lote, validar CEP, código IBGE por CEP, DDD por CEP, higienização de cadastro, frete por CEP.*

# Actor input Schema

## `ceps` (type: `array`):

Lista de CEPs (com ou sem hífen). Duplicados são removidos automaticamente.

## Actor input object example

```json
{
  "ceps": [
    "01001-000",
    "20040-020"
  ]
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "ceps": [
        "01001-000",
        "20040-020"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("gangary/consulta-cep-lote").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "ceps": [
        "01001-000",
        "20040-020",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("gangary/consulta-cep-lote").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "ceps": [
    "01001-000",
    "20040-020"
  ]
}' |
apify call gangary/consulta-cep-lote --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,gangary/consulta-cep-lote"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/ZN5CeoBaPxYWe8a7o/builds/RUsCh57VTKufgJmW6/openapi.json