Libraries and APIs

All the options below read the same published files, so the numbers are the same whichever one you use.

JSON API

A read-only HTTP API at https://dataseries.org. No key required.

Endpoint	Returns
`GET /catalog`	the full list of datasets (id, title, source, license, frequency, span, last updated)
`GET /dataset/{id}/meta`	one dataset's metadata: dimensions, levels, labels, units, hierarchy
`GET /series?dataset={id}&dims={spec}&from={date}&to={date}`	the selected series as columnar JSON
`GET /series.csv?dataset={id}&dims={spec}&from={date}&to={date}`	the same selection as tidy CSV (one row per observation), readable by any tool that opens a CSV URL
`GET /health`	service status

dims selects levels within each dimension, separated by semicolons, for example structure=gdp;type=nom;seas_adj=csa. Leave it out to get the whole dataset. from and to are optional ISO dates.

# Whole catalog
curl https://dataseries.org/catalog
# SECO GDP, nominal, seasonally adjusted, from 2000
curl "https://dataseries.org/series?dataset=ch_seco_gdp&dims=structure=gdp;type=nom;seas_adj=csa&from=2000-01-01"
# A single-series dataset
curl "https://dataseries.org/series?dataset=ch_kof_barometer"

The endpoints are documented at /__docs__/, where you can also try them out. The OpenAPI spec is at /openapi.json.

R

ds() takes a dataset id and one argument per dimension, and returns a data frame with a Date column. ds_catalog() lists the datasets, ds_meta() shows a dataset's dimensions and codes, and ds_search() finds individual series.

install.packages("dataseries")
library(dataseries)
# SECO GDP, nominal, seasonally adjusted, from 2000
df <- ds("ch_seco_gdp", structure = "gdp", type = "nom", seas_adj = "csa",
         from = "2000-01-01")
# A single-series dataset: no dimension arguments
df <- ds("ch_kof_barometer")

Python

The Python package has the same functions as the R package and returns pandas DataFrames. The date arguments are called start and end instead of from and to.

pip install dataseries

from dataseries import ds
# SECO GDP, nominal, seasonally adjusted, from 2000
df = ds("ch_seco_gdp", structure="gdp", type="nom", seas_adj="csa",
        start="2000-01-01")
# A single-series dataset: no dimension arguments
df = ds("ch_kof_barometer")

Other software

/series.csv returns a CSV file, so any tool that can open a URL can read a series directly, with the same dims, from and to filters. The Use this series card on each dataset page generates the snippet for your current selection.

# Stata
import delimited "https://dataseries.org/series.csv?dataset=ch_seco_gdp&dims=structure=gdp;type=nom;seas_adj=csa", clear
# MATLAB
T = readtable("https://dataseries.org/series.csv?dataset=ch_kof_barometer");
# Julia
using CSV, DataFrames, Downloads
df = CSV.read(Downloads.download("https://dataseries.org/series.csv?dataset=ch_kof_barometer"), DataFrame)
# Excel / Power Query: Data > Get Data > From Web, then paste the URL (refreshes in place)
https://dataseries.org/series.csv?dataset=ch_kof_barometer
# SAS
filename ds url "https://dataseries.org/series.csv?dataset=ch_kof_barometer";
proc import file=ds out=work.ds dbms=csv replace; run;
# curl / shell
curl "https://dataseries.org/series.csv?dataset=ch_kof_barometer"

Downloads

Each dataset page downloads the current selection, with any transform applied, as CSV, Excel or JSON, and the chart as PNG or SVG. The complete files for each dataset (CSV data, JSON metadata and a Parquet copy) are in the dataseries-data repository.

Embedding charts

Charts can be embedded in any web page with an iframe. The Embed tab of the Use this series card generates the snippet for your current selection. Embedded charts update when new data arrives.

<iframe
  src="https://dataseries.org/d/ch_kof_barometer?embed=1"
  width="100%" height="580" style="border:0;border-radius:12px"
  loading="lazy" title="KOF Barometer, dataseries.org">
</iframe>

Data licenses →