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'