In Eleftheria94/AdvancedRlab5: Advanced R Programming Lab 5 Assignment

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  echo = TRUE
)

library(httr)
library(jsonlite)
library(AdvancedRlab5)

About the Kolada API

The Kolada API provides a web-service that accesses Key Performance Indicators (KPI) of Swedish municipalities and organizational units. The open source database gives user access to approximately 5.000 figures, which can be useful for data analysis. Within the database we can find two types of data:

1. Municipal data

2. Organizational unit data

A detailed description can be found on the following website: https://github.com/Hypergene/kolada/blob/master/README.rst

Code appendix - The koladabindings.r file

# Modified template from Best Practices for API Packages 
# https://cran.r-project.org/web/packages/httr/vignettes/api-packages.html
require(httr)
require(jsonlite)


#' kolada_api handles the API link
#' 
#' @param path The path of the API url.
#' 
#' @return Returns a list that contains all data for the given API.
#' @export
#'
kolada_api <- function(path) {

  #Add v2 to path
  path = paste("v2/",path,sep="")
  url <- modify_url("http://api.kolada.se/v2/", path = path)

  #Check response format is json
  resp <- GET(url)
  print(resp)
  if (http_type(resp) != "application/json") {
    stop("API did not return json", call. = FALSE)
  }

  #Json parser-Deserialization
  parsed <- jsonlite::fromJSON(content(resp, "text"), simplifyVector = FALSE)

  # Check Server Response 
  if (status_code(resp) != 200) {
    stop(
      sprintf(
        "Kolada API request failed [%s]\n%s\n<%s>", 
        status_code(resp),
        parsed$message,
        parsed$documentation_url
      ),
      call. = FALSE
    )
  }

  #Return a useful object
  structure(
    list(
      content = parsed,
      path = path,
      response = resp
    ),
    class = "kolada_api"
  )
}

#' Get municipalities
#' 
#' @param name The name of the municipality we want to access.
#' 
#' @return Returns a data frame that contain all municipalities.
#' @export
#'
get_municipality = function(name){
  #http://api.kolada.se/v2/municipality?title=lund

  stopifnot(is.character(name))
  stopifnot(!grepl("/",name, fixed=TRUE)) # checking if a string is in another string

  name = URLencode(name)
  response = kolada_api(paste("municipality?title=",name,sep=""))
  return(response$content)
}

#' Get a municipality's organizational units
#' 
#' @param name The name/code id of the municipality's organizational unit we want to access.
#' 
#' @return Returns a data frame that contains all organizational units of a municipality.
#' @export
#'
get_municipality_groups = function(name){
  #http://api.kolada.se/v2/ou?municipality=1280

  stopifnot(is.character(name))
  stopifnot(!grepl("/",name, fixed=TRUE))

  name = URLencode(name)
  response = kolada_api(paste("municipality?ou=",name,sep=""))
  return(response$content)
}

#' Get KPI
#'
#' @param name The name of the kpi we want to access.
#' 
#' @return Returns a data frame that contains for a specific KPI with its id and description.
#' @export
#'
get_kpi = function(name){
  #http://api.kolada.se/v2/kpi?title=kvinnofridskränkning

  stopifnot(is.character(name))
  stopifnot(!grepl("/",name, fixed=TRUE))

  name = URLencode(name)
  response = kolada_api(paste("kpi?title=",name,sep=""))
  return(response$content)
}

#' Get KPI groups
#' 
#' @param name The name of the group we want to access.
#' 
#' @return Returns a data frame that contains information about a specific kpi group.
#' @export
#'
get_kpi_groups = function(name){
  #http://api.kolada.se/v2/kpi_groups?title=kostnad

  stopifnot(is.character(name))
  stopifnot(!grepl("/",name, fixed=TRUE))

  name = URLencode(name)
  response = kolada_api(paste("kpi_groups?title=",name,sep=""))
  return(response$content)
}

#' Get Search Results
#' 
#' @param kpi_list Id of the KPIs as a list.
#' @param municipality_list Id of the municipality.
#' @param year_list The years to get.
#' 
#' @return Returns a data frame that contains data about KPIs in a given municipality by a specific (user-defined) year.
#' @export
#'
get_search_results = function(kpi_list=NULL, municipality_list=NULL,year_list=NULL){
  #http://api.kolada.se/v2/data/kpi/N07402/municipality/1280/year/2011

  params = list(kpi=kpi_list,
             municipality=municipality_list,
             year=year_list)

  #Filter unused arguments
  params[sapply(params, is.null)] = NULL

  #Input checking
  sapply(params, function(x) stopifnot(is.list(x)))

  #Translate R term list into api term list
  search_terms = sapply(params, function(x) paste(x,collapse=","))

  #Build path from search terms
  path = paste(lapply(names(search_terms), function(x) paste(x,search_terms[x], sep="/"))
        ,collapse = "/")

  response = kolada_api(paste("data/", path,sep=""))
  return(response$content)
}

get_municipality()

A method call that contains information about the municipalities in the API.

head(get_municipality())

get_municipality_groups()

A method call that contains data about all organizational units of a municipality.

head(get_municipality_groups())

get_kpi()

A method call that contains information for a specific KPI with its id and description.

head(get_kpi())

get_kpi_groups()

A method call that contains information about a specific KPI group.

head(get_kpi_groups())

get_search_results()

A method call that contains data about KPIs in a given municipality by a specific (user-defined) year.

head(get_search_results())

Examples

The user can access the API by using the following example links included in the appendix. We recommend the use of Google Chrome and Mozilla Firefox.

1. http://api.kolada.se/v2/municipality?title=lund [2020-10-04]

2. http://api.kolada.se/v2/ou?municipality=1280 [2020-10-04]

3. http://api.kolada.se/v2/kpi?title=kvinnofridskränkning [2020-10-04]

4. http://api.kolada.se/v2/kpi_groups?title=kostnad [2020-10-04]

5. http://api.kolada.se/v2/data/kpi/N07402/municipality/1280/year/2011 [2020-10-04]

References

1. https://dittochdata.netlify.app/2018/06/27/ladda-hem-data-fr%C3%A5n-kolada-med-r/ [2020-10-04]

2. https://www.kolada.se/?_p=index/API [2020-10-04]

3. https://github.com/Hypergene/kolada/blob/master/README.rst [2020-10-04]

4. https://shiny.rstudio.com/tutorial/ [2020-10-04]

Eleftheria94/AdvancedRlab5 documentation built on Oct. 14, 2020, 6:54 a.m.