The tsdbapi package is a Python wrapper for the KOF Time Series DB API. The functionality of the package includes reading time series data, metadata and release information from the KOF time series database. At the moment, the functionality of the package is quite limited (in contrast to the R package). If you miss a function for a particular API endpoint, check for updates regularly. The package functions convert the JSON data returned by the KOF Time Series DB API to either a Python dict or a polars.DataFrame.
Install the package with
pip install tsdbapi
Use the function read_ts to read time series from the KOF time series database. The code below reads the time series with the key ch.kof.barometer and returns it as a polars.DataFrame.
from tsdbapi import read_ts
read_ts(ts_keys="ch.kof.barometer")
Read multiple time series at the same time by providing a list of keys:
read_ts(ts_keys=["ch.kof.globalbaro.leading","ch.kof.globalbaro.leading"])
When running the code above, you will be redirected to KOF's identity provider (Keycloak), where you have to log in with your KOF credentials (unless you are already logged in). If you do not have a KOF account, you can still access the public time series in the KOF time series database by setting the access_type to public:
from tsdbapi import read_ts, set_config
set_config(access_type = "public")
read_ts("ch.kof.barometer")
The time series ch.kof.barometer is a public time series.
If you want to avoid user login, for example in a non-interactive session, you must use an offline token. An offline token is a refresh token that does not expire and can be used to retrieve access tokens. Request an offline token with:
from tsdbapi import get_offline_token
mytoken = get_offline_token()
print(mytoken)
The returned offline token must be treated like a secret!
Use the offline token by setting the environment variable TSDBAPI_OAUTH_OFFLINE_TOKEN before running a Python script. Alternatively, you can set the corresponding package configuration option:
from tsdbapi import read_ts, set_config
set_config(oauth_offline_token="mytoken")
read_ts(ts_keys="ch.kof.barometer")
Every time series can have multiple vintages (or versions). A time series vintage is based on the data available at its vintage date.
By default, read_ts returns the most recent vintage (or version) of the time series.
To specify a different vintage, use the valid_on parameter. The code below reads the KOF barometer vintage based on the data available at January 15, 2026.
from tsdbapi import read_collection_ts
from datetime import date
read_ts("ch.kof.barometer", valid_on = date(2026, 1, 15))
For users with role extern (everyone not employed at KOF), a time series vintage is only visible once it has been officially released, hence its data, including its vintage date, can only be read after release. A time series vintage is usually released several days after its vintage date.
The release information, including the release time, of the most recent time series vintage can be read with
from tsdbapi import read_ts_release
read_ts_release(ts_keys="ch.kof.barometer")
Use the valid_on parameter to specify a different vintage. For users with the role extern, only vintages that have been released are visible. However, the release information of future, yet to be released time series vintages can be read with
from tsdbapi import read_ts_release_future
read_ts_release_future(ts_keys="ch.kof.barometer")
Note that he release times of future vintages are not guaranteed and are subject to change (although changes are rare).
If you are a KOF data service subscriber, the number of time series downloads (reads) per year is limited by a quota. You can check your annual download quota and the number of time series downloads remaining in the current subscription year with
from tsdbapi import read_user_quota
read_user_quota()
To read an entire collection of time series use
from tsdbapi import read_collection_ts
read_collection_ts(collection="bs_indicator", owner="public")
Every time series collection has an owner. By default, the owner is assumed to be yourself owner="self".
You can list all collections visible to you with
from tsdbapi import read_collection_ts
list_collections()
For users with the role extern, the includes all collections owned by the user himself and by the user public.
The metadata of one or multiple time series can be read with
from tsdbapi import read_metadata_ts
read_ts_metadata(ts_keys="ch.kof.barometer")
To read the metadata of an entire collection of time series:
from tsdbapi import read_collection_ts_metadata
read_collection_ts_metadata(collection="bs_indicator", owner="public")
Consult the package help for a detailed documentation of all available functions.