ViaCEP API
Free ViaCEP API with no key: resolve any Brazilian CEP to street, neighbourhood, city, state, IBGE code and area code, or search by address. Tested example included.
Endpoint tested and returned HTTP 200 on 2026-08-21
What is the ViaCEP API?
ViaCEP is a free, key-free API that resolves Brazilian postcodes (CEPs) to a full address: street, neighbourhood, city, state, region, IBGE municipality code and telephone area code. It also works in reverse, searching for CEPs by state, city and street name.
Almost every Brazilian checkout form works the same way: the customer types eight digits, the address fills itself in, and the only fields left are the house number and the flat. ViaCEP is what a large share of those forms call. It has been running since 2014, needs no key, and answers fast enough to fire on the blur event of an input.
The reverse search is the half people forget. Hitting `/ws/{UF}/{cidade}/{rua}/json/` returns every CEP matching a street name in a city, which is how you handle a customer who knows their address but not their postcode. Two constraints apply: the street fragment must be at least three characters, and the result set is capped, so a search for "Rua" in São Paulo will silently give you a truncated list rather than an error.
Quick facts
- Base URL
https://viacep.com.br/ws- Authentication
- No key or account. The service is free for personal and commercial use; the operator asks only that you do not hammer it.
- Rate limit
- No published numeric limit. Sustained bulk querying from one IP gets blocked, so cache aggressively — CEP data changes rarely.
- Pricing
- Free.
- CORS
- Enabled — callable directly from browser JavaScript
- Official docs
- Read the docs
How to use the ViaCEP API
Every request below was executed against the live API on 2026-08-21, and the response shown is the real body it returned — not an illustration.
1. Look up a Brazilian address by CEP
GET https://viacep.com.br/ws/01001000/json/
curl 'https://viacep.com.br/ws/01001000/json/'const res = await fetch("https://viacep.com.br/ws/01001000/json/");
if (!res.ok) throw new Error(`Request failed: ${res.status}`);
const data = await res.json();
console.log(data);import requests
res = requests.get("https://viacep.com.br/ws/01001000/json/", timeout=20)
res.raise_for_status()
print(res.json()){
"cep": "01001-000",
"logradouro": "Praça da Sé",
"complemento": "lado ímpar",
"unidade": "",
"bairro": "Sé",
"localidade": "São Paulo",
"uf": "SP",
"estado": "São Paulo",
"regiao": "Sudeste",
"ibge": "3550308",
"gia": "1004",
"ddd": "11",
"siafi": "7107"
}Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
cep | path | Required | Eight-digit CEP, with or without the hyphen. Sent as `/ws/{cep}/json/`. 01001000 |
format | path | Required | Response format segment: `json`, `xml`, `piped` or `querty`. json |
uf | path | Optional | For reverse search: two-letter state code, as `/ws/{uf}/{city}/{street}/json/`. SP |
cidade | path | Optional | City name for reverse search. Accents may be omitted. Sao Paulo |
logradouro | path | Optional | Street name fragment for reverse search. Minimum three characters. Praca da Se |
(callback) | query | Optional | Appending `?callback=fn` returns JSONP, for legacy pages without CORS support. fn |
Response fields
cepstring- The CEP, normalised with a hyphen — "01001-000" even if you sent it without one.
logradourostring- Street name. Empty for CEPs that cover a whole town rather than a single street.
complementostring- Range qualifier such as "lado ímpar" (odd-numbered side). Often empty.
bairrostring- Neighbourhood.
localidadestring- City name.
ufstring- Two-letter state code.
estado / regiaostring- Full state name and macro-region, for example "São Paulo" and "Sudeste".
ibgestring- IBGE municipality code — the identifier to use when joining to Brazilian statistical datasets.
dddstring- Telephone area code for the locality, useful for validating phone numbers against an address.
gia / siafistring- Tax and federal administrative codes, relevant mainly for invoicing systems.
What you can build with the ViaCEP API
- Auto-fill a Brazilian address from a CEP at checkout
- Validate that a CEP and city entered by a customer agree
- Find a CEP from a street name when the customer does not know it
- Join address data to IBGE statistics using the municipality code
- Pre-fill or sanity-check a telephone area code from the delivery address
Common errors and how to fix them
`{"erro": "true"}` with HTTP 200
The CEP is well formed but does not exist.
Fix: Check for the `erro` key rather than the status code. ViaCEP answers 200 for a valid-format, non-existent CEP.
400 Bad Request
The CEP is not eight digits, or the street fragment is under three characters.
Fix: Strip everything but digits before sending, and require at least three characters in the street field of a reverse search.
Reverse search returns a truncated list
The result set is capped server-side.
Fix: Narrow the street fragment. A search that matches thousands of streets returns a partial list with no warning that it was cut.
Requests start failing after a burst
Sustained high-volume querying triggers a block.
Fix: Cache results indefinitely — CEP records are near-static — and add a short delay between calls when bulk-enriching a database.
ViaCEP API — frequently asked questions
Is the ViaCEP API free?
Yes, free with no key or registration, for personal and commercial use alike. The only expectation is reasonable request volume, since it is run as a public service rather than a funded product.
How do I find a CEP if I only know the street?
Use the reverse search path `/ws/{UF}/{city}/{street}/json/`. It returns every matching CEP for that street in that city; the street fragment must be at least three characters long.
Why does a valid CEP return an error object?
ViaCEP distinguishes malformed input, which returns HTTP 400, from a correctly formatted CEP that is not in the register, which returns HTTP 200 with `{"erro": "true"}`. Check for that key explicitly.
What is the ibge field used for?
It is the official IBGE municipality code. Brazilian statistical, electoral and health datasets are keyed on it, so it is the reliable way to join an address to public data — city names are not, because of spelling and accent variation.
Tools that pair with this API
JSON Formatter
Format, beautify and minify JSON online with 2-space, 4-space or tab indentation. Sort keys alphabetically and catch syntax errors instantly — free and private.
XML to JSON Converter
Convert XML to JSON online. Elements become objects, attributes are prefixed with @, text is preserved, and parse errors are reported clearly — in-browser.
CSV to JSON Converter
Convert CSV to a JSON array of objects online. Header-row detection, comma/semicolon/tab delimiters and pretty-printed output — 100% in your browser.
ViaCEP is an independent third-party service and is not affiliated with ByteTools or ByteVancer. Details on this page were verified on 2026-08-21; always check the official documentation before relying on this API in production, as terms and limits can change.