Skip to content

Web API

Useful links:

Time series completion

Sometimes a time series can be incomplete (i.e. have holes in the periods).

As explained on the features page, one of the design goals of DBnomics is to redistribute data from providers as-is.

Example:

PERIOD VALUE
2000 1
2001 7
2003 2
2004 NA

In the above series, the year 2002 is missing, and DBnomics will not inject it.

However you can download the time series from a DBnomics client of a programming language (e.g. Python) and complete the time series by yourself, adding missing periods with NA values.

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

A solution would be to complete both series (cf time series completion) in order to insert missing periods using NA values, but depending on the case, that would insert a huge number of lines.

There is another solution, time series alignment, which consists of unifying the periods of all requested series, and insert NA values only for those inserted periods, like this:

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:

curl -I "https://api.db.nomics.world/v22/datasets/IMF/WEO:latest"

HTTP/1.0 302 FOUND
Location: https://api.db.nomics.world/v22/datasets/IMF/WEO:2019-10
[...]