Fetch economic time series and their observations - by explicit series IDs across providers, by provider and dataset with dimension filters or series-code masks, or as a single series - with JSON or CSV output, period alignment, facets, and metadata options.
openapi: 3.0.3
info:
title: DBnomics API
description: >-
DBnomics is the world's economic database - a free, open-source aggregator
run by Cepremap that harvests macroeconomic time series from more than 90
national and international providers (IMF, ECB, Eurostat, World Bank, OECD,
BLS, BEA, and more) into one standardized format. The Web API serves
providers, datasets, series, and full-text search over HTTPS with no
authentication or API key required. This document is grounded in the live
Swagger definition published at
https://api.db.nomics.world/v22/apispec_1.json (API version 22.1.17).
version: '22.1.17'
contact:
name: DBnomics
url: https://db.nomics.world
email: contact@nomics.world
license:
name: GNU Affero General Public License v3.0
url: https://git.nomics.world/dbnomics/dbnomics-api
servers:
- url: https://api.db.nomics.world/v22
description: DBnomics Web API v22 (public, no authentication)
tags:
- name: Providers
description: Statistical agencies, central banks, and institutions aggregated by DBnomics.
- name: Datasets
description: Dataset metadata within a provider, plus the last-updates feed.
- name: Series
description: Economic time series and their observations.
- name: Search
description: Full-text search across all datasets.
paths:
/providers:
get:
operationId: listProviders
tags:
- Providers
summary: List providers
description: Responds with the paginated list of providers aggregated by DBnomics.
parameters:
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Offset'
responses:
'200':
description: A list of providers.
content:
application/json:
schema:
type: object
properties:
_meta:
$ref: '#/components/schemas/Meta'
providers:
type: object
properties:
docs:
type: array
items:
$ref: '#/components/schemas/Provider'
limit:
type: integer
num_found:
type: integer
offset:
type: integer
'400':
$ref: '#/components/responses/BadRequest'
/providers/{provider_code}:
get:
operationId: getProvider
tags:
- Providers
summary: Retrieve a provider
description: Responds with a provider and its category tree of datasets.
parameters:
- $ref: '#/components/parameters/ProviderCode'
responses:
'200':
description: The requested provider with its category tree.
content:
application/json:
schema:
type: object
properties:
_meta:
$ref: '#/components/schemas/Meta'
provider:
$ref: '#/components/schemas/Provider'
category_tree:
type: array
items:
type: object
'404':
$ref: '#/components/responses/NotFound'
/datasets/{provider_code}:
get:
operationId: listDatasets
tags:
- Datasets
summary: List datasets of a provider
description: Responds with one or several datasets of a provider.
parameters:
- $ref: '#/components/parameters/ProviderCode'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Offset'
responses:
'200':
description: Datasets belonging to the provider.
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetsResponse'
'404':
$ref: '#/components/responses/NotFound'
/datasets/{provider_code}/{dataset_code}:
get:
operationId: getDataset
tags:
- Datasets
summary: Retrieve a dataset
description: Responds with a single dataset of a provider.
parameters:
- $ref: '#/components/parameters/ProviderCode'
- $ref: '#/components/parameters/DatasetCode'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Offset'
responses:
'200':
description: The requested dataset.
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetsResponse'
'404':
$ref: '#/components/responses/NotFound'
/last-updates:
get:
operationId: getLastUpdates
tags:
- Datasets
summary: List last updates
description: Responds with a list of providers and a list of datasets sorted
by creation/conversion date, most recent first.
parameters:
- name: datasets.limit
in: query
description: The number of datasets to return.
schema:
type: integer
- name: datasets.offset
in: query
description: The number of datasets to skip before starting to collect the result set.
schema:
type: integer
- name: providers.limit
in: query
description: The number of providers to return.
schema:
type: integer
- name: providers.offset
in: query
description: The number of providers to skip before starting to collect the result set.
schema:
type: integer
responses:
'200':
description: Recently updated providers and datasets.
content:
application/json:
schema:
type: object
properties:
_meta:
$ref: '#/components/schemas/Meta'
datasets:
type: object
properties:
docs:
type: array
items:
$ref: '#/components/schemas/Dataset'
providers:
type: object
properties:
docs:
type: array
items:
$ref: '#/components/schemas/Provider'
/search:
get:
operationId: searchDatasets
tags:
- Search
summary: Full-text search of datasets
description: Responds with a list of datasets from a full-text search across
every provider aggregated by DBnomics.
parameters:
- name: q
in: query
description: Full-text search query.
schema:
type: string
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Offset'
responses:
'200':
description: Datasets matching the search query.
content:
application/json:
schema:
type: object
properties:
_meta:
$ref: '#/components/schemas/Meta'
results:
type: object
properties:
docs:
type: array
items:
$ref: '#/components/schemas/Dataset'
limit:
type: integer
num_found:
type: integer
offset:
type: integer
/series:
get:
operationId: getSeriesByIds
tags:
- Series
summary: Retrieve series by IDs
description: Responds with a list of series found by IDs, belonging
potentially to different providers and datasets. A series ID is
formatted like provider_code/dataset_code/series_code.
parameters:
- name: series_ids
in: query
required: true
description: List of series IDs separated by commas. A series ID is
formatted like provider_code/dataset_code/series_code.
schema:
type: array
items:
type: string
style: form
explode: false
- $ref: '#/components/parameters/Facets'
- $ref: '#/components/parameters/Observations'
- $ref: '#/components/parameters/Metadata'
- $ref: '#/components/parameters/Format'
- $ref: '#/components/parameters/AlignPeriods'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Offset'
responses:
'200':
description: The requested series, optionally with observations.
content:
application/json:
schema:
$ref: '#/components/schemas/SeriesResponse'
text/csv:
schema:
type: string
'400':
$ref: '#/components/responses/BadRequest'
/series/{provider_code}/{dataset_code}:
get:
operationId: listDatasetSeries
tags:
- Series
summary: List series of a dataset
description: Responds with a list of series belonging to the same dataset,
filterable by dimensions or a full-text query. If the dataset code ends
with a format extension (e.g. .csv), some parameters are preset.
parameters:
- $ref: '#/components/parameters/ProviderCode'
- $ref: '#/components/parameters/DatasetCode'
- name: dimensions
in: query
description: JSON object describing the dimensions filtering the search.
Cannot be used with the series_code path parameter.
schema:
type: string
- name: q
in: query
description: Full-text search query within the dataset.
schema:
type: string
- $ref: '#/components/parameters/Facets'
- $ref: '#/components/parameters/Observations'
- $ref: '#/components/parameters/Metadata'
- $ref: '#/components/parameters/Format'
- $ref: '#/components/parameters/AlignPeriods'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Offset'
responses:
'200':
description: Series belonging to the dataset.
content:
application/json:
schema:
$ref: '#/components/schemas/SeriesResponse'
text/csv:
schema:
type: string
'404':
$ref: '#/components/responses/NotFound'
/series/{provider_code}/{dataset_code}/{series_code}:
get:
operationId: getSeries
tags:
- Series
summary: Retrieve series by code or mask
description: Responds with the series of a dataset matching a series code or
a series code mask (a dimension filter expressed in the code, e.g.
using + for alternatives and empty segments as wildcards). Cannot be
used with the dimensions parameter.
parameters:
- $ref: '#/components/parameters/ProviderCode'
- $ref: '#/components/parameters/DatasetCode'
- name: series_code
in: path
required: true
description: A series code or series code mask (an alternative way to
express a dimension filter).
schema:
type: string
- name: q
in: query
description: Full-text search query within the dataset.
schema:
type: string
- $ref: '#/components/parameters/Facets'
- $ref: '#/components/parameters/Observations'
- $ref: '#/components/parameters/Metadata'
- $ref: '#/components/parameters/Format'
- $ref: '#/components/parameters/AlignPeriods'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Offset'
responses:
'200':
description: The matching series, optionally with observations.
content:
application/json:
schema:
$ref: '#/components/schemas/SeriesResponse'
text/csv:
schema:
type: string
'404':
$ref: '#/components/responses/NotFound'
components:
parameters:
ProviderCode:
name: provider_code
in: path
required: true
description: Code of the provider (e.g. IMF, ECB, Eurostat, BLS, OECD).
schema:
type: string
DatasetCode:
name: dataset_code
in: path
required: true
description: Code of the dataset.
schema:
type: string
Limit:
name: limit
in: query
description: The number of items to return.
schema:
type: integer
Offset:
name: offset
in: query
description: The number of items to skip before starting to collect the result set.
schema:
type: integer
Facets:
name: facets
in: query
description: Return facets in the response.
schema:
type: boolean
default: false
Observations:
name: observations
in: query
description: Return observations (periods and values) for each series in the response.
schema:
type: boolean
default: false
Metadata:
name: metadata
in: query
description: Return providers and datasets metadata in the response.
schema:
type: boolean
default: true
Format:
name: format
in: query
description: Format of the output. If using csv and the response includes
series of different frequencies, many CSV files are produced.
schema:
type: string
enum:
- json
- csv
default: json
AlignPeriods:
name: align_periods
in: query
description: Ensure that all the periods of each series are defined in every
other series, adding NA (not available) values where needed.
schema:
type: boolean
default: false
schemas:
Meta:
type: object
description: Request metadata echoed back with every response.
properties:
args:
type: object
version:
type: string
example: '22.1.17'
Provider:
type: object
properties:
code:
type: string
example: ECB
name:
type: string
example: European Central Bank
region:
type: string
slug:
type: string
terms_of_use:
type: string
website:
type: string
indexed_at:
type: string
format: date-time
Dataset:
type: object
properties:
code:
type: string
name:
type: string
description:
type: string
provider_code:
type: string
provider_name:
type: string
nb_series:
type: integer
dimensions_codes_order:
type: array
items:
type: string
dimensions_labels:
type: object
dimensions_values_labels:
type: object
indexed_at:
type: string
format: date-time
Series:
type: object
properties:
series_code:
type: string
series_name:
type: string
provider_code:
type: string
dataset_code:
type: string
dataset_name:
type: string
dimensions:
type: object
period:
type: array
description: Periods of the observations (when observations=true).
items:
type: string
value:
type: array
description: Observation values (when observations=true); NA when not available.
items:
nullable: true
indexed_at:
type: string
format: date-time
SeriesResponse:
type: object
properties:
_meta:
$ref: '#/components/schemas/Meta'
dataset:
$ref: '#/components/schemas/Dataset'
series:
type: object
properties:
docs:
type: array
items:
$ref: '#/components/schemas/Series'
limit:
type: integer
num_found:
type: integer
offset:
type: integer
providers:
type: object
DatasetsResponse:
type: object
properties:
_meta:
$ref: '#/components/schemas/Meta'
datasets:
type: object
properties:
docs:
type: array
items:
$ref: '#/components/schemas/Dataset'
limit:
type: integer
num_found:
type: integer
offset:
type: integer
Error:
type: object
properties:
_meta:
$ref: '#/components/schemas/Meta'
message:
type: string
responses:
BadRequest:
description: The request parameters are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: The requested provider, dataset, or series was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'