Calling Brazil’s official statistics API can retrieve observations; it cannot, by itself, tell an application what those observations mean. IBGE’s Aggregate Data API exposes structured concepts such as aggregates, variables, classifications, categories, periods, and localities. A semantic layer must preserve those relationships so a value is not detached from its definition.
The public documentation supports that distinction, but it does not establish which datasets or tables a particular author integrated, what model they built, or which implementation problem took the most effort. Without that project record, this account explains the documented design challenge rather than claiming unverified first-person build details.
As an Amazon Associate I earn from qualifying purchases.
What the IBGE API gives you—and what it does not
IBGE describes its Aggregate Data API as the API that feeds SIDRA, its automatic data retrieval system for research and census data. The documentation is version 3.0.0 and was generated on 26 December 2024. It presents data through aggregates and provides routes for associated metadata, periods, variables, and localities. These are useful building blocks, but they are not a guarantee that every returned number is self-explanatory.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
In practical terms, retrieving an observation is only one step. To interpret it, a client needs to know which aggregate it came from, which variable it represents, the applicable classification and category, the geographic level, and the period. The value alone cannot reliably carry all of that context.
#1 Best Overall
IBGE Aggregate Data API documentation
Why a semantic layer matters
A semantic layer gives an application a consistent way to name and constrain statistical concepts rather than passing around unlabeled values. The IBGE documentation offers a helpful conceptual bridge: it says variables, classifications, and categories correspond respectively to OLAP measures, dimensions, and members. That mapping helps explain the shape of the data; it does not establish that different aggregates share identical business meaning or can be combined without qualification.
A robust model therefore needs to retain the source context and make its assumptions visible. A reader or application should be able to trace a displayed statistic back to the aggregate and variable that define it, understand its unit and classification, and identify its geography and reference period. If the project handles revisions or changing classifications, those rules also need to be supported by evidence from the actual source and implementation; they should not be presumed from the API structure alone.
A documented discovery path for an observation
The API’s documented routes suggest a discovery workflow. This describes how to investigate an observation in IBGE’s API, not a claim about a specific private system’s implementation.
- Find the aggregate. Identify the relevant aggregate for the statistical subject. Aggregates are grouped by research in the API documentation.
- Inspect its metadata and periods. Use the corresponding metadata and period routes to establish what the aggregate describes and which reference periods are available.
- Identify the variable. Determine which variable represents the quantity being requested; do not assume a value is meaningful without its variable context.
- Resolve classification and category. Where applicable, identify the classification and category that qualify the observation. IBGE’s OLAP analogy calls these dimensions and members, respectively.
- Specify locality and period. Establish the geographic locality and reference period, using the relevant locality and period information rather than treating geography or time as implicit.
- Preserve provenance in the application. Keep enough source and concept information with the observation for users to determine what it represents and where it came from.
This sequence is a way to reason about the documented API structure, not a prescribed implementation or a promise that every statistic uses every concept in the same way.
Rank #3
Where the metadata API fits
IBGE also has a separate Statistical Metadata API, APIMETADADOS, cataloged for consulting principal metadata classes from its Statistical Metadata System. The federal API catalog describes classes including statistical operations, occurrences of operations, reference documents, and variables. Its entry records version 2.0 dated 23 October 2018 and lists the production host apimetadados.ibge.gov.br.
This is a distinct metadata discovery route, not another name for the Aggregate Data API. Because the catalog entry is dated 2018, its current endpoint details and behavior should be checked against live technical documentation before building on them.
Federal API catalog: APIMETADADOS
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.What cannot be claimed without the project record
Public API documentation establishes the available concepts and their documented relationships; it does not reveal which sources and tables a particular implementation used or how its semantic model handled them. Nor does it identify the hardest obstacle in that build. A concrete account would need a traceable example: the user’s question, the source aggregate and variable, relevant unit and classification, locality and period, the returned value, and the rule the application applied to make that value usable.
Free tools Windows power users keep installed
One-click scans. No signup required.
Without that evidence, it would be misleading to invent a data mismatch, describe an endpoint failure, or claim firsthand experience. The defensible engineering lesson is narrower but important: API access and semantic interpretation are separate tasks. The API provides structured data and discovery routes; an application still has to preserve and explain the meaning attached to each observation.
Sources and scope
IBGE’s 2024–2025 Open Data Plan identifies SIDRA, the IBGE Statistical Metadata Bank, APISIDRA, and APIMetadados among public data access channels. The available evidence supports treating these as public access routes, but does not establish current uptime, complete coverage, response limits, or the definition of any particular economic statistic.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
