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
For R users, the easiest way to consume data from the KOF Datenservice API is to use the API wrapper package 'kofdata'. Installing the package is easy as 1-2-3 because it's an official CRAN package. Getting the kofbarometer is simply a matter of:
install.packages("kofdata") # only need to install once :)
library(kofdata)
get_time_series("kofbarometer")
Python
We also offer a Python API wrapper package which can be downloaded from github: https://github.com/KOF-ch/kofdata_py
The package will also soon be available as a pip installation.
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.
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.
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.
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
- How can I find keys? I know which series I want to download, but I don't know its key.
We're working to improve meta information and to provide an interface to query meta information and find keys. Currently this application is only accessible from inside KOF. We planning to publicly release the application during the later second half of 2020. If you are interested in an export of our data catalog before, please contact bannert [at] kof.ethz.ch - My .csv export does not recognize multiple columns -- it's all in the first column when I open it in MS Excel?
This happens due to internationally varying column delimiters. Regions that use commas as decimal delimiters cannot use them as column delimiters. Hence depending on your local settings your Excel might not recognize our semicolon delimited columns. However, this can easily be configured in general MS Excel configuration or when importing a file.
