openapi: 3.0.3
info:
  title: DBnomics Datasets Series 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: Series
  description: Economic time series and their observations.
paths:
  /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:
    Observations:
      name: observations
      in: query
      description: Return observations (periods and values) for each series in the response.
      schema:
        type: boolean
        default: false
    ProviderCode:
      name: provider_code
      in: path
      required: true
      description: Code of the provider (e.g. IMF, ECB, Eurostat, BLS, OECD).
      schema:
        type: string
    Limit:
      name: limit
      in: query
      description: The number of items to return.
      schema:
        type: integer
    Facets:
      name: facets
      in: query
      description: Return facets in the response.
      schema:
        type: boolean
        default: false
    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
    DatasetCode:
      name: dataset_code
      in: path
      required: true
      description: Code of the dataset.
      schema:
        type: string
    Metadata:
      name: metadata
      in: query
      description: Return providers and datasets metadata in the response.
      schema:
        type: boolean
        default: true
    Offset:
      name: offset
      in: query
      description: The number of items to skip before starting to collect the result set.
      schema:
        type: integer
  schemas:
    Error:
      type: object
      properties:
        _meta:
          $ref: '#/components/schemas/Meta'
        message:
          type: string
    Meta:
      type: object
      description: Request metadata echoed back with every response.
      properties:
        args:
          type: object
        version:
          type: string
          example: 22.1.17
    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
    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
    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
  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'