Brazil CEP Address Lookup - ViaCEP

Brazil CEP address lookup. Look up Brazilian postal codes you already have. ViaCEP JSON: street, district, city, UF, IBGE, DDD. No key. Punctuation ignored.

This Actor is a scheduled watchlist, not a one-shot dump. You bring identifiers you already have. It returns structured current fields, a change type against your previous snapshot, and a NEXT_SNAPSHOT you own.

Why pay

GET https://viacep.com.br/ws/{cep}/json/ (ViaCEP, no API key) is free. The paid job is bounded, scheduled, charge-after-success monitoring with isolated snapshots, honest nulls, and no fee for failed lookups or suppressed unchanged rows.

• charges per successful watchlist item, with no Actor-start fee
• does not bill source errors or onlyChanges unchanged rows
• does not invent scores, contacts, or matches beyond what the source returned

Not a geocoder. Not a street-to-CEP reverse search. Unknown CEPs are errors, not invented addresses.

What you get

{
  "schemaVersion": 1,
  "id": "01310100",
  "status": "ok",
  "cep": "01310-100",
  "street": "Avenida Paulista",
  "city": "São Paulo",
  "state": "SP",
  "ddd": "11",
  "changeType": "INITIAL",
  "error": null
}

Public example identifiers, not a customer or endorsement. Missing source strings are null — never "N/A".

Quick start

{
  "ceps": [
    "01310100"
  ],
  "maxItems": 1
}

Run it, open the dataset, and save NEXT_SNAPSHOT from the default key-value store.

Repeat workflow

1. Keep one watchlist per customer or project.
2. Start a bounded run. Schedule it yourself if you need a cadence.
3. Save the returned NEXT_SNAPSHOT JSON in your private state.
4. On the next run pass it as previousSnapshot and set onlyChanges: true.
5. Route changeType: CHANGED rows for review.

No schedules are enabled by default. Snapshots use the run's default storage, never a shared named store.

Input

Field	Type	Default	What it does
ceps	array	—	1–50 Brazilian CEP codes (8 digits).
maxItems	integer	50	Must cover all unique items; a smaller value is rejected rather than silently dropping IDs.
onlyChanges	boolean	false	Suppress unchanged successful records without charging them. The first observation is still emitted.
previousSnapshot	object	—	Prior NEXT_SNAPSHOT with schemaVersion: 1, kind: "brazil-cep", and a records map.

Pricing

Event	Price	When it happens
Successful watchlist result	$0.0015 ($1.5 / 1,000)	One successful watchlist item written to the dataset
Actor start	none	No custom start fee

You are not charged for: failed requests, parse failures, invalid input, or unchanged records suppressed by onlyChanges. With onlyChanges: false, an unchanged successful refresh is delivered work and is charged. The run stops when eventChargeLimitReached is true.

Worked example. 50 CEPs daily, onlyChanges: true, ~2 corrections/week → about 8 × $0.0015 = $0.012/month after the first full refresh.

Set maxTotalChargeUsd on the run. The Actor launches with a $1.00 minimum max-cost-per-run so a high-volume schedule cannot cap itself at the Console $0.05 default.

Using the API

Keep APIFY_TOKEN on a protected backend.

curl --fail -X POST "https://api.apify.com/v2/acts/technicaldost~brazil-cep-address-lookup/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"ceps":["01310100"],"maxItems":1}'

JavaScript

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('technicaldost/brazil-cep-address-lookup').call({
        "ceps": [
            "01310100"
        ],
        "maxItems": 1
    });
const { items } = await client.dataset(run.defaultDatasetId).listItems();

n8n. HTTP Request → POST https://api.apify.com/v2/acts/technicaldost~brazil-cep-address-lookup/runs with header Authorization: Bearer {{$credentials.apifyToken}}. Poll the run, then read the default dataset and NEXT_SNAPSHOT.

Limitations

• Public metadata only. No authentication bypass and no non-public personal data.
• Output is only as current as the official source. Lag and outages are reported as errors, not invented rows.
• One request at a time, 20 seconds per request.
• At most 1,000 snapshot records are retained; SUMMARY.snapshotPruned reports eviction.

Not affiliated with or endorsed by Correios or ViaCEP.

Changelog

See CHANGELOG.md. Release 1.0.0 (2026-09-14): caller-owned watchlists, isolated snapshots, $0.0015 per successful result, no start fee.