# Table of Contents

- [What is DBnomics? - DBnomics documentation](#what-is-dbnomics-dbnomics-documentation)
- [FAQ - DBnomics documentation](#faq-dbnomics-documentation)
- [Contributing - DBnomics documentation](#contributing-dbnomics-documentation)
- [Web API - DBnomics documentation](#web-api-dbnomics-documentation)
- [Core design principles - DBnomics documentation](#core-design-principles-dbnomics-documentation)
- [Website - DBnomics documentation](#website-dbnomics-documentation)
- [A Public Good Sustained by Its Community - DBnomics documentation](#a-public-good-sustained-by-its-community-dbnomics-documentation)
- [Legal Terms - DBnomics documentation](#legal-terms-dbnomics-documentation)
- [Quick tour - DBnomics documentation](#quick-tour-dbnomics-documentation)
- [Architecture - DBnomics documentation](#architecture-dbnomics-documentation)
- [Data model - DBnomics documentation](#data-model-dbnomics-documentation)
- [Fetchers - DBnomics documentation](#fetchers-dbnomics-documentation)

---

# What is DBnomics? - DBnomics documentation

 

[Skip to content](https://docs.db.nomics.world/#what-is-dbnomics)

[](https://git.nomics.world/dbnomics/dbnomics-docs/tree/master/docs/index.md "Edit this page")

What is DBnomics?
=================

![DBnomics, the world's economic database](https://docs.db.nomics.world/assets/dbnomics-logo.svg)

Economic data is a public good — we make it accessible.

Note

This is the documentation of DBnomics. The main website is available at [https://db.nomics.world/](https://db.nomics.world/)
.

DBnomics is a **free platform that aggregates publicly available economic data** from national and international statistical institutions, as well as researchers and private companies.

All data is standardized into a common format to simplify search, access, and analysis.

![DBnomics dataflow](https://docs.db.nomics.world/assets/dataflow.svg)  

DBnomics data collection and distribution flow

Features
--------

*   **Broad Worldwide Coverage**
    
    * * *
    
    Access millions of economic [time series](https://en.wikipedia.org/wiki/Time_series)
     from national and international institutions through one [website](https://docs.db.nomics.world/website/)
     and a unified [Web API](https://docs.db.nomics.world/web-api/)
    .
    
    The data covers population and living conditions, environment and energy, agriculture, finance, trade, and more.
    
    [Learn more](https://docs.db.nomics.world/quick-tour/)
    
*   **Redistribute Data As-Is**
    
    * * *
    
    DBnomics is intentionally non-opinionated: original dataset and series codes are preserved, numerical values are never modified, and `NA` (not available) values are kept.
    
    We do not reclassify datasets into our own hierarchy: each provider's category tree is shown as-is.
    
    [Learn more](https://docs.db.nomics.world/core-design-principles/#redistribute-data-as-is)
    
*   **Powerful Website**
    
    * * *
    
    Browse datasets through each provider's category tree, search by keyword, or enter dataset or series IDs directly if you know them.
    
    Filter datasets by dimensions, and visualize series as charts or tables.
    
    Download data in various formats (e.g. CSV, Excel XLSX).
    
    [Learn more](https://docs.db.nomics.world/website/)
    
*   **API & Developer-Friendly Tools**
    
    * * *
    
    Access time series directly from your work environment using the [Web API](https://docs.db.nomics.world/web-api/)
     and its client libraries (e.g. [Python](https://git.nomics.world/dbnomics/dbnomics-python-client)
    , [R](https://git.nomics.world/dbnomics/rdbnomics)
    ).
    
    Stop spending time parsing file formats (e.g. XML, CSV, Excel), or copy-pasting data by hand.
    
    [Learn more](https://docs.db.nomics.world/web-api/)
    
*   **Daily Automatic Updates**
    
    * * *
    
    Our daily data pipeline runs dedicated fetchers — one per provider — to collect new releases and archive every revision.
    
    Your indicators are updated as soon as providers publish new data.
    
    [Learn more](https://docs.db.nomics.world/core-design-principles/#automatic-data-updates)
    
*   **Access To Past Revisions**
    
    * * *
    
    Every change from providers is archived, so that past revisions of time series remain accessible.
    
    This enables [reproducible research](https://en.wikipedia.org/wiki/Reproducibility#Reproducible_research)
     for your project.
    
    It also makes it possible to build [real-time historical databases](https://en.wikipedia.org/wiki/Real-time_data)
    .
    
    [Learn more](https://docs.db.nomics.world/core-design-principles/#provider-data-versioning)
    

Why use DBnomics?
-----------------

When you need macroeconomic data, you have to deal with a large number of providers, each with its own infrastructure and data formats. DBnomics aggregates macroeconomic data from a wide range of providers, with a unified data model and format, plus a powerful website and Web API.

With DBnomics, you can consume macroeconomic data from a single access point, with a unified UI (user interface) and API, without dealing with the technical aspects of data fetching (e.g. pagination, rate limits) and file formats (e.g. SDMX, JSON, CSV, XLSX).

Some providers distribute data files without providing a web UI to access them. DBnomics makes it possible to access those data files through its website and Web API.

Whether you are an economist, researcher, student, or data journalist, DBnomics helps you simplify data retrieval and focus on analysis.

---

# FAQ - DBnomics documentation

 

[Skip to content](https://docs.db.nomics.world/faq/#frequently-asked-questions-faq)

[](https://git.nomics.world/dbnomics/dbnomics-docs/tree/master/docs/faq.md "Edit this page")

Frequently asked questions (FAQ)
================================

How can I contact the DBnomics core team?
-----------------------------------------

*   by email: [contact@nomics.world](mailto:contact@nomics.world)
    
*   on the [community forum](https://forum.db.nomics.world/)
    
*   on X: [@DBnomics](https://x.com/DBnomics)
    

I like DBnomics, how can I contribute?
--------------------------------------

Well, glad you like it :)

See the [contributing page](https://docs.db.nomics.world/contributing/)
.

How do you guarantee that data on DBnomics is correct?
------------------------------------------------------

In short, there is no formal guarantee, but...

Fetcher developers use a [validation script](https://docs.db.nomics.world/contributing/#validate-data-produced-by-a-fetcher)
 in order to detect some errors automatically.

Of course, a program cannot verify the correctness of floating-point values. To do that, manual checks must be performed against the original source data on the provider website. The DBnomics core team includes economists who manually verify data produced by a fetcher once developers have finished writing it.

Finally, like many free software projects, DBnomics quality improves each time users contribute, and [reporting problems with data](https://docs.db.nomics.world/contributing/#report-problems-with-data)
 is very helpful.

I've seen a problem with data on DBnomics, what should I do?
------------------------------------------------------------

Please read: [report problems with data](https://docs.db.nomics.world/contributing/#report-problems-with-data)
.

When is data updated?
---------------------

Updating data as soon as the provider publishes it is a major concern. Here are more explanations about how it works.

DBnomics data, distributed by its [web API](https://docs.db.nomics.world/web-api/)
, is updated daily (most of the time) by [fetchers](https://docs.db.nomics.world/fetchers/)
.

There can be two types of delays:

1.  the delay between the publication of new data on the provider side and the next execution of the corresponding fetcher,
2.  and the delay due to a failure of the fetcher, requiring manual intervention.

The delay can be reduced when providers publish a log of data updates (e.g. IMF, INSEE, Eurostat) that is small enough to be checked more often (e.g. hourly). In this case, the download is triggered only when needed, and applies only to data that has been updated since the last fetcher execution. We call this the _incremental_ mode.

Where do I find the source code of a fetcher?
---------------------------------------------

Look at that GitLab group: [https://git.nomics.world/dbnomics-fetchers/](https://git.nomics.world/dbnomics-fetchers/)
.

Can I have private data on DBnomics?
------------------------------------

DBnomics is designed to aggregate and redistribute **publicly available** economic data from external sources — it is not a storage service for private datasets. Data that a researcher keeps private, i.e. not published anywhere publicly, cannot be integrated into DBnomics.

However, if a researcher publishes their data in a publicly accessible location (e.g. a Git repository, an institutional website), DBnomics can treat them as a data provider and fetch the data from there. Their institution can serve as the provider code. In other words, DBnomics is not meant to be the primary storage for the data: it retrieves data from wherever it is already published.

In addition, DBnomics will not redistribute paid data or data that is not licensed for redistribution: doing so would violate the provider's terms of use. This is a legal constraint, not a technical one.

Please [contact us](https://docs.db.nomics.world/faq/#how-can-i-contact-the-dbnomics-core-team)
 if you have questions about a specific data source — we'd be happy to discuss your needs.

Why do fetchers break?
----------------------

If you look at the [dashboard](https://db.nomics.world/dashboard/)
, you will see that many fetchers are in error status with red icons.

Fetchers download and convert data from providers, but the provider website, web API, or data can evolve in an unpredictable way.

Fetcher stability is correlated with provider stability. This includes stable infrastructure, stable API URLs, stable responses, stable data models, etc. When a provider changes something, the fetcher breaks and needs to be fixed by its developers.

Which data sources are easier to process?
-----------------------------------------

Data distributed in manually formatted Excel files is more difficult to process by fetchers, mainly because data is not produced systematically.

For example, having cells with a color background to add semantics to data is quite annoying to process, as well as handling merged cells, or data tables shifted below a header, or having a footer with notes.

On the other hand, structured data files with a stable schema, such as XML, JSON, or CSV, are easier to work with because there are almost no special cases to handle.

Another aspect is the transport layer: it is easier to download static files and process them locally than to follow the pagination of a web API or scrape a website.

---

# Contributing - DBnomics documentation

 

[Skip to content](https://docs.db.nomics.world/contributing/#contributing)

[](https://git.nomics.world/dbnomics/dbnomics-docs/tree/master/docs/contributing.md "Edit this page")

Contributing
============

You can contribute in several ways:

*   by [reporting problems with data](https://docs.db.nomics.world/contributing/#report-problems-with-data)
    
*   by participating in discussions on the [community forum](https://forum.db.nomics.world/)
     and becoming an active community member
*   by writing a client for the Web API to let the users [access data from their work environment](https://docs.db.nomics.world/core-design-principles/#access-data-from-work-environment)
    
*   by creating or maintaining fetchers to support new providers or datasets: see the documentation of dbnomics-toolbox: [https://dbnomics-toolbox.readthedocs.io/en/latest/fetcher-authoring/](https://dbnomics-toolbox.readthedocs.io/en/latest/fetcher-authoring/)
    
*   by subscribing to a paid plan: see the [sponsorship page](https://db.nomics.world/sponsorship)
    
*   for institutions, by joining the steering committee of DBnomics: [contact us](https://docs.db.nomics.world/faq/#how-can-i-contact-the-dbnomics-core-team)
    

Report problems with data
-------------------------

If you notice wrong data on the website, you can help by contributing at different levels.

First, you can notify the DBnomics core team about the problem by [creating a new issue](https://git.nomics.world/dbnomics-fetchers/management/-/issues/new?issuable_template=Problem%20with%20data)
 and filling in the template named "Problem with data". This template contains placeholders that you can replace with real values. The goal is to provide as much detail as possible to help the DBnomics team investigate.

Then you can try to solve the issue yourself if you'd like. Once you have identified the source code repository of the fetcher, you can fork it and submit a merge request. We recommend doing this after discussing with the DBnomics core team on the issue you created.

In any case, thank you for your contribution.

Validate data produced by a fetcher
-----------------------------------

Suppose you just finished writing or fixing a fetcher. Now you'd like to check the validity of data produced by `convert.py`. Run your fetcher if not already done:

`[](https://docs.db.nomics.world/contributing/#__codelineno-0-1) mkdir source-data json-data [](https://docs.db.nomics.world/contributing/#__codelineno-0-2) python download.py source-data [](https://docs.db.nomics.world/contributing/#__codelineno-0-3) python convert.py source-data json-data`

Now install the validation script and run it:

`[](https://docs.db.nomics.world/contributing/#__codelineno-1-1) pip install dbnomics-data-model [](https://docs.db.nomics.world/contributing/#__codelineno-1-2) dbnomics-validate --all-series --all-observations --developer-mode json-data`

Example output:

`[](https://docs.db.nomics.world/contributing/#__codelineno-2-1) - Series "RBA/A3-4/AFROMOTD" at location AFROMOTD.tsv (line 3)   [](https://docs.db.nomics.world/contributing/#__codelineno-2-2)   Error code: duplicated-observations-period  [](https://docs.db.nomics.world/contributing/#__codelineno-2-3)   Message: Duplicated period  [](https://docs.db.nomics.world/contributing/#__codelineno-2-4)   Context:    [](https://docs.db.nomics.world/contributing/#__codelineno-2-5)     period: '2013-11-11' [](https://docs.db.nomics.world/contributing/#__codelineno-2-6)[](https://docs.db.nomics.world/contributing/#__codelineno-2-7) - Series "RBA/A3-4/AFROMOTD" at location AFROMOTD.tsv (line 5)   [](https://docs.db.nomics.world/contributing/#__codelineno-2-8)   Error code: duplicated-observations-period  [](https://docs.db.nomics.world/contributing/#__codelineno-2-9)   Message: Duplicated period  [](https://docs.db.nomics.world/contributing/#__codelineno-2-10)   Context:    [](https://docs.db.nomics.world/contributing/#__codelineno-2-11)     period: '2013-11-12' [](https://docs.db.nomics.world/contributing/#__codelineno-2-12)[](https://docs.db.nomics.world/contributing/#__codelineno-2-13) [...] [](https://docs.db.nomics.world/contributing/#__codelineno-2-14)[](https://docs.db.nomics.world/contributing/#__codelineno-2-15) Encountered errors codes:     [](https://docs.db.nomics.world/contributing/#__codelineno-2-16)     - duplicated-observations-period: 12448`

At the end of the output you'll find a summary of the count of errors by type.

The `--developer-mode` option displays all errors, in particular the non fatal ones, in order to improve the quality of your fetcher. In production this option is not used to accelerate validation.

If your fetcher writes a huge quantity of data, you can remove the `--all-series` option to validate only a randomly chosen sample of series per dataset. You can also remove the `--all-observations` option to validate only a few observations per series.

---

# Web API - DBnomics documentation

 

[Skip to content](https://docs.db.nomics.world/web-api/#web-api)

[](https://git.nomics.world/dbnomics/dbnomics-docs/tree/master/docs/web-api.md "Edit this page")

Web API
=======

The Web API of DBnomics is hosted here: [https://api.db.nomics.world/v22/](https://api.db.nomics.world/v22/)
.

Its OpenAPI (aka Swagger) documentation is available here: [https://api.db.nomics.world/v22/apidocs](https://api.db.nomics.world/v22/apidocs)
.

Its source code is available here: [https://git.nomics.world/dbnomics/dbnomics-api](https://git.nomics.world/dbnomics/dbnomics-api)
.

Usage
-----

The Web API of DBnomics can be used by any programming language able to make HTTP requests and parse JSON responses.

It is designed to query focused data, i.e. a subset of the data available on DBnomics, and not to download large datasets.

Downloading time series using the Web API is recommended over clicking on "Download" on the website:

*   it allows to automate the process: just re-execute your data fetching function and you're sure to get the latest data available on DBnomics, without having to check if there is an update on the website;
*   it allows to fetch only the data you need, without having to download the whole dataset and filter it locally, which can be time-consuming and resource-consuming;
*   it allows to fetch data in a format that is easier to manipulate in your programming language, without having to transform the downloaded file.

It is recommended to add a cache layer to your application to avoid making too many requests to the Web API and to speed up data retrieval.

Clients
-------

### Command-line

To use the Web API with `curl`, `wget`, or any other HTTP client, refer to the OpenAPI documentation and call the endpoint URLs you need.

Here are some examples (the HTTP responses are not shown for brevity):

`[](https://docs.db.nomics.world/web-api/#__codelineno-0-1) # Fetch provider metadata [](https://docs.db.nomics.world/web-api/#__codelineno-0-2) curl "https://api.db.nomics.world/v22/providers/INSEE" [](https://docs.db.nomics.world/web-api/#__codelineno-0-3)[](https://docs.db.nomics.world/web-api/#__codelineno-0-4) # Fetch dataset metadata [](https://docs.db.nomics.world/web-api/#__codelineno-0-5) curl "https://api.db.nomics.world/v22/datasets/INSEE/IPC-2015" [](https://docs.db.nomics.world/web-api/#__codelineno-0-6)[](https://docs.db.nomics.world/web-api/#__codelineno-0-7) # Fetch series metadata [](https://docs.db.nomics.world/web-api/#__codelineno-0-8) curl "https://api.db.nomics.world/v22/series/INSEE/IPC-2015/A.IPC.SO.00.00.INDICE.ENSEMBLE.FE.SO.BRUT.2015.FALSE" [](https://docs.db.nomics.world/web-api/#__codelineno-0-9)[](https://docs.db.nomics.world/web-api/#__codelineno-0-10) # Fetch series metadata with observations [](https://docs.db.nomics.world/web-api/#__codelineno-0-11) curl "https://api.db.nomics.world/v22/series/INSEE/IPC-2015/A.IPC.SO.00.00.INDICE.ENSEMBLE.FE.SO.BRUT.2015.FALSE?observations=1"`

### Python client

The Web API can be called by the Python client available here: [https://pypi.org/project/dbnomics/](https://pypi.org/project/dbnomics/)
.

Its source code is available here: [https://git.nomics.world/dbnomics/dbnomics-python-client](https://git.nomics.world/dbnomics/dbnomics-python-client)
.

Install the package in a virtual environment:

`[](https://docs.db.nomics.world/web-api/#__codelineno-1-1) python3 -m venv test-dbnomics-python [](https://docs.db.nomics.world/web-api/#__codelineno-1-2) source test-dbnomics-python/bin/activate [](https://docs.db.nomics.world/web-api/#__codelineno-1-3) pip install dbnomics`

Then run the Python interpreter and call the `fetch_series` function:

`[](https://docs.db.nomics.world/web-api/#__codelineno-2-1) python [](https://docs.db.nomics.world/web-api/#__codelineno-2-2) Python 3.14.4 (main, Apr  8 2026, 17:48:49) [GCC 15.2.1 20260209] on linux [](https://docs.db.nomics.world/web-api/#__codelineno-2-3) Type "help", "copyright", "credits" or "license" for more information. [](https://docs.db.nomics.world/web-api/#__codelineno-2-4) >>> from dbnomics import fetch_series [](https://docs.db.nomics.world/web-api/#__codelineno-2-5) >>> # Fetch a single series with observations [](https://docs.db.nomics.world/web-api/#__codelineno-2-6) ... df = fetch_series("INSEE/IPC-2015/A.IPC.SO.00.00.INDICE.ENSEMBLE.FE.SO.BRUT.2015.FALSE") [](https://docs.db.nomics.world/web-api/#__codelineno-2-7) >>> df[["period", "value"]]        [](https://docs.db.nomics.world/web-api/#__codelineno-2-8)        period   value [](https://docs.db.nomics.world/web-api/#__codelineno-2-9) 0  1990-01-01   66.10 [](https://docs.db.nomics.world/web-api/#__codelineno-2-10) 1  1991-01-01   68.30 [](https://docs.db.nomics.world/web-api/#__codelineno-2-11) 2  1992-01-01   70.10 [](https://docs.db.nomics.world/web-api/#__codelineno-2-12) 3  1993-01-01   71.70 [](https://docs.db.nomics.world/web-api/#__codelineno-2-13) 4  1994-01-01   73.00 [](https://docs.db.nomics.world/web-api/#__codelineno-2-14) 5  1995-01-01   74.40 [](https://docs.db.nomics.world/web-api/#__codelineno-2-15) 6  1996-01-01   75.90 [](https://docs.db.nomics.world/web-api/#__codelineno-2-16) 7  1997-01-01   76.80 [](https://docs.db.nomics.world/web-api/#__codelineno-2-17) 8  1998-01-01   77.40 [](https://docs.db.nomics.world/web-api/#__codelineno-2-18) 9  1999-01-01   78.00 [](https://docs.db.nomics.world/web-api/#__codelineno-2-19) 10 2000-01-01   79.10 [](https://docs.db.nomics.world/web-api/#__codelineno-2-20) 11 2001-01-01   80.30 [](https://docs.db.nomics.world/web-api/#__codelineno-2-21) 12 2002-01-01   81.90 [](https://docs.db.nomics.world/web-api/#__codelineno-2-22) 13 2003-01-01   83.70 [](https://docs.db.nomics.world/web-api/#__codelineno-2-23) 14 2004-01-01   85.50 [](https://docs.db.nomics.world/web-api/#__codelineno-2-24) 15 2005-01-01   87.20 [](https://docs.db.nomics.world/web-api/#__codelineno-2-25) 16 2006-01-01   88.89 [](https://docs.db.nomics.world/web-api/#__codelineno-2-26) 17 2007-01-01   90.41 [](https://docs.db.nomics.world/web-api/#__codelineno-2-27) 18 2008-01-01   92.88 [](https://docs.db.nomics.world/web-api/#__codelineno-2-28) 19 2009-01-01   93.21 [](https://docs.db.nomics.world/web-api/#__codelineno-2-29) 20 2010-01-01   94.64 [](https://docs.db.nomics.world/web-api/#__codelineno-2-30) 21 2011-01-01   96.52 [](https://docs.db.nomics.world/web-api/#__codelineno-2-31) 22 2012-01-01   98.36 [](https://docs.db.nomics.world/web-api/#__codelineno-2-32) 23 2013-01-01   99.30 [](https://docs.db.nomics.world/web-api/#__codelineno-2-33) 24 2014-01-01   99.88 [](https://docs.db.nomics.world/web-api/#__codelineno-2-34) 25 2015-01-01  100.00 [](https://docs.db.nomics.world/web-api/#__codelineno-2-35) 26 2016-01-01  100.21 [](https://docs.db.nomics.world/web-api/#__codelineno-2-36) 27 2017-01-01  101.12 [](https://docs.db.nomics.world/web-api/#__codelineno-2-37) 28 2018-01-01  102.70 [](https://docs.db.nomics.world/web-api/#__codelineno-2-38) 29 2019-01-01  103.74 [](https://docs.db.nomics.world/web-api/#__codelineno-2-39) 30 2020-01-01  104.22 [](https://docs.db.nomics.world/web-api/#__codelineno-2-40) 31 2021-01-01  105.81 [](https://docs.db.nomics.world/web-api/#__codelineno-2-41) 32 2022-01-01  110.64 [](https://docs.db.nomics.world/web-api/#__codelineno-2-42) 33 2023-01-01  115.63 [](https://docs.db.nomics.world/web-api/#__codelineno-2-43) 34 2024-01-01  118.00 [](https://docs.db.nomics.world/web-api/#__codelineno-2-44) 35 2025-01-01  119.34`

The `fetch_series` function returns a Pandas DataFrame.

Have a look at the [tutorial notebook](https://git.nomics.world/dbnomics/dbnomics-python-client/-/blob/master/index.ipynb)
 for more examples.

### Other clients

Other clients for the Web API are made available by the community.

Clients for programming languages:

*   R: [rdbnomics](https://cran.r-project.org/web/packages/rdbnomics/)
     ([source code](https://git.nomics.world/dbnomics/rdbnomics)
    )
*   Julia: [DBnomics.jl](https://github.com/s915/DBnomics.jl)
    
*   Stata: [dbnomics](https://github.com/dreameater89/dbnomics)
    

Clients for external software:

*   [EViews](https://www.eviews.com/)
    : [foreign format database](https://www.eviews.com/help/helpintro.html#page/content%2Fdatabase-Foreign_Format_Databases.html%23ww201468)
    
*   [Gretl](http://gretl.sourceforge.net/)
    : [dbnomics addon](http://gretl.sourceforge.net/addons-data/addons.xml)
    
*   Matlab: [mdbnomics](https://git.dynare.org/dbnomics/mdbnomics)
    

### Contributing

If you're using a programming language or an application that is not already supported, please tell us about it!

To download DBnomics data, you can always call the Web API directly by using the common HTTP functions, but manipulating a dedicated client should feel easier.

You can contribute by telling us how you access DBnomics data from your preferred application.

You can also contribute by writing a new package for a programming language, allowing others to retrieve DBnomics data from that language and helping the DBnomics community grow.

More ways to contribute are described on the [contributing](https://docs.db.nomics.world/contributing/)
 page.

Features
--------

### Time series alignment

In order to represent many time series on the same table, they must share a common list of periods.

But sometimes, series distributed by providers are incomplete, like this:

Series A

| PERIOD | VALUE |
| --- | --- |
| 2000 | 1   |
| 2001 | 7   |
| 2003 | 2   |
| 2004 | NA  |

Series B

| PERIOD | VALUE |
| --- | --- |
| 2001 | 5   |
| 2003 | 6   |
| 2004 | NA  |
| 2005 | 8   |

Time series alignment consists of unifying the periods of all requested series, and filling the gaps with `NA` values:

| PERIOD | Series A | Series B |
| --- | --- | --- |
| 2000 | 1   | NA  |
| 2001 | 7   | 5   |
| 2002 | NA  | NA  |
| 2003 | 2   | 6   |
| 2004 | NA  | NA  |
| 2005 | NA  | 8   |

The Web API, via its parameter `align_periods`, is able to do that:

*   [original non-aligned time series](https://api.db.nomics.world/v22/series/ECB/BSI?metadata=0&observations=1&align_periods=0&dimensions=%7B%22FREQ%22%3A%5B%22M%22%5D%2C%22REF_AREA%22%3A%5B%22U2%22%5D%2C%22ADJUSTMENT%22%3A%5B%22N%22%5D%2C%22BS_REP_SECTOR%22%3A%5B%22R%22%5D%7D)
    
*   [aligned time series](https://api.db.nomics.world/v22/series/ECB/BSI?metadata=0&observations=1&align_periods=1&dimensions=%7B%22FREQ%22%3A%5B%22M%22%5D%2C%22REF_AREA%22%3A%5B%22U2%22%5D%2C%22ADJUSTMENT%22%3A%5B%22N%22%5D%2C%22BS_REP_SECTOR%22%3A%5B%22R%22%5D%7D)
    

Note: the difference between both URLs is the usage of the `align_periods` parameter.

### Dataset releases

As described in the [data model](https://docs.db.nomics.world/data-model/#dataset-releases)
, datasets can have releases in DBnomics.

The Web API is able to resolve the reserved release code `latest` to the actual release code.

For example, if a dataset has 2 releases `WEO:2019-04` and `WEO:2019-10`, declared in this order, `WEO:latest` is resolved to `WEO:2019-10`.

The endpoints of the Web API that accept a dataset code parameter are able to do this resolution using an HTTP temporary redirection (code 302).

For example:

`[](https://docs.db.nomics.world/web-api/#__codelineno-3-1) curl -I "https://api.db.nomics.world/v22/datasets/IMF/WEO:latest" [](https://docs.db.nomics.world/web-api/#__codelineno-3-2)[](https://docs.db.nomics.world/web-api/#__codelineno-3-3) HTTP/1.0 302 FOUND [](https://docs.db.nomics.world/web-api/#__codelineno-3-4) Location: https://api.db.nomics.world/v22/datasets/IMF/WEO:2019-10 [](https://docs.db.nomics.world/web-api/#__codelineno-3-5) [...]`

---

# Core design principles - DBnomics documentation

 

[Skip to content](https://docs.db.nomics.world/core-design-principles/#core-design-principles)

[](https://git.nomics.world/dbnomics/dbnomics-docs/tree/master/docs/core-design-principles.md "Edit this page")

Core design principles
======================

Redistribute data as-is
-----------------------

DBnomics redistributes data from providers without modifying it. Only the format of the data may be normalized to ensure consistency across different providers. The original dataset and series codes are preserved, numerical values are never modified, and `NA` (not available) values are kept. The category tree of datasets is also kept as-is, when published by the provider.

The concrete rules about what is preserved as-is and what is normalized are documented on the [Data model](https://docs.db.nomics.world/data-model/)
 page.

Automatic data updates
----------------------

We want up-to-date data on DBnomics, so data is updated automatically.

Data acquisition is done by the [fetchers](https://docs.db.nomics.world/fetchers/)
 which are run automatically by the [fetcher pipeline](https://docs.db.nomics.world/fetchers/#fetcher-pipeline)
.

We also want to track fetcher executions, which is why we have a [dashboard](https://db.nomics.world/dashboard)
.

Provider data versioning
------------------------

DBnomics is designed to store each revision of the data fetched from a provider when running a [fetcher](https://docs.db.nomics.world/fetchers/)
 from the [pipeline](https://docs.db.nomics.world/fetchers/#fetcher-pipeline)
.

As a consequence, past revisions of time series remain accessible. This enables [reproducible research](https://en.wikipedia.org/wiki/Reproducibility#Reproducible_research)
 for your project.

Access data from work environment
---------------------------------

DBnomics is designed to allow consumers to download time series directly from their work environment, by exposing data using the data types they are familiar with without having to parse file formats (e.g. XML, CSV, Excel) or copy-paste data by hand.

Read more about the [clients of the Web API](https://docs.db.nomics.world/web-api/#clients)
.

---

# Website - DBnomics documentation

 

[Skip to content](https://docs.db.nomics.world/website/#website)

[](https://git.nomics.world/dbnomics/dbnomics-docs/tree/master/docs/website.md "Edit this page")

Website
=======

The website of DBnomics is available at [https://db.nomics.world/](https://db.nomics.world/)
.

It allows users to browse and download time series.

URL structure
-------------

The website URLs are designed to reflect the structure of the data, remain human-readable, and be easy to share.

Here are the main URLs used for browsing data:

*   `https://db.nomics.world/{provider_code}`: provider page
*   `https://db.nomics.world/{provider_code}/{dataset_code}`: dataset page
*   `https://db.nomics.world/{provider_code}/{dataset_code}/{series_code}`: series page

You can navigate up the hierarchy by removing the last segment of the URL: from series to dataset, then from dataset to provider.

Available pages
---------------

### Search page

This page shows the results of a search query.

*   URL: `https://db.nomics.world/?q={query}` (replace `{query}` with your search query)
*   Example: [https://db.nomics.world/?q=trade+products](https://db.nomics.world/?q=trade+products)
    

This page is available by typing a search query in the search input field of the sidebar.

[![Sidebar search](https://docs.db.nomics.world/assets/screenshots/website_sidebar_search.png)](https://db.nomics.world/)

[![full text search](https://docs.db.nomics.world/assets/screenshots/website_search_results.png)](https://db.nomics.world/?q=trade+products)

### List of providers page

This page shows the available providers in DBnomics.

*   URL: [https://db.nomics.world/providers](https://db.nomics.world/providers)
    

[![providers page](https://docs.db.nomics.world/assets/screenshots/website_list_of_providers_page.png)](https://db.nomics.world/providers)

### Provider page

This page shows the datasets of a provider.

*   URL: `https://db.nomics.world/{provider_code}` (replace `{provider_code}` with the provider's code)
*   Example: [https://db.nomics.world/CEPII](https://db.nomics.world/CEPII)
    

[![CEPII provider](https://docs.db.nomics.world/assets/screenshots/website_provider_cepii.png)](https://db.nomics.world/CEPII)

#### Category tree

These datasets are often organized by the provider in a category tree, as shown in the screenshot above.

### Dataset page

This page shows the series of a dataset and allows users to filter them by dimensions.

*   URL: `https://db.nomics.world/{provider_code}/{dataset_code}` (replace `{provider_code}` and `{dataset_code}` with the provider's and dataset's codes)
*   Example: [https://db.nomics.world/CEPII/BACI\_HS17](https://db.nomics.world/CEPII/BACI_HS17)
    

[![dataset page](https://docs.db.nomics.world/assets/screenshots/website_dataset_page_BACI_HS17.png)](https://db.nomics.world/CEPII/BACI_HS17)

#### Filter by dimension

You can filter the series of a dataset by their dimensions (e.g. Country=France, Frequency=Quarterly, etc).

Note

This search pattern is often called [faceted search](https://en.wikipedia.org/wiki/Faceted_search)
 and is commonly used on e-commerce websites to find products by criteria like size, weight, color, etc.

Here is the dataset `CEPII/BACI_HS17`, with the dimension "Exporter" set to "France". The number of series matching this criterion is shown:

[![dataset page with dimension filter](https://docs.db.nomics.world/assets/screenshots/website_dataset_page_BACI_HS17_exporter_france.png)](https://db.nomics.world/CEPII/BACI_HS17?dimensions=%7B%22i%22%3A%5B%22251%22%5D%7D)

#### Full-text search

It is also possible to do a full-text search on the series belonging to the current dataset (as opposed to the search of the home page which targets the whole database).

[![dataset page with full-text search](https://docs.db.nomics.world/assets/screenshots/website_dataset_page_BACI_HS17_full_text_search.png)](https://db.nomics.world/CEPII/BACI_HS17?q=animal)

#### Download series

Limitations

Downloading series from the website requires a [user account](https://docs.db.nomics.world/website/#user-account)
.

Due to technical limitations, it is not possible to download more than 1000 series at once from the website. If you want to download more series, please use the [Web API](https://docs.db.nomics.world/web-api/)
.

Click on the "Download" button to open a menu and select "Excel file" or "CSV file".

Downloading series from the website is useful for one-off exports, but you need to start the download again manually each time you want fresh data. With the [Web API](https://docs.db.nomics.world/web-api/)
 and its [clients](https://docs.db.nomics.world/web-api/#clients)
, you can automate retrieval and updates of your time series directly from your preferred environment (e.g. Python, R, etc.).

### Series page

Each time series has its own URL, allowing it to be displayed as a chart or a table, and making it easier to reference.

Here is the page of the time series `ECB/EXR/A.ARS.EUR.SP00.A`:

[![series page](https://docs.db.nomics.world/assets/screenshots/website_series_page.png)](https://db.nomics.world/ECB/EXR/A.ARS.EUR.SP00.A)

User account
------------

Creating an account is required to download data, but not to browse it.

To create a user account, click on the "Sign up" button in the sidebar.

Once you have an account, you can log in by clicking on the "Login" button in the sidebar.

### Starred series

Once you are logged in, you can star time series to easily find them later.

You can find a "Star" or "Unstar" button on each series page.

Your starred series are listed on your user page, accessible by clicking on your username in the sidebar.

---

# A Public Good Sustained by Its Community - DBnomics documentation

 

[Skip to content](https://docs.db.nomics.world/public-good-and-community/#a-public-good-sustained-by-its-community)

[](https://git.nomics.world/dbnomics/dbnomics-docs/tree/master/docs/public-good-and-community.md "Edit this page")

A Public Good Sustained by Its Community
========================================

Most macroeconomic series exist thanks to public funding. They are a public good for administrations, researchers, and businesses alike – and should remain accessible without costly intermediaries.

We aim to grow a **community of users** around the project, and share the maintenance of the [fetchers](https://git.nomics.world/dbnomics-fetchers)
 with a community of **contributors**.

The platform is developed and maintained on a modest budget of less than €200,000 per year, funded by partner institutions and the community.

Our tools are already used by analysts, data scientists, and modelers in major public institutions, including the OECD, Bank of France, and the French Directorate General of the Treasury. DBnomics can support your team with easy data access, seamless workflow integration, and zero infrastructure requirements.

If your organization relies on time series, DBnomics offers a reliable gateway to global economic data. We welcome new users and contributors to join our growing community.

* * *

Want to support open access to economic data? [Become a sponsor](https://db.nomics.world/sponsorship)
.

---

# Legal Terms - DBnomics documentation

 

[Skip to content](https://docs.db.nomics.world/legal-terms/#legal-terms)

[](https://git.nomics.world/dbnomics/dbnomics-docs/tree/master/docs/legal-terms.md "Edit this page")

Legal Terms
===========

DBnomics copyright © 2015 – present, [Cepremap](https://www.cepremap.fr/)

*   Data distributed by DBnomics is subject to the same license and terms of use as its original source provider.
*   The DBnomics aggregated datasets are distributed under the [Open Database License](https://www.opendatacommons.org/licenses/odbl/)
     (ODbL).
*   Each source code repository has its own license, available on our [GitLab platform](https://git.nomics.world/dbnomics/)
    ; most of the data fetchers are distributed under the [GNU Affero General Public License version 3 or later](https://www.gnu.org/licenses/agpl-3.0.en.html)
     (AGPLv3+).
*   DBnomics republishes data from various official and public sources. DBnomics and Cepremap are not responsible for the accuracy or continued availability of the source data.

---

# Quick tour - DBnomics documentation

 

[Skip to content](https://docs.db.nomics.world/quick-tour/#quick-tour)

[](https://git.nomics.world/dbnomics/dbnomics-docs/tree/master/docs/quick-tour.md "Edit this page")

Quick tour
==========

Let's say we want to find data about product transactions between France and some other countries.

We'll start by searching for a corresponding dataset on the DBnomics website, and then we'll see how to download time series using the Python client of the web API.

DBnomics website
----------------

The [website](https://db.nomics.world/)
 of DBnomics allows users to browse data using different entry points.

### Search for datasets

In our case let's say we don't know which dataset contains the data we are looking for, so we start with a full-text search.

Enter the `trade products` keywords in the search field of the sidebar, and see the [search results](https://db.nomics.world/?q=trade+products)
:

[![full text search](https://docs.db.nomics.world/assets/screenshots/website_search_results.png)](https://db.nomics.world/?q=trade+products)

After looking at the results, we choose to use the dataset [`CEPII/BACI_HS17`](https://db.nomics.world/CEPII/BACI_HS17)
, which contains data about bilateral trade of products between countries.

Clicking on "Go to dataset" opens the dataset page.

### Dataset page

[![dataset page](https://docs.db.nomics.world/assets/screenshots/website_dataset_page_BACI_HS17.png)](https://db.nomics.world/CEPII/BACI_HS17)

The dataset page shows the total number of series (17,819,522 in this case), and allows users to filter them by dimensions.

Let's set the "Exporter" dimension to "France", and see the 497,196 series that match this criterion:

[![dataset page with dimension filter](https://docs.db.nomics.world/assets/screenshots/website_dataset_page_BACI_HS17_exporter_france.png)](https://db.nomics.world/CEPII/BACI_HS17?dimensions=%7B%22i%22%3A%5B%22251%22%5D%7D)

### Series page

Each time series has its own URL, allowing it to be displayed as a chart or a table, and making it easier to reference.

Here is the page of the time series `ECB/EXR/A.ARS.EUR.SP00.A`:

[![series page](https://docs.db.nomics.world/assets/screenshots/website_series_page.png)](https://db.nomics.world/ECB/EXR/A.ARS.EUR.SP00.A)

---

# Architecture - DBnomics documentation

 

[Skip to content](https://docs.db.nomics.world/architecture/#architecture)

[](https://git.nomics.world/dbnomics/dbnomics-docs/tree/master/docs/architecture.md "Edit this page")

Architecture
============

DBnomics services
-----------------

The source code of these components is available on GitLab:

*   [https://git.nomics.world/dbnomics/dbnomics-api](https://git.nomics.world/dbnomics/dbnomics-api)
    
*   [https://git.nomics.world/dbnomics/dbnomics-website](https://git.nomics.world/dbnomics/dbnomics-website)
    
*   [https://git.nomics.world/dbnomics/dbnomics-dashboard](https://git.nomics.world/dbnomics/dbnomics-dashboard)
    
*   [https://git.nomics.world/dbnomics/dbnomics-solr](https://git.nomics.world/dbnomics/dbnomics-solr)
    

### Run a local instance

To run a local instance of the DBnomics services, you can use the [dbnomics-docker](https://git.nomics.world/dbnomics/dbnomics-docker)
 project, which provides Docker images and Docker Compose files for the different services.

---

# Data model - DBnomics documentation

 

[Skip to content](https://docs.db.nomics.world/data-model/#data-model)

[](https://git.nomics.world/dbnomics/dbnomics-docs/tree/master/docs/data-model.md "Edit this page")

Data model
==========

This page gives a high-level overview of the DBnomics data model, and the main design principles behind it.

The [data model page](https://dbnomics-toolbox.readthedocs.io/en/latest/data-model/)
 of the documentation of the `dbnomics-toolbox` library explains how this data model is implemented in Python and how to use it in fetchers.

Data representation principles
------------------------------

DBnomics distinguishes data from its format, and simplifies format only.

This means DBnomics tries to preserve provider semantics while normalizing a limited set of representation details needed for consistent access across providers.

### Preserved provider semantics

The following items are kept as-is from the provider:

*   time series and their observations
*   dataset dimensions: a dataset may have a dimension named "Country" with values "France", "Germany", etc., and another dataset may have a dimension named "REF\_AREA" with values "FR", "DE", etc. DBnomics does not try to harmonize those dimensions, but keeps them as-is from the provider.
*   NA (non-available) values usage: DBnomics does not add or remove them. If a provider distributes a time series with an incomplete calendar (with some missing periods), DBnomics does not try to complete it

Some providers distribute time series with no observation, or with only NA values, and DBnomics keeps them as-is as well. Here are some examples:

*   [time series with no observation](https://db.nomics.world/BDF/QFAGG/QFAGG.Q.N.FR.W0.S13._Z.C.A.LE.F66._Z._Z.XDC._T.S.V.N._T)
    
*   [time series with only NA values](https://db.nomics.world/WB/DB/IC.REG.COST.PC.MA.ZS-AD)
    
*   [other special cases](https://git.nomics.world/dbnomics-fetchers/documentation/-/wikis/special-datasets)
     on our wiki

### Normalized representation

Some data is normalized from provider source data:

*   periods: providers use different ways to represent them and DBnomics defines a standard format (e.g. `202001` or `2020M01` becomes `2020-01`)
*   NA (non-available) values: some providers use `NaN`, some others `-9999`, etc. DBnomics always uses `NA`

Normalization is done by each fetcher in the data conversion part, based on the knowledge of the provider source data. For example, a period like `2000-qII` would be normalized as `2000-Q2`.

Why normalize this?

If we kept the original formats for periods or NA values, it would be difficult to, for example, represent time series on a chart, because each format would have to be handled separately.

The best place to do this normalization is in the fetcher, because it has the knowledge of the provider source data, and can be adapted to each provider.

Conceptual model
----------------

We first present a conceptual model of the main DBnomics concepts and their relationships:

Note

This diagram is a conceptual model, meant as a mental model of the main DBnomics concepts and their relationships.

It does not reflect the actual implementation or describe the in-memory representation used by DBnomics or by `dbnomics_toolbox.model`. The subsections below describe the conceptual model.

### Provider

Each provider has:

*   a code that must be unique across providers
*   many datasets (see section below)

Examples: `IMF` for International Monetary Fund, `OECD` for Organisation for Economic Co-operation and Development, `WB` for World Bank, etc.

Provider codes are used in several [DBnomics URLs](https://docs.db.nomics.world/website/#url-structure)
.

### Dataset

Each dataset is part of a provider and has:

*   a code that must be unique across a single provider (e.g. `BOP` for Balance of Payments).
*   an ID that is the concatenation of the provider code and the dataset code, separated by a slash (e.g. `IMF/BOP`).
*   many dimensions definitions (see section below)
*   many series (see section below)

Dataset codes are used in several [DBnomics URLs](https://docs.db.nomics.world/website/#url-structure)
.

#### Dataset dimensions

In DBnomics datasets are multi-dimensional and are sometimes referred to as [data cubes](https://en.wikipedia.org/wiki/Data_cube)
.

Each dataset defines an ordered list of dimensions, and each series of the dataset has a value for each dimension.

For example, a dataset may have dimensions `FREQ` (frequency), `REF_AREA` (reference area), `UNIT` (unit of measurement), etc., and a series of this dataset may have values `A` for `FREQ`, `FR` for `REF_AREA`, `USD` for `UNIT`, etc.

#### Dataset releases

Sometimes providers publish datasets with releases.

In DBnomics each dataset release is a regular dataset having a code following this pattern: `{dataset_code}:{release_code}`.

For example, IMF publishes WEO every 6 months (e.g. `2019-04`, `2019-10`, `2020-04`, etc.) and DBnomics datasets have the codes `WEO:2019-04`, `WEO:2019-10`, `WEO:2020-04`, etc.

See also: [dataset releases](https://docs.db.nomics.world/web-api/#dataset-releases)
.

### Series

Each series is part of a dataset and has:

*   a code that must be unique across a single dataset (e.g. `A.1C_355.BACK_BP6_USD`)
*   an ID that is the concatenation of the dataset ID and the series code, separated by a slash (e.g. `IMF/BOP/A.1C_355.BACK_BP6_USD`)
*   a name that SHOULD be unique
*   a value for each dimension of the dataset (e.g. `FREQ => A`, `REF_AREA => FR`, etc.)
*   many observations (see section below)

Duplicate series names

Some providers give the same names to many series. DBnomics data model tolerates this, even if it's not recommended.

In this case, the user will always be able to distinguish those time series by looking at their code or dimensions.

Series without code

Some providers don't give codes to series, but only dimensions (e.g. `{"FREQ": "A", "REF_AREA": "FR"}`). In this case, as the series code is required in the data model of DBnomics, it can be generated from the dimensions (e.g. `A.FR`).

This does not mean that the series codes must be generated from dimensions: some providers give arbitrary codes to series, that do not correspond to dimensions (e.g. `SERIES_137`).

However, building the series codes from dimensions is a common practice among providers, and is recommended as it makes them easier to understand and more stable over time.

### Observation

An observation is a pair of period and value, like `{"period": "2020-01", "value": 123.45}`.

It can also have attributes: a set of key-value pairs (e.g. `{"unit": "USD", "status": "final"}`).

Periods can be years (`2020`), months (`2020-01`), quarters (`2020-Q1`), etc. For more information, see the documentation of `dbnomics-toolbox` on [periods](https://dbnomics-toolbox.readthedocs.io/en/latest/data-model#periods)
.

Example: multi-dimensional dataset
----------------------------------

A multi-dimensional dataset defines many dimensions and has many series where each one is categorized using dimensions.

To help understanding that concept, here is an example. Let's start from the following hypothetical CSV file named `product_prices.csv` that tracks the evolution of the price of different products in different countries:

| sku | country | year | price |
| --- | --- | --- | --- |
| 111 | FR  | 2000 | 12  |
| 111 | FR  | 2001 | 13  |
| 111 | FR  | 2002 | 11  |
| 111 | DE  | 2001 | 9   |
| 111 | DE  | 2002 | 11  |
| 111 | DE  | 2003 | 14  |
| 222 | FR  | 2000 | 87  |
| 222 | FR  | 2001 | 88  |
| 222 | FR  | 2002 | 90  |
| 222 | FR  | 2003 | 79  |

We can consider this file a multi-dimensional dataset if we identify dimensions in it, and series where each one is categorized by those dimensions.

Based on the given columns, we can infer 2 dimensions: `SKU` and `COUNTRY` (we'll keep this order), with values `SKU={111,222}` and `COUNTRY={DE,FR}`.

The remaining columns `year` and `price` define the observations of each series, and the series can be found by applying a "group-by" operation on the dimensions.

So the dataset is composed of 4 time series, each being related to a single product and country.

Series `111.FR`:

| period | value |
| --- | --- |
| 2000 | 12  |
| 2001 | 13  |
| 2002 | 11  |

Series `111.DE`:

| period | value |
| --- | --- |
| 2001 | 9   |
| 2002 | 11  |
| 2003 | 14  |

Series `222.FR`:

| period | value |
| --- | --- |
| 2000 | 87  |
| 2001 | 88  |
| 2002 | 90  |
| 2003 | 79  |

Series codes

Because the dimensions of a dataset are ordered, we can infer the series codes by concatenating the codes of the values of the dimensions, separated by a `.` character.

For example, the series for `SKU=111` and `COUNTRY=FR` has the code `111.FR`, and not `FR.111`.

---

# Fetchers - DBnomics documentation

 

[Skip to content](https://docs.db.nomics.world/fetchers/#fetchers)

[](https://git.nomics.world/dbnomics/dbnomics-docs/tree/master/docs/fetchers.md "Edit this page")

Fetchers
========

What is a fetcher?
------------------

In DBnomics, data acquisition is done by _fetchers_, small programs that download data from provider infrastructures and convert it to a common [data model](https://docs.db.nomics.world/data-model/)
 and format.

There is one fetcher per data provider.

Here is a diagram that shows the main steps of a fetcher:

The source code of the fetchers is hosted in a GitLab group: [https://git.nomics.world/dbnomics-fetchers](https://git.nomics.world/dbnomics-fetchers)
. Each repository is dedicated to a fetcher, for example [https://git.nomics.world/dbnomics-fetchers/insee-fetcher](https://git.nomics.world/dbnomics-fetchers/insee-fetcher)
.

To write a new fetcher or maintain an existing one, see [contributing](https://docs.db.nomics.world/contributing/)
.

Fetcher pipeline
----------------

The fetcher pipeline is the part of the DBnomics infrastructure that runs fetchers and makes their output available on the DBnomics website and Web API.

The source code of the fetcher pipeline is available in the [dbnomics-fetcher-pipeline](https://git.nomics.world/dbnomics/dbnomics-fetcher-pipeline)
 repository.

Fetcher pipelines are scheduled regularly (daily by default) in order to keep DBnomics data up to date.

### Dashboard

The [dashboard](https://db.nomics.world/dashboard/)
 shows the status of the latest pipeline executions for each fetcher.

[![DBnomics dashboard](https://docs.db.nomics.world/assets/screenshots/dbnomics_dashboard.png)](https://db.nomics.world/dashboard/)

Its source code is available in the [dbnomics-dashboard](https://git.nomics.world/dbnomics/dbnomics-dashboard)
 repository.

---