KOF Datenservice REST API v1

Welcome to the documentation of the KOF Datenservice REST API. This API is a dynamic service to provide regularly updated downloads of time series published by the KOF Swiss Economic Institute. The API offers multiple output formats and is designed to be used by machines and humans alike.

Endpoints

The main address of the KOF Datenservice is https://datenservice.kof.ethz.ch. This address has 3 main endpoints that serve time series from the KOF Database as well as pre-defined datasets.

/api/v1/public/ts

Time series which are available through the /public/ts endpoint are available without restrictions. This endpoint is mostly used to publish KOF indicators such as the KOF Barometer or the KOF Surprise Indicator.

Example use

https://datenservice.kof.ethz.ch/api/v1/public/ts?keys=kofbarometer

A comma separated list of keys parameters allow to query multiple time series and return them in a single file.

/api/v1/public/sets

The datenservice API know pre-defined sets of time series. So instead of composing multiple keys again and again, you can fall back to these pre-defined sets of data that are often requested together. Sets are handsome for non-bulk data exports of regularly requested data. For bulk delivery of larger datasets, please refer to the datasets endpoint below, which stores pre-cached dataset based on your individual demand.

Example use

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

/api/v1/main/ts

The /main/ts endpoint provides publicly available, but volume restricted time series. You will need an API Key and a valid user account to obtain data from this endpoint.

Example use

https://datenservice.kof.ethz.ch/api/v1/main/ts?keys=ch.bfs.bpi.2010.baugewerbe.total,ch.bfs.bpi.2010.bfsr7.baugewerbe.total&apikey=YOUR_API_KEY

/api/v1/main/sets

The datenservice API know pre-defined sets of time series. So instead of composing multiple keys again and again, you can fall back to these pre-defined sets of data that are often requested together. Sets are handsome for non-bulk data exports of regularly requested data. For bulk delivery of larger datasets, please refer to the datasets endpoint below, which stores pre-cached dataset based on your individual demand. For usage example of this setup see the public version of this endpoint above.

/api/v1/user/<|YOUR_USERNAME|>/datasets

This endpoints contains individually composed, exported datasets. The basic endpoint returns a JSON object containg all file names that are available to a specific user. If a valid file name is provided the file will be downloaded.

Example use

# File list
https://datenservice.kof.ethz.ch/api/v1/user/<YOUR_USERNAME>/datasets?apikey=YOUR_API_KEY

# Download file
https://datenservice.kof.ethz.ch/api/v1/user/<YOUR_USERNAME>/datasets/SOME_FILE.xlsx?apikey=YOUR_API_KEY

/api/v1/metadata?key=A_SINGLE_TIME_SERIES

The metadata endpoint provides meta information for single time series. This endpoint is public. Meta data are provided for all KOF surveys in greater detail. We are currently working on multi-lingual meta information an meta information for non-KOF series.

Parameters

The endpoints described above accept a handful of paramerts. The following table gives an overview of all available parameters. Note that not all endpoints accept all parameters. E.g. a datasets endpoint does not process a time series specific lastn parameter. The first parameter is added to the endpoint using a question mark ?. All further parameters are added using an ampersand &.

parameter description
keys comma separated list of keys. Only available to ts endpoints. Mandatory to ts endpoints.
mime return type: json, csv, xlsx, html. Defaults to json
lastn Only return the lastn observations of a series.
fname provide a custom file for the downloaded file.

Advanced Use

The KOF Datenservice is designed to foster automated processing. For example, interactive online visualizations of time series can be set up easily using the KOF Datenservice API as a data source. Popular javascript libraries such as dygraphs can directly visualize time series given the server you run these libraries on allows CORS for datenservice.kof.ethz.ch.

Code Snippets (Example)

Querying data from an REST API is easy. The following section provides a few code lines of example code for some of data science's most popular languages.

R language for Statistical Computation

Make sure the R extension packages curl and jsonlite are installed. KOF plans to release an R wrapper package for the Datenservice REST API which accepts keys and API Keys and returns time series objects.

library(curl)
library(jsonlite)
con <- curl("https://datenservice.kof.ethz.ch/api/v1/main/ts?keys=ch.bfs.ip.f12.prod_a.sector_group.b.cmpym_pct&apikey=YOUR_API_KEY")

dframe <- fromJSON(con)

START_YEAR <- as.numeric(format(as.Date(paste0(dframe[-1,1],"-01"))[1],"%Y"))
START_PERIOD <- as.numeric(format(as.Date(paste0(dframe[-1,1],"-01"))[1],"%m"))
FRQ <- 12

ts(dframe[-1,2],start=c(START_YEAR,START_PERIOD),frequency = FRQ)

Python

import requests
import json
url = 'https://datenservice.kof.ethz.ch/api/v1/main/ts?keys=ch.bfs.ip.f12.prod_a.sector_group.b.cmpym_pct&apikey=YOUR_API_KEY'
out = requests.get(url)
str(out.text)

STATA

import delimited "https://datenservice.kof.ethz.ch/api/v1/public/ts?keys=kofbarometer&mime=csv", clear
gen _date = monthly(date, "YM")
drop date
rename _date date
format date %tm

Microsoft Excel

Microsoft Excel can consume data from the KOF API directly through its read-from-web feature. Once connected an .xlsx spreadsheet can automatically be refreshed by hitting the refresh button within Excel. To set up a new query, simply Select New Query -> From Other Sources -> From Web from the data tab.

query from web

Continue to paste the URL with all its parameters including your API Key (if needed). Make sure mime is set to csv, by adding a mime=csv parameter to the URL.

query from web

Excel will query the KOF Datenservice API and put all data received into a spreadsheet. Dates are automatically recognized and the resulting tables can be sorted by its variables. Finally click load to actually put the data into your spreadsheet.

query from web

Note that this feature was tested with Microsoft Excel 2016 on Windows. Earlier versions or other spreadsheet software might be organized in slightly different fashion. If your version does not support this process, (VBA) macros using the urlmon lib or queryTables are a workaround.

FAQ

https://datenservice.kof.ethz.ch/static/keyexplorer/index.html

Even if you are not logged in you can browse the Key Explorer. If you cannot find a particular time series or if you have further questions, please contact datenservice [ at ] kof.ethz.ch.