ViaCep API

Beginner's Pick Geocoding / No Auth Required Beginner HTTPS
Free to Use Varies (check documentation)

Overview

ViaCep is a free Brazilian zip code (CEP) API that returns address data including street, neighborhood, city, and state for any valid Brazilian postal code. No authentication is required, making it ideal for beginners building forms or address validation for Brazil. Responses are available in JSON or XML format.

Beginner Tip

Just replace the CEP in the URL with any valid 8-digit Brazilian zip code. Use the JSON format endpoint (/json/) for easiest parsing in modern apps.

Available Data

IP address information
geographic location
ASN and ISP data
Use case: Integrate brazil restful zip codes api data into web and mobile applications

Example Response

JSON Response
{
  "status": "success",
  "data": {
    "result": "Data from ViaCep",
    "description": "Brazil RESTful zip codes API",
    "timestamp": "2025-01-15T10:00:00Z"
  }
}

Field Reference

cep The Brazilian postal code in XXXXX-XXX format.
logradouro Street name associated with the postal code.
bairro Neighborhood or district name.
localidade City name for the postal code.
uf Two-letter Brazilian state abbreviation, e.g. SP for São Paulo.
ibge IBGE code, a numeric identifier for the municipality.

Implementation Example

Request
const url = "https://viacep.com.br/";
const response = await fetch(url);
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const data = await response.json();
console.log(data);

What Can You Build?

Note: These code examples are AI-generated and unverified. Always refer to the official API documentation for accurate usage.

Common Errors & Troubleshooting

400 Bad Request The CEP contains non-numeric characters or is not 8 digits long.
Strip dashes and spaces from the CEP before passing it to the URL. Only digits, optionally with a hyphen (XXXXX-XXX), are accepted.
erro: true in response The CEP number is syntactically valid but does not exist in the database.
Check the CEP on a postal directory and confirm it is a real Brazilian zip code.
Empty or timeout response Network issue or the API is temporarily unavailable.
ViaCep is free and has no SLA; implement retry logic with exponential backoff for production use.

Metadata Score Breakdown

Estimated from metadata — endpoint not independently tested

This score is estimated from observable metadata — HTTPS support, authentication model, declared CORS, and documentation reachability — because the API requires authentication or exposes no publicly testable endpoint. The five-signal breakdown is only shown for live-tested APIs.

Metadata estimate · endpoint not independently tested

Technical Specifications

Auth No Auth
HTTPS REQUIRED
CORS UNKNOWN
Category Geocoding
Difficulty Beginner
Verified: 2026-04-04

Related Tags

Similar APIs

View All →