BrasilAPI: a self-hosted Next.js gateway to Brazilian public data

The gap BrasilAPI fills: Brazilian public records without a vendor contract

Brazilian public data is scattered across federal, state and municipal sources. The README gives one concrete motivation: the Correios CEP API does not enable CORS, so a browser cannot call it directly. BrasilAPI centralises such lookups behind modern HTTP endpoints cached by Vercel Smart CDN. The project describes itself in package.json as "Vamos transformar o Brasil em uma API?", which is the whole thesis: turn the country's public records into endpoints.

The audience is Brazilian developers building checkout forms, onboarding flows, invoice validators or internal dashboards who do not want to sign a contract with a data broker for every field. The MIT licence removes the usual procurement conversation. Because the code is a Next.js application rather than a hosted-only service, a team can run it on its own infrastructure and keep the request path inside its own network.

The repository also carries a contributor process: CONTRIBUTING.md, CODE_OF_CONDUCT.md and GOOD_PRACTICES.md sit at the root. The README calls it an experimental project in beta and asks contributors to use the issues to discuss open points and which APIs could be created.

How the Next.js app and its service layer fit together

The repository layout is a Next.js project. app.js, next.config.js, pages/, components/, styles/ and public/ are the web application. The data work sits in services/, lib/, util/, middlewares/ and errors/. The pages directory is what maps a URL path to a handler, so the public endpoint surface is defined there rather than in a separate router file.

The dependency list shows how the data is fetched and shaped. axios handles outbound HTTP. cep-promise, a dedicated CEP client, is pinned at 4.4.1. fast-xml-parser is present, which means at least some upstream sources return XML and are parsed in-process. papaparse handles CSV, so some datasets are ingested as delimited files. piscina, a worker pool, appears in dependencies, which points to CPU-bound work being pushed off the request thread. tz-lookup and dayjs cover timezone and date handling, and joi plus zod both appear, so validation is done with more than one library depending on the code path.

The runtime is pinned tightly. package.json declares engines for npm >=10 and node 24.x, and .nvmrc is tracked at the repository root. Next.js is on ^12.3.4 while React is on ^17.0.2, which is an older pairing than current Next.js releases. Vite 6.2.2 is in dependencies and vite.config.js is at the root, alongside a Vitest 3.0.8 test setup. That mix of a Next.js app and a Vite config is worth reading before you assume a single build pipeline.

The errors/ directory suggests error responses are centralised rather than written ad hoc in each handler.

Running BrasilAPI locally and hitting your first endpoint

The repository does not ship a step-by-step install section in the root README. What it does give you is the runtime contract in package.json and the scripts block. Node 24.x and npm 10 or newer are required, so check those before anything else.

npm install
npm run dev

The engines field in package.json expects node 24.x and npm >=10, and the dev script is mapped to next, so this starts the Next.js development server. If your machine reports a different major Node version, switch before installing. Read the port from the terminal output.

Once the server is up, the endpoints you want are the ones described in the project's OpenAPI documentation at brasilapi.com.br/docs. The README does not enumerate endpoint paths, so read that documentation to get the exact route before you build a client against it.

Where BrasilAPI is the wrong tool

The README is a short project overview: motivation, a link to the OpenAPI documentation, a contributing section, usage terms and a list of community libraries, rather than operating instructions. It says the project is in beta and the Termos de Uso are still being written. That is a real limitation for anyone evaluating it as infrastructure: there is no documented rollback procedure, no stated uptime target and no published rate limit.

Upstream dependency is the second constraint. axios, cep-promise, fast-xml-parser and papaparse all exist because BrasilAPI does not own the data. It reads from sources it does not control. When a source changes its response format or goes down, the failure surfaces in your application. The services/ and errors/ directories are where that is handled, but handling it is not the same as eliminating it.

The runtime pin is the third. Node 24.x with npm >=10 is not a wide compatibility window, and Next.js ^12.3.4 with React ^17.0.2 is a stack that has moved on. If your platform of choice only offers an older Node LTS, you are either upgrading the runtime or patching the dependency set yourself.

Finally, if you need a contractual guarantee, a support channel with response times, or an audit trail for the data you consume, a self-hosted MIT project is the wrong shape. BrasilAPI gives you the code and the endpoints. It does not give you a vendor.

BrasilAPI against CepAberto, ViaCEP and Infosimples

The alternatives split into two groups, and the difference is architectural rather than cosmetic.

ViaCEP and CepAberto are single-purpose address services. They answer CEP lookups. If a CEP is all you need, a single-purpose service is a smaller dependency: one endpoint, one response shape, nothing else in the request path. BrasilAPI's stated aim is to centralise and serve modern endpoints for Brazilian public data, with CEP as the example its README gives, so more than one lookup can sit behind one host.

Infosimples is a commercial data provider. The difference there is who carries the operational burden. A commercial provider owns the upstream integrations, the retries and the schema changes, and charges for that. BrasilAPI hands you the integration code under MIT and lets you run it. You trade a line item on an invoice for the work of keeping the service alive.

The honest comparison is this: pick a single-purpose service when your need is a single field and you want the smallest possible surface. Pick a commercial provider when you cannot staff the operational side. Pick BrasilAPI when you want several Brazilian datasets behind one interface and you are willing to run the Node process yourself.

Maintenance, licence and the cost of keeping it current

The repository is not archived and the last push was on 2026-11-02, so the codebase is being touched. That is a statement about activity, not about support commitments. The repository has no published GitHub releases, which means there is no versioned artifact to pin against; you would be tracking the main branch.

Tracking main has a cost. Nothing in source marks which commits are stable. Pin a commit in your deployment and review the diff before moving it.

The licence is MIT. In practical terms that permits commercial use, modification and redistribution with the licence text retained. It is a permissive licence, not a copyleft one, so it does not obligate you to publish your own changes. This is a description of the licence identifier, not legal advice; if your organisation has rules about third-party code, route the LICENSE file through whoever handles that.

The ongoing cost is the upstream integrations. Each dependency that talks to a public source (cep-promise, axios calls, the XML and CSV parsers) is a place where an external change can break your deployment. Budget for reading the diff when you bump the pinned commit, and for the possibility that a source changes shape between your bumps.

Editorial conclusion

Adopt BrasilAPI if you need Brazilian reference data (CEP lookups, for example) behind your own domain and you can run Node 24 with npm 10 or newer. Do not adopt it if you need a vendor SLA, a documented rollback path, or an operations runbook, because the README is a short project overview and the OpenAPI documentation at brasilapi.com.br/docs is the place to check for endpoint-level detail. Before you commit, verify the app boots with npm run dev under Node 24, confirm the endpoint you depend on in the OpenAPI documentation, and read CONTRIBUTING.md and the usage terms in the README, which ask users not to crawl the API.

Frequently asked questions

Official sources

1. BrasilAPI/BrasilAPI on GitHub
2. Issues
3. License: MIT
4. Project website
5. README