M
API Matrix

ViaCep API

⭐ Beginner's Pick Geocoding / No Auth Required Beginner HTTPS
Free to Use Varies (check documentation)
82 Score
Grade A
Visit Official Site Compare Alternatives

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 

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.

Matrix Score Breakdown

🌐 Reachability 30/30
⚡ Speed 15/20
🔒 Security 15/15
🛠 Developer XP 15/20
✓ Reliability 7/15
Response Time 202ms

Fully tested on Apr 5, 2026

Technical Specifications

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

Similar APIs

View All →

administrative-divisons-db

⭐ Beginner's Pick
92

The Administrative Divisions DB API provides a structured list of all administrative divisions (states, provinces, regions, cities) for countries around the world.

No Auth Beginner HTTPS 40ms

adresse.data.gouv.fr

0

adresse.data.gouv.fr provides programmatic access to address database of france, geocoding and reverse via REST API.

No Auth Beginner HTTPS 638ms

Airtel IP

⭐ Beginner's Pick
57

Airtel IP is a free, no-auth IP geolocation API that aggregates data from multiple sources to return the country associated with any given IP address.

No Auth Beginner HTTPS 146ms

bng2latlong

⭐ Beginner's Pick
57

bng2latlong is a simple, free API that converts British National Grid (OSGB36) easting and northing coordinates into standard WGS84 latitude and longitude.

No Auth Beginner HTTPS 389ms

Cartes.io

⭐ Beginner's Pick
87

Cartes.io is a free API that lets you create maps and add custom markers without signing up.

No Auth Beginner HTTPS 55ms