DBnomics API v22 released

Community
1

Dear DBnomics community,

We released today the next version (22) of the Web API, and the website (https://db.nomics.world/) uses it.

In short, this new version allows “table” and “multi series charts” views in the dataset pages of the website (example: click on the “Table” and “Chart” tabs.

Note that if you are a user of the website and don’t call the API, you’re not concerned by these changes.

But it you make calls to the API in your scripts or application, you’ll want to upgrade to version 22. The version 21 will remain available at least until version 23 is released, to avoid breaking your application.

Here are some links to help you with this upgrade:

Summary of URL changes (URL parameters are filled with examples):

https://api.db.nomics.world/v21/series?provider_code=P1&dataset_code=D1&dimensions={"FREQ":["A"]}
https://api.db.nomics.world/v22/series/P1/D1?observations=1&dimensions={"FREQ":["A"]}

https://api.db.nomics.world/v21/series?provider_code=P1&dataset_code=D1&series_code_mask=A.FR+DE
https://api.db.nomics.world/v22/series/P1/D1/A.FR+DE?observations=1

https://api.db.nomics.world/v21/series?series_ids=P1/D1/S1,P1/D2/S3
https://api.db.nomics.world/v22/series?observations=1&series_ids=P1/D1/S1,P1/D2/S3

If you have any question, please answer to this message and we will try to help you the best we can.

Best regards and merry Christmas :slight_smile:

1 Like
2

In particular I’m thinking to @acottrell, @jacklucchetti, @signorsignore and @webapperc.

3

Thanks! Gretl’s client code for v22 is now in testing – seems to work fine so far.

4

Having experimented a bit further I have two comments on the v22 APIs.

  1. The new path /datasets/{provider_code} (“Respond datasets of a provider.”)

This could do with fuller documentation. The “limit” and “offset” parameters are
not mentioned under apidocs/v22, and it’s perhaps surprising that the default
limit is 10 (given that some providers have thousands of datasets).

  1. The element “observations_attributes” which appears under series.docs
    in some cases.

This element is represented as an array of arrays. For example under
IMF/CPI/Q.BE.PCPIT_IX we have:

"observations_attributes" : [["REFERENCE_PERIOD", "2013A"]]

Making the inner element here an array suggests that “REFERENCE_PERIOD”
and “2013A” have the same logical status, but I guess it’s actually a matter of
key plus value, in which case it would be more transparent to represent the
inner element(s) as JSON object(s):

"observations_attributes" : [{"REFERENCE_PERIOD" : "2013A"}]

5

How can I request series values by id with v22 API without all dimension descriptions about data set returned in response? For example with v21:

https://api.db.nomics.world/v21/series?provider_code=OECD&dataset_code=KEI&series_code=SLRTCR03.AUS.ST.M&format=json&orientation=column

The response returns only with series values, with the short dataset field.
Same series with v22:

https://api.db.nomics.world/v22/series?observations=1&series_ids=OECD/KEI/SLRTCR03.AUS.ST.M

The response returns with series values and all dimension descriptions about data sets in the datasets field: dimensions_codes_order, dimensions_labels, dimensions_values_labels.

It seems not big deal, but it increases amount of unused traffic for big data sets in case of only values of series are interested.

Thanks in advance.

1 Like
6

Hi @acottrell

Thanks for your feedback!

You’re right, the API documentation was incomplete. We added the missing “limit” and “offset” parameters, in particular for /datasets/{provider_code}.

We also increased the default limit to 50, with a maximum of 500.

About “observations_attributes”, it is implemented as a list to keep the order of the columns.

Thanks again for your contribution!

7

Hi @webapperc

Thanks for your message!

Indeed, in the version 22 of the API we unified the fields that are returned. There is no way to select which fields to return.

I created an issue for that: https://git.nomics.world/dbnomics-fetchers/management/issues/370

I can’t tell you right now when we will do it, we must plan it before.

Thanks again!

1 Like
8

Hi @cbenz

Okay, I understand. It is not urgent.

Adapter for DBnomics API is updated to v22 in web app ERC (Economic RESTful Client).

Thanks.

9

I want raise the subject again. With Api v22 a big bunch of meta data is transmitted which makes fetching data difficult.
Thanks for going to change that with a new realease.

10

Hi @Klaus

due to the requests of the community we are going to reevaluate this feature with more priority.

Thanks for your feedback!

11

Hi @Klaus, we added a metadata argument that can be set to false to disable metadata.

It is documented in API doc: http://api.db.nomics.world/v22/apidocs

1 Like