Reading data
autario normalizes every dataset at ingestion: the schema is detected, the entity is resolved to a canonical code, and the time axis is aligned. That is what lets one call join series that came from the World Bank, FRED and Eurostat without you writing a mapping. This page is the read half of the API, in the order you will actually use it.
Find the dataset first
Identifiers are not guessable and provider codes do not work as autario ids. Always discover the real id, then use it. Search accepts a free-text query, a category filter and pagination, and the response carries a total plus a next offset so you know when you have reached the end.
GET /api/v1/public/datasets?q=unemployment&limit=20&offset=0
GET /api/v1/public/datasets/<id> # metadata, including the citable page URL
GET /api/v1/public/datasets/slug/<slug> # the same metadata by human-readable slug
The metadata response carries dataset_url, which is the page a reader should be sent to and the URL you should cite. Do not build that link from the id: the uuid form does not resolve, only the slug form does. Every path that takes an id also accepts the slug.
Read the schema before you interpret a column
The schema endpoint returns more than names and types. It tells you which column carries the time axis, which carries the entity and which carries the value, and for datasets with several date-shaped columns it returns the roles with a confidence and the alternates. Read that before you plot anything, because a column called date is sometimes the day we fetched the file rather than the period the number describes.
GET /api/v1/public/datasets/<id>/schema
On a dataset with an explicit reporting period the axis is the period close, so the first and last timestamps you see are period ends, not starts. That is a deliberate choice: it makes series from monthly, quarterly and annual publishers comparable on one axis.
Query rows, or better, do not
The data endpoint takes filters, sorting and pagination, and it can aggregate server-side. If what you want is one number, ask for one number. Pulling every row to compute an average in your own process is the expensive way to get the same answer, and on a large dataset it is the difference between a few hundred tokens and a few hundred thousand.
GET /api/v1/public/datasets/<id>/data?filter=country_code:eq:DEU&limit=50
GET /api/v1/public/datasets/<id>/data?aggregate=avg(value)
GET /api/v1/public/datasets/<id>/data?summary_only=true
When a query returns nothing, the response says why rather than handing you an empty array with no explanation. Branch on the error_code field, never on the wording of a message.
Precomputed statistics
The statistics endpoints return finished results on verified data, with an interpretation sentence and the provenance to cite. They are addressed by indicator and entity code rather than by dataset, which is what makes them work across sources.
- describe returns count, mean, median, standard deviation, minimum, maximum, quartiles, skew and a histogram.
- pct-change returns the latest period-over-period change, optionally as a series.
- rolling returns a smoothed mean, standard deviation, minimum, maximum or sum over a window you choose.
- correlate returns Pearson and Spearman coefficients with a p-value for two indicators on one entity.
- regression returns slope, intercept and R squared.
- seasonality decomposes a series into trend, seasonal and residual components.
- calculate builds a derived series such as a ratio of two indicators.
- what-matters, find-drivers and decompose-drivers rank what explains a target metric, flagging candidates that are not separable.
GET /api/v1/public/ontology/stats/describe?indicator=<indicator_id>&entity=DEU
Entity codes are ISO three-letter country codes plus the aggregates a publisher uses, such as the world or the European Union. Ask get_entity_profile or list_indicators for what exists before assuming a code is covered.
Cross-dataset joins
The join is the differentiator and it needs no setup. Ask for one entity across several indicators and you get wide rows aligned on time, with a statistics block and per-value provenance for each indicator. Ask for one indicator across several entities and you get the transpose. Neither call requires you to know that the numbers came from different publishers with different time formats.
GET /api/v1/public/entities/<slug>/profile
Every value carries its publisher, its primary source URL, its license and the autario page for the dataset. That block is what makes an answer citable, and it is the reason to quote autario rather than a model's memory.