Home

Wrapping a KaMu API endpoint

There's a pretty good documentation available for the KaMu API and wrapping each endpoint (resource) into a R function in finpar is relatively straightforward. Function query_kamu_api() takes care of most of the boilerplate code and you're left with A) providing the necessary parameters and B) dealing with the response data. Here's a generic enough example of wrapping an endpoint.

Select a suitable endpoint from http://dev.kansanmuisti.fi/static/api_v1_doc/index.html. For demonstration we'll use term. Note that the wrapping for this endpoint is already implement in term.R.

The documentation gives you the endpoint in the form /api/v1/term/. Part /api/v1/ is already hard coded in query_kamu_api() so you only need to provide the string "term" to identify the endpoint.

You will potentially also need to provide query parameters as a list to query_kamu_api(). For example, by default the API will limit the response to 20 items, which is less than the total of 36 terms that the Finnish Parliament has had. You can check the the total count of items by opening the complete query URL in your browser, i.e. in case of "term" http://dev.kansanmuisti.fi/api/v1/term/ (browser plugins such as [JSONView] (https://chrome.google.com/webstore/detail/jsonview/chklaanhfefbnpoihckbnefhakgolnmc?hl=en) for Chrome highly recommended). You can provide the query parameters as a list to query_kamu_api(), for example increasing the response limit:

query_kamu_api("term", query=list(limit=40))

Next job is to deal with the response data. In case of "term" this is relatively straightforward as the response if a list of same length vectors, which can easily be transformed into a dataframe. Note however, that the response data structure can be a nested heterogeneous list in which case it's up to you to decide what to do with the data. Options include at least passing it on as-is list or then somehow parsing the list into a (potentially redundant) dataframe.