# BrasilAPI: A Unified Public REST API for Brazilian Data

> BrasilAPI is a free, MIT-licensed public REST API that consolidates Brazilian government and public data behind a single consistent interface, built on Next.js and deployed via Vercel. It is aimed at developers who need access to Brazilian data such as CEP postal codes without maintaining separate integrations for each official source.

**BrasilAPI/BrasilAPI** — Vamos transformar o Brasil em uma API?

- Repository: https://github.com/BrasilAPI/BrasilAPI
- Website: https://brasilapi.com.br
- Stars: 11,211 · Forks: 775
- Language: JavaScript
- License: MIT
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/brasilapi-brasilapi

## What BrasilAPI Provides and Who It Targets

Brazil has numerous government databases, official registries, and public data sources, each with its own access method. Developers who need postal code lookups, company registration data, or other official Brazilian data have historically had to integrate each source separately, dealing with differing API shapes, authentication requirements, and reliability levels.

BrasilAPI addresses this by exposing a single REST API at brasilapi.com.br that unifies access to these sources. The project description frames this as a mission: transforming Brazil into an API. The practical implication is that a developer building a Brazilian address form, a company onboarding flow, or a financial application can call one consistent API rather than maintaining separate integrations for different official sources.

The target audience is developers building web and mobile applications for the Brazilian market. The MIT license permits commercial use, so both startups and established companies can call the public API or host their own instance. The package.json in the repository shows the project requires Node.js 24.x and npm 10+, which defines the minimum runtime for self-hosting.

The related searches for BrasilAPI include queries specifically about CEP, CNPJ, and CPF lookups, which are common needs in Brazilian financial and logistics applications. CEP is the Brazilian postal code system, CNPJ is the company registration number used in tax and invoicing contexts, and CPF is the individual taxpayer identification number.

## Architecture: Next.js API Routes on Vercel

BrasilAPI is built on Next.js, with the API endpoints implemented as Next.js API routes. This means each endpoint is a serverless function, deployed via Vercel as shown by the vercel.json configuration file in the repository root. The next.config.js configures the application behavior, and the pages/ directory structure typical of Next.js applications holds both the web front end and the API route handlers.

The cep-promise package (version 4.4.1) is a direct dependency listed in package.json, confirming that CEP postal code lookup is implemented using this library. cep-promise queries multiple CEP data sources in parallel and returns the first successful response, which is a reliability pattern: if one source is slow or unavailable, the lookup still completes from another source.

Other dependencies in package.json reveal further API categories. The wikijs package (version 6.4.0) is a Wikipedia API client, suggesting some endpoints pull from Wikipedia data. The selic package (version 1.1.0) suggests SELIC rate data (Brazil's base interest rate) is available. The fast-xml-parser package handles XML responses from government sources that still use XML formats.

The next-connect package handles middleware composition for API routes, and joi (version 17.8.3) handles request validation. The piscina package (version 3.2.0) is a Node.js worker thread pool library, indicating that some API operations are parallelized across worker threads for performance.

On the front end, the project uses React 17, styled-components, and redoc for API documentation rendering. The @djpfs/react-vlibras package is a Brazilian sign language accessibility widget, showing the project addresses accessibility requirements for government-facing applications.

## Running BrasilAPI Locally for Development

BrasilAPI follows a standard Next.js development workflow. Clone the repository and install dependencies:

```bash
npm install
```

Start the development server:

```bash
npm run dev
```

The dev script runs the next command, which starts the Next.js development server. API routes become available locally, and the front-end documentation page loads in the browser.

The repository includes a .nvmrc file, which specifies the exact Node.js version for the project. Using nvm with this file ensures the local Node.js version matches the documented requirement of Node.js 24.x.

The .husky/ directory contains Git hooks configured with Husky, and lint-staged is listed as a dev dependency. This means commit-time linting runs automatically, enforcing ESLint rules defined in .eslintrc.js before code can be committed. The eslint-config-airbnb configuration is the style basis, combined with prettier (version 2.8.0) for formatting.

Testing uses Vitest (version 3.0.8) with @vitest/coverage-istanbul for coverage reporting. The vite.config.js configures the test runner. Tests live in the tests/ directory. The scripts section of package.json shows the test runner is invoked with the standard test script name.

For contributors adding a new endpoint, the .github/ directory contains copilot-instructions.md with the project's development guidelines, a PR template in PULL_REQUEST_TEMPLATE.md, and code review guidelines. New endpoints follow the pattern established in the existing pages/api/ directory.

## Endpoint Coverage: CEP, CNPJ, and Other Brazilian Data

The cep-promise dependency confirms CEP postal code lookup is a core feature. CEP codes in Brazil identify specific streets or postal zones, and address forms across Brazilian commerce rely on real-time CEP lookup to auto-populate city, state, and street information. The parallel-query pattern in cep-promise means the endpoint is more reliable than calling any single official CEP source directly.

The selic package dependency confirms exposure of Brazil's SELIC interest rate, which banks, financial applications, and accounting tools need for interest calculations. SELIC is set by the Central Bank of Brazil and changes periodically.

The wikijs dependency indicates at least one endpoint pulls data from Portuguese-language Wikipedia. The related searches for BrasilAPI include CNPJ queries, and company registration lookups typically draw from Receita Federal (Brazil's federal revenue service) data.

The package.json lists tz-lookup (version 6.1.25) as a dependency, suggesting timezone data for Brazilian locations is an available endpoint. Brazil has four time zones, and applications displaying local times for Brazilian cities need this data.

The project homepage at brasilapi.com.br serves the documentation, rendered with redoc (version 2.0.0) from OpenAPI specification data. Developers can browse the full endpoint list there. The documentation source lives in the docs/ directory of the repository.

All endpoints are read-only. BrasilAPI is a query layer on top of public data sources; it does not provide any write operations to underlying government systems. This is an important boundary: you can look up a CEP or CNPJ but you cannot submit or modify government records through BrasilAPI.

## Limitations and Data Accuracy Constraints

BrasilAPI's data is only as current as the sources it queries. For CEP data, cep-promise queries several sources, which helps with availability but does not guarantee the data reflects the most recent postal zone changes from Correios (Brazil's postal service). New CEP codes or changed boundaries may lag behind the official update.

The project has no published versioned releases on GitHub. The main branch is what is deployed to the public API. This means breaking changes to endpoint behavior or response schemas can reach production without a version increment. Applications that depend on specific response formats should monitor the repository's commit history or pin to a specific git commit when self-hosting.

Runtime errors or data source outages on the upstream services (government websites, Receita Federal systems, Correios) directly affect BrasilAPI endpoint availability. When an upstream source is slow or returning errors, the corresponding BrasilAPI endpoint returns errors. The cep-promise approach mitigates this for CEP by querying multiple sources, but endpoints backed by a single upstream source have no such fallback.

The README available in the repository is the .github/ documentation README describing the contribution and code review workflow, not the end-user API documentation. For endpoint documentation and usage examples, developers need to visit brasilapi.com.br or read the docs/ directory.

The project targets the Brazilian market specifically. Developers building applications for other countries will find the endpoints are not applicable. There is no generalization layer for non-Brazilian postal codes, tax identifiers, or government data.

## BrasilAPI vs ViaCEP: Scope and Single-Endpoint Difference

ViaCEP is the most direct single-feature comparison for BrasilAPI's CEP endpoint. ViaCEP is a free public API that serves only CEP lookups, with a simple REST interface and no authentication required. Many Brazilian applications use ViaCEP for postal code lookups exclusively.

The difference is scope. ViaCEP does one thing: it returns address data for a given CEP code. BrasilAPI covers CEP lookup as one of many endpoints, alongside CNPJ, SELIC rate, timezone data, and more. For a project that only needs CEP lookup, ViaCEP is a simpler dependency with no additional surface area. For a project that needs multiple types of Brazilian data, BrasilAPI reduces the number of API integrations to maintain.

cep-promise itself, which BrasilAPI uses internally, is another comparison point. cep-promise is a Node.js library that queries multiple CEP providers (including ViaCEP) in parallel. Developers who control their server-side code could use cep-promise directly rather than calling BrasilAPI, which removes an external HTTP dependency. BrasilAPI is most useful for front-end applications or mobile apps where installing and running a Node.js library directly is not an option.

Infosimples is a paid data enrichment service for Brazilian data. It covers more data types with contractual SLAs and higher rate limits than BrasilAPI's free public tier. For high-volume production use where rate limits or data freshness matter commercially, a paid service is the more appropriate choice.

## Maintenance, Contribution Process, and MIT License

The main branch received its last push on 2026-09-25, indicating the project is actively maintained as of that date. The repository has no GitHub releases, so the current main branch deployment is the production version of the public API.

The contribution process uses commitizen and cz-conventional-changelog (both listed as dev dependencies) to enforce conventional commit message formatting. The .husky/ hooks run lint-staged on commit, and the PR template in .github/PULL_REQUEST_TEMPLATE.md defines a checklist that contributors follow before submitting. GitHub Copilot instructions in .github/ guide automated PR review.

The CODE_OF_CONDUCT.md and CONTRIBUTING.md set behavioral expectations for the community. The GOOD_PRACTICES.md file suggests the project has documented internal coding standards beyond what ESLint enforces automatically.

The MIT license means the codebase is freely reusable. Organizations can fork the repository, add private endpoints for internal data sources, and deploy to their own Vercel account without publishing the changes. The Vercel-native deployment through vercel.json means a fork can be live with a single Vercel deployment, pointing to the forked repository.

The @djpfs/react-vlibras dependency adds a Brazilian sign language (Libras) accessibility widget to the documentation site. This reflects Brazilian accessibility requirements (Lei Brasileira de Inclusão, Article 63) for digital public services. The inclusion of this in the public documentation site rather than just in the package demonstrates attention to the accessibility context of the Brazilian public sector audience the project serves.

## Conclusion

BrasilAPI is a practical tool for developers building applications that require Brazilian government and public data. The zero-cost access and MIT license make it straightforward to use in open-source and commercial projects alike. Before using it in a production application, verify that the specific endpoints your application depends on are stable, since the project has no versioned releases. The last push to main was on 2026-09-25, indicating active maintenance. Teams running production workloads that cannot tolerate endpoint downtime should consider running their own instance by cloning the repository and deploying it on their own Vercel account, which the MIT license and the Next.js codebase support without restriction.

## FAQ

### What does CEP mean in a Brazilian address?

CEP stands for Codigo de Enderecamento Postal, Brazil's postal code system maintained by Correios. BrasilAPI exposes a CEP lookup endpoint backed by the cep-promise library, which queries multiple CEP data sources in parallel for reliability.

### What types of Brazilian data does BrasilAPI expose?

Based on the package.json dependencies, BrasilAPI covers at least CEP postal code lookup (via cep-promise), SELIC interest rate data (via the selic package), timezone information for Brazilian locations (via tz-lookup), and data from Wikipedia. The full endpoint list is documented at brasilapi.com.br.

### Can BrasilAPI be self-hosted?

Yes. The repository is MIT-licensed and built on Next.js with a vercel.json configuration, so it can be deployed to any Vercel account or any hosting environment that runs Node.js 24.x applications. Cloning the repository and running npm install followed by npm run dev starts the API locally.

## Sources

- [BrasilAPI/BrasilAPI on GitHub](https://github.com/BrasilAPI/BrasilAPI)
- [Issues](https://github.com/BrasilAPI/BrasilAPI/issues)
- [License: MIT](https://github.com/BrasilAPI/BrasilAPI/blob/main/LICENSE)
- [Project website](https://brasilapi.com.br)
- [README](https://github.com/BrasilAPI/BrasilAPI/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/brasilapi-brasilapi