KOF Account

In order to access KOF data, you need a KOF account. On request, KOF will create an account for you with a given username and a temporary password.

On your first log in, you will be asked to set a password and to complete your profile. Please provide your email address and your first and last name. The email address can be used to log in to your account (besides the username). Optionally, you can add email addresses to which notification emails will be sent. For example, you will receive a notification email when new files are exported to your S3 bucket (see Object Storage) or if revisions in the exported time series are to be expected.

KOF Object Storage

KOF is hosting its own S3-compatible object storage. We will create an S3 bucket for you if you receive

data other than time series
large amounts of data

The name of your S3 bucket will be your username.

Accessing your S3 bucket

Go to the KOF minio console. Click on the KOF Login button. Log in with your KOF account credentials. You should now see your S3 bucket. Click on the bucket to view its contents.

Download files manually

In the KOF minio console, click on the file you want to download (you can also select multiple files). A context menu will appear on the right. Click on Download. If you want to share the download with others, you can create a temporary download link by clicking on Share.

Download files from notification email

If you receive a notification email from KOF Data as soon as a file has been uploaded to your S3 bucket, the email will include an unprotected link to the file. Click on the link to download the file. The link is valid for 7 days only. For a later download, go to the KOF minio console and download the file manually.

Download files programmatically

First, you need to create an access key in the KOF minio console. In the navigation bar to the left, click on Access Keys. Then, click on the button Create access key to the right. You are now presented with a form to fill out. The Access Key and Secret Key fields are automatically generated. You can keep the default values or fill in your own. All the other fields are optional and can safely be ignored. Click on Create and make sure to write down the Secret Key.

R

Install the aws.s3 package with

install.packages("aws.s3")

You can download a file in your S3 bucket with

aws.s3::get_object(
  base_url = "minio-api.kof.ethz.ch",
  bucket = USERNAME,
  file = FILENAME,
  object = FILENAME,
  key = ACCESS_KEY,
  secret = SECRET_KEY,
  region ="",
  show_progress = T)

Where USERNAME is your KOF account username, ACCESS_KEY is the access key you created in the minio console and SECRET KEY is the corresponding secret key. Instead of providing the arguments key and secret with every aws.s3::get_object function call, you can also set the following environment variables

Sys.setenv(
  "AWS_ACCESS_KEY_ID" = ACCESS_KEY,
  "AWS_SECRET_ACCESS_KEY" = SECRET_KEY,
  "AWS_S3_ENDPOINT" = "minio-api.kof.ethz.ch")

Python

Install the minio package with

pip3 install minio

You can download a file in your bucket with

from minio import Minio

client = Minio(
  endpoint = "minio-api.kof.ethz.ch",
  access_key = ACCESS_KEY,
  secret_key = SECRET_KEY
)

client.fget_object(
  bucket_name = USERNAME,
  object_name = FILENAME,
  file_path = FILENAME
)

Where USERNAME is your KOF account username, ACCESS_KEY is the access key you created in the minio console and SECRET KEY is the corresponding secret key.

MinIO Client

Install the MinIO Client on Linux with

curl https://dl.min.io/client/mc/release/linux-amd64/mc \
  --create-dirs \
  -o $HOME/minio-binaries/mc

chmod +x $HOME/minio-binaries/mc
export PATH=$PATH:$HOME/minio-binaries/

Create an alias for the KOF minio service with

mc alias set kof-minio https://minio-api.kof.ethz.ch $ACCESS_KEY $SECRET_KEY

Then download a file with

mc get kof-minio/$USERNAME/$FILENAME .

KOF Time Series Database API v2

Version 2 of the KOF Time Series Database API implements all functionality of the KOF Time Series Database. In particular, you can download time series data and metadata in CSV, XLSX or JSON format, read time series release information, manage time series collections and check your download quota. A detailed documentation of all API endpoints is available here.

If you are an R user, we recommend using the tsdbapi R package to interact with the API. The package functions conveniently transform the API responses into R data types, such as ts, xts, data.frame and list. For Python users, we provide the tsdbapi Python package. It transforms the API responses into a polars.DataFrame or Python dict. Currently, the Python package offers less functionality than the R package.

Basic Usage

The link below downloads the time series with the keys ch.kof.globalbaro.coincident and ch.kof.globalbaro.leading as a CSV file.

https://tsdb-api.kof.ethz.ch/v2/ts?keys=ch.kof.globalbaro.coincident,ch.kof.globalbaro.leading&mime=csv

Other supported mime types are xlsx, html and json (default).

Authorization

If you click on the link 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:

https://tsdb-api.kof.ethz.ch/v2/ts?keys=ch.kof.barometer&mime=csv&access_type=public

The time series ch.kof.barometer is a public time series.

For programmatic access without user log in, you must use an API key. The link below creates an API key for your user and returns it in the response. Any previously created API key will be overwritten and therefore invalidated. Store the newly created API key securely because it cannot be retrieved later.

https://tsdb-api.kof.ethz.ch/v2/users/self/api-key

Pass the API key in the request header in order to get access. The curl call below uses a given API key to download the time series ch.kof.barometer as a CSV file.

curl -X GET "https://tsdb-api.kof.ethz.ch/v2/ts?keys=ch.kof.barometer&mime=csv" \
     -H "x-api-key: YOUR_API_KEY" \
     -o ts_data.csv

Vintages

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, the ts-endpoint returns the most recent vintage of a 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 on January 15, 2026.

https://tsdb-api.kof.ethz.ch/v2/ts?keys=ch.kof.barometer&valid_on=2026-01-15

For users with the 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.

Release information

The release information, including the release time, of the most recent time series vintage can be read with

https://tsdb-api.kof.ethz.ch/v2/ts/release?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

https://tsdb-api.kof.ethz.ch/v2/ts/release/future?keys=ch.kof.barometer

Note that the release times of a future vintages are not guaranteed and are subject to change (although changes are rare).

Download Quota

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

https://tsdb-api.kof.ethz.ch/v2/users/self/quota

Collections

To read an entire collection of time series use

https://tsdb-api.kof.ethz.ch/v2/collections/public/bs_indicator/ts

Every time series collection has an owner. In the link above, the owner is the user public. Use self instead of public to access your own collections.

You can list information on all collections visible to you with

https://tsdb-api.kof.ethz.ch/v2/collections

For users with the role extern, the includes all collections owned by the user himself and by the user public.

Metadata

The metadata of one or multiple time series can be downloaded with

https://tsdb-api.kof.ethz.ch/v2/ts/metadata?keys=ch.kof.barometer&locale=en&mime=csv

Other supported mime types are xlsx, html and json (default). The parameter locale, the ISO language code, is one of en, de, fr or it. To download the metadata of an entire collection of time series:

https://tsdb-api.kof.ethz.ch/v2/collections/public/bs_indicator/ts/metadata?locale=en&mime=csv

Advanced usage

Consult the swagger documentation for a detailed description of all API endpoints.

Transition from API v1 to API v2

With v1 of the API, the link for downloading a time series was:

https://datenservice.kof.ethz.ch/api/v1/main/ts?keys=ch.kof.globalbaro.coincident&mime=csv&apikey=MY_API_KEY

With v2, the link is

https://tsdb-api.kof.ethz.ch/v2/ts?keys=ch.kof.globalbaro.coincident&mime=csv

There is no apikey parameter anymore. Instead, you have to log in with your KOF account credentials or pass the API key in the request header (note that the v1 API key does not work with v2 and vice versa). For public time series, the v1 link looked like this:

https://datenservice.kof.ethz.ch/api/v1/public/ts?keys=ch.kof.barometer&mime=csv

With v2, there’s the access_type parameter instead:

https://tsdb-api.kof.ethz.ch/v2/ts?keys=ch.kof.barometer&mime=csv&access_type=public

The v1 link for reading a public collection of time series was

https://datenservice.kof.ethz.ch/api/v1/public/sets/bs_indicator

With v2, the link is

https://tsdb-api.kof.ethz.ch/v2/collections/public/bs_indicator/ts

For collections owned by yourself, the v1 link was

https://datenservice.kof.ethz.ch/api/v1/main/sets/MY_COLLECTION&apikey=MY_API_KEY

With v2, the link is

https://tsdb-api.kof.ethz.ch/v2/collections/self/MY_COLLECTION/ts

For downloading metadata, of either individual time series or a time series collection, the v1 links were

https://datenservice.kof.ethz.ch/api/v1/public/metadata?keys=ch.kof.barometer&locale=en&mime=csv

https://datenservice.kof.ethz.ch/api/v1/public/metadata/sets/bs_indicator?locale=en&mime=csv

With v2, they are

https://tsdb-api.kof.ethz.ch/v2/ts/metadata?keys=ch.kof.barometer&locale=en&mime=csv

https://tsdb-api.kof.ethz.ch/v2/collections/public/bs_indicator/ts/metadata?locale=en&mime=csv

KOF Time Series Database API v1

Version 1 of the KOF Time Series Database API is deprecated. Please migrate to version 2 of the API as soon as possible

The kofdata R package is deprecated. Please migrate to the tsdbapi R package as soon as possible. The functions kofdata::download_cached_files and kofdata::list_cached_files have no equivalent in the tsdbapi package. Instead, use the aws.s3 package for the file download as described here.

The documentation of the deprecated KOF Time Series Database API v1 can be found here.

KOF Time Series Explorer

In order to find a specific time series you need, or to get an overview over the time series available as a data service subscriber, you can use the KOF Time Series Explorer. For the non-publicly available time series, the Time Series Explorer will only show a preview with the latest 2 years of data missing. Log in with your KOF account to view and download the full time series through the Time Series Explorer.