Web API
The Web API of DBnomics is hosted here: https://api.db.nomics.world/v22/.
Its OpenAPI (aka Swagger) documentation is available here: https://api.db.nomics.world/v22/apidocs.
Its source code is available here: 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):
# Fetch provider metadata
curl "https://api.db.nomics.world/v22/providers/INSEE"
# Fetch dataset metadata
curl "https://api.db.nomics.world/v22/datasets/INSEE/IPC-2015"
# Fetch series metadata
curl "https://api.db.nomics.world/v22/series/INSEE/IPC-2015/A.IPC.SO.00.00.INDICE.ENSEMBLE.FE.SO.BRUT.2015.FALSE"
# Fetch series metadata with observations
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/.
Its source code is available here: https://git.nomics.world/dbnomics/dbnomics-python-client.
Install the package in a virtual environment:
Then run the Python interpreter and call the fetch_series function:
python
Python 3.14.4 (main, Apr 8 2026, 17:48:49) [GCC 15.2.1 20260209] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> from dbnomics import fetch_series
>>> # Fetch a single series with observations
... df = fetch_series("INSEE/IPC-2015/A.IPC.SO.00.00.INDICE.ENSEMBLE.FE.SO.BRUT.2015.FALSE")
>>> df[["period", "value"]]
period value
0 1990-01-01 66.10
1 1991-01-01 68.30
2 1992-01-01 70.10
3 1993-01-01 71.70
4 1994-01-01 73.00
5 1995-01-01 74.40
6 1996-01-01 75.90
7 1997-01-01 76.80
8 1998-01-01 77.40
9 1999-01-01 78.00
10 2000-01-01 79.10
11 2001-01-01 80.30
12 2002-01-01 81.90
13 2003-01-01 83.70
14 2004-01-01 85.50
15 2005-01-01 87.20
16 2006-01-01 88.89
17 2007-01-01 90.41
18 2008-01-01 92.88
19 2009-01-01 93.21
20 2010-01-01 94.64
21 2011-01-01 96.52
22 2012-01-01 98.36
23 2013-01-01 99.30
24 2014-01-01 99.88
25 2015-01-01 100.00
26 2016-01-01 100.21
27 2017-01-01 101.12
28 2018-01-01 102.70
29 2019-01-01 103.74
30 2020-01-01 104.22
31 2021-01-01 105.81
32 2022-01-01 110.64
33 2023-01-01 115.63
34 2024-01-01 118.00
35 2025-01-01 119.34
The fetch_series function returns a Pandas DataFrame.
Have a look at the tutorial notebook for more examples.
Other clients
Other clients for the Web API are made available by the community.
Clients for programming languages:
- R: rdbnomics (source code)
- Julia: DBnomics.jl
- Stata: dbnomics
Clients for external software:
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 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:
Note: the difference between both URLs is the usage of the align_periods parameter.
Dataset releases
As described in the data model, 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: