Skip to content
Get packs

Guide · Open source

How to use BrasilAPI: CEP lookups and public Brazilian data

Updated · written with AI from the project's own documentation and checked against our catalogue data

BrasilAPI is an open-source project that collects publicly available Brazilian information, such as postal codes (CEP), and serves it through simple web endpoints. It is aimed at developers building Brazilian websites or apps who want public data without integrating each government or public source separately. This guide explains what it is, how to call it from the web, and the usage rules you need to respect before relying on it.

BrasilAPIBrasilAPI/BrasilAPI · ★ 11.4k · MIT

Quick start

  1. 1Read the limits. Read the README's usage rules first. Plan for normal, person-like request volumes and no automated crawling.
  2. 2Open the documentation. Go to brasilapi.com.br/docs to find the OpenAPI description of the available endpoints.
  3. 3Pick the endpoint you need. Choose the endpoint that matches your data, such as CEP lookup for postal codes.
  4. 4Make a single request from your app. Call the endpoint from your website or app. The README notes that this is the reason the project exists, since the Correios API cannot be called directly from a browser.
  5. 5Handle the response in your code. Build your code to handle responses and errors, since the project is in beta and uptime is not guaranteed.
  6. 6Ask in the issues if something is missing. If a data source or endpoint you need is not available, raise it in the project's issues.

What BrasilAPI is and why it exists

The README explains that some public information, such as a CEP (Brazilian postal code), cannot be called directly from a browser because the Correios postal API does not have CORS enabled. BrasilAPI sits in between and exposes that data through endpoints a browser can reach.

The project also uses caching. The README says it relies on Vercel Smart CDN to cache responses in regions around the world, so slow upstream sources are still served as quickly as possible.

Check the documentation before you call an endpoint

The project publishes an OpenAPI documentation page at brasilapi.com.br/docs. Use it to find the exact endpoints and the details of each integration, since the README itself does not list them.

The project homepage is https://brasilapi.com.br.

Use the rules that apply to every request

BrasilAPI is in beta and the README says its terms of use are still being written. Until they are published, the maintainers ask users not to use automated methods to crawl the API.

The README gives an example of the volume it does not want: a large telecom provider validated every CEP from 00000000 to 99999999 and exceeded the project's current server limit by about five times. The maintainers say request volume should look like a real person asking for a given piece of data. They plan a bulk download option later, but the README does not describe it yet.

  • Make requests that resemble one person looking up a specific record.
  • Do not loop through ranges of CEPs or other records.
  • If you need high-volume data, wait for the bulk option the maintainers mention, or contact them through the project's issues.

Find help and contribute through the issues

The project is at an early stage and many questions are still open. The README asks contributors to use the project's issues to see which points are unresolved, discuss them with the maintainers, and suggest technical ideas or which APIs should be created.

For contribution details, the README points to CONTRIBUTING.md in the repository.

Use community client libraries

The README lists community-made integrations for several languages, including Go, JavaScript, Flutter, Swift, .NET, PHP, Python, Ruby, Rust, Java, Delphi and V. These are maintained by their individual authors, not by the BrasilAPI maintainers, so check each one before depending on it.

  • JS: brasil-api-promisse and brasilapi-js
  • Python: brasilapy and brasilapi-python
  • PHP: brasilapi-php (two versions listed)

What people use it for

  • Filling in address fields on a Brazilian checkout form from a CEP
  • Validating a postal code entered by a user on a website
  • Building a Brazilian app that needs public data from one API instead of several sources
  • Prototyping a Brazilian-data feature with a community client library in your language

Frequently asked questions

Is BrasilAPI free to use?

The project is released under the MIT licence, according to its repository information. The README does not describe pricing, but it does say the terms of use are still being written, so check the homepage for current terms.

What is BrasilAPI used for?

It serves publicly available Brazilian information, such as CEP postal codes, through simple web endpoints. It is mainly useful to developers building Brazilian websites or apps that need this kind of data.

Why can't I call the Correios API directly from my browser?

According to the README, the Correios postal API does not have CORS enabled, so a browser cannot call it directly. BrasilAPI is meant to provide that data through endpoints a browser can access.

Can I download the whole CEP database with BrasilAPI?

The README says a bulk download option is planned for later, where the whole CEP base could be downloaded in one request. It does not say when this will be available.

Can I use BrasilAPI for heavy automated data collection?

No, the README asks users not to crawl the API and not to use automated methods for high-volume extraction. It says request volume should resemble a real person looking up specific data.

Is BrasilAPI production-ready?

The README describes the project as experimental and in beta, at an early stage. It does not guarantee uptime or formal terms, so teams that need reliability should plan fallbacks.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

BrasilAPI suits developers building Brazilian websites or apps who need CEP or other public Brazilian data through a single API, and contributors who want to help shape new endpoints. It is a poor fit for high-volume data extraction or for anyone who needs guaranteed uptime and formal terms of service, since the project says it is still in beta.

Install options & downloads