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.
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.
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.
A comma separated list of keys parameters allow to query multiple time series and return them in a single file.
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.
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.
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.
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.
# 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
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.
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 &.
|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.|
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")),"%Y")) START_PERIOD <- as.numeric(format(as.Date(paste0(dframe[-1,1],"-01")),"%m")) FRQ <- 12 ts(dframe[-1,2],start=c(START_YEAR,START_PERIOD),frequency = FRQ)
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)
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 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.
- 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. For starters we offer the KOF Key Explorer. The tree shown in the Key Explorer provides a browsable visualization of our hierarchical time series keys. The explorer can be found at:
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.
- 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.