api_call.R

###############################################################
########################## i14y APIs ##########################
###############################################################

#' Get a codelist based on an identifier
#'
#' @param identifier  the codelist's identifier
#' @param export_format the export's format
#' Available are CSV, XLSX, SDMX-ML or JSON.
#' @param version_format the export format's version
#' (2.0 or 2.1 when format is SDMX-ML).
#' @param annotations flag to include annotations
#'
#' @return response based on the export format
#' @export
#'
#' @examples
#' get_codelist(identifier='CL_NOGA_SECTION')
get_codelist <- function(identifier,
                         export_format = "SDMX-ML",
                         version_format = 2.1,
                         annotations = FALSE) {
  api <- api_class(
    api_type = "codelist",
    export_format = export_format,
    parameters = glue("annotations={tolower(annotations)}"),
    id = identifier
  )
  api$get_response()
}


#' Get the display information for the available configured content
#'
#' @return the configured content's display information
#' @export
#'
#' @examples
#' get_content_configuration()
get_content_configuration <- function() {
  api <- api_class(api_type = "content_configuration")
  api$get_response()
}



#' Get a nomenclature information based on its identifier
#'
#' @param identifier the nomenclature's identifier
#'
#' @return  the nomenclature's information
#' @export
#'
#' @examples
#' get_identifier_content(identifier='HCL_CH_ISCO_19_PROF')
get_identifier_content <- function(identifier) {
  api <- api_class(
    api_type = "content_configuration_identifier",
    id = identifier
  )
  api$get_response()
}




#' Get the dcat dataset description
#'
#' @param identifier the dataset's identifier
#' @param language the language of the response data
#' Available are 'fr', 'de', 'it', 'en'.
#'
#' @return dataset description
#' @export
#'
#' @examples
#' get_dataset_description(identifier='HCL_NOGA', language='de')
get_dataset_description <- function(identifier, language = "fr") {
  api <- api_class(
    api_type = "dcat_dataset_description",
    id = identifier,
    language = language
  )
  api$get_response()
}



#' Get the dcat dataset information
#'
#' @param identifier the dataset's identifier
#' @param language  the language of the response data
#' Available are 'fr', 'de', 'it', 'en'.
#'
#' @return dataset's information
#' @export
#'
#' @examples
#' get_dataset_information(identifier='HCL_NOGA', language='de')
get_dataset_information <- function(identifier, language = "en") {
  api <- api_class(
    api_type = "dcat_dataset_information",
    id = identifier,
    language = language
  )
  api$get_response()
}



#' Get the data structure
#'
#' @param identifier the dataset's identifier
#' @param language  the language of the response data
#' Available are 'fr', 'de', 'it', 'en'.
#'
#' @return data structure
#' @export
#'
#' @examples
#' get_data_structure(identifier='HCL_NOGA', language='it')
get_data_structure <- function(identifier, language = "en") {
  api <- api_class(
    api_type = "dcat_data_structure",
    id = identifier,
    language = language
  )
  api$get_response()
}



#' Get the nodes of a path within a nomenclature
#'
#' @param identifier the nomenclature's identifier
#' @param path the path leading to the nodes
#' @param filters the filters to apply
#' @param language  the language of the response data
#' Available are 'fr', 'de', 'it', 'en'.
#' 
#' @return nodes and their metadata
#' @export
#'
#' @examples
#' get_nomenclature_path_nodes(identifier='HCL_CH_ISCO_19_PROF', path='.', filters=my_filters)
get_nomenclature_path_nodes <- function(identifier,
                                        path = ".",
                                        filters = "",
                                        language = "en") {
  api <- api_class(
    api_type = "nomenclature_path_nodes",
    id = identifier,
    path = path,
    parameters = stringify(filters),
    language = language
  )
  api$get_response()
}


#' Get one level of a nomenclature
#'
#' @param identifier nomenclature's identifier
#' @param filters additionnal filters
#' @param level_number level to export
#' @param language  the language of the response data
#' Available are 'fr', 'de', 'it', 'en'.
#' @param annotations flag to include annotations
#'
#' @return dataframe with 3 columns
#' (Code, Parent and Name in the selected language)
#' @export
#'
#' @examples
#' get_nomenclature_one_level(identifier='HCL_CH_ISCO_19_PROF', filters=my_filters, level_number=2)
get_nomenclature_one_level <- function(identifier,
                                       filters,
                                       level_number = 1,
                                       language = "en",
                                       annotations = FALSE) {
  parameters <- glue::glue("language={language}&level={level_number}&annotations={tolower(annotations)}&{stringify(filters)}")
  print(parameters)
  api <- api_class(
    api_type = "nomenclature_one_level",
    id = identifier,
    parameters = parameters,
    export_format = "CSV"
  )
  api$get_response()
}


#' Get multiple levels of a nomenclature (from `level_from` to `level_to`)
#'
#' @param identifier nomenclature's identifier
#' @param filters additionnal filters
#' @param level_from the 1st level to include
#' @param level_to the last level to include
#' @param language  the language of the response data
#' Available are 'fr', 'de', 'it', 'en'.
#' @param annotations flag to include annotations
#'
#' @return dataframe columns
#' from `level_from` to `level_to` codes
#' @export
#'
#' @examples
#' get_nomenclature_multiple_levels(identifier='HCL_CH_ISCO_19_PROF', filters=my_filters, level_from=2, level_to=5)
get_nomenclature_multiple_levels <- function(identifier,
                                             filters,
                                             level_from = 1,
                                             level_to = 2,
                                             language = "en",
                                             annotations = FALSE) {
  parameters <- glue::glue("language={language}&levelFrom={level_from}&levelTo={level_to}&annotations={tolower(annotations)}&{stringify(filters)}")
  api <- api_class(
    api_type = "nomenclature_multiple_levels",
    id = identifier,
    parameters = parameters,
    export_format = "CSV"
  )
  api$get_response()
  ###############################################################
  # TODO: post processing in R
  ###############################################################
}


#' Search query within a nomenclature
#'
#' @param identifier nomenclature's identifier
#' @param query the search query
#' @param page_number the number of the result page to return
#' @param page_size the size of each page result
#' @param filters additionnal filters
#' @param language  the language of the response data
#' Available are 'fr', 'de', 'it', 'en'.
#'
#' @return the query result
#' @export
#'
#' @examples
#' query_nomenclature(identifier='HCL_CH_ISCO_19_PROF', query='SELECT *', page_number=5, page_size=2, filters=my_filters)
query_nomenclature <- function(identifier,
                               query,
                               page_number,
                               page_size,
                               filters,
                               language = "en") {
  parameters <- glue::glue("query={URLencode(query)}&page={page_number}&pageSize={page_size}&language={language}&{stringify(filters)}")
  api <- api_class(
    api_type = "nomenclature_search",
    id = identifier,
    parameters = parameters
  )
  api$get_response()
}



###############################################################
########################## dcat APIs ##########################
###############################################################


#' List all agents
#'
#' @return all agents
#' @export
#'
#' @examples
#' dcat_list_all_agents()
dcat_list_all_agents <- function() {
  api <- api_class(
    api_type = "agents_list",
    root_url = DCAT_URL
  )
  api$get_response()
}


#' Get the agent with the corresponding agent id
#'
#' @param agent_id agent's id
#'
#' @return agent with this id
#' @export
#'
#' @examples
#' dcat_get_agent_from_id(agent_id='xx')
dcat_get_agent_from_id <- function(agent_id) {
  api <- api_class(
    api_type = "agent_id",
    root_url = DCAT_URL,
    id = agent_id
  )
  api$get_response()
}


#' List all datasets
#'
#' @return all datasets
#' @export
#'
#' @examples
#' dcat_list_all_datasets()
dcat_list_all_datasets <- function() {
  api <- api_class(
    api_type = "dataset_list",
    root_url = DCAT_URL
  )
  api$get_response()
}


#' Get all distributions for the dataset with the corresponding dataset id
#'
#' @param dataset_id dataset's id
#'
#' @return distributions for the dataset with dataset's id
#' @export
#'
#' @examples
#' dcat_get_distributions_from_dataset_id(dataset_id='xx')
dcat_get_distributions_from_dataset_id <- function(dataset_id) {
  api <- api_class(
    api_type = "dataset_id_distributions",
    root_url = DCAT_URL,
    id = dataset_id
  )
  api$get_response()
}


#' Get the dataset with the corresponding id
#'
#' @param dataset_id dataset's id
#'
#' @return the dataset
#' @export
#'
#' @examples
#' dcat_get_dataset_from_id(dataset_id='xx')
dcat_get_dataset_from_id <- function(dataset_id) {
  api <- api_class(
    api_type = "dataset_id",
    root_url = DCAT_URL,
    id = dataset_id
  )
  api$get_response()
}


#' Get the dataset with the corresponding identifier
#'
#' @param identifier dataset's identifier
#'
#' @return the dataset
#' @export
#'
#' @examples
#' dcat_get_dataset_from_identifier(identifier='xx')
dcat_get_dataset_from_identifier <- function(identifier) {
  api <- api_class(
    api_type = "dataset_identifier",
    root_url = DCAT_URL,
    id = identifier
  )
  api$get_response()
}


#' Get all distributions for the dataset with the corresponding identifier.
#'
#' @param identifier dataset's identifier
#'
#' @return all distributions for the dataset with 
#' the corresponding dataset identifier
#' @export
#'
#' @examples
#' dcat_get_distributions_from_dataset_identifier(identifier='xx')
dcat_get_distributions_from_dataset_identifier <- function(identifier) {
  api <- api_class(
    api_type = "dataset_identifier_distributions",
    root_url = DCAT_URL,
    id = identifier
  )
  api$get_response()
}


#' List all distributions
#'
#' @return all distributions
#' @export
#'
#' @examples
#' dcat_list_all_distributions()
dcat_list_all_distributions <- function() {
  api <- api_class(
    api_type = "distributions_list",
    root_url = DCAT_URL
  )
  api$get_response()
}


#' Get the distribution with the corresponding id
#'
#' @param distribution_id distribution's id
#'
#' @return the distribution
#' @export
#'
#' @examples
#' dcat_get_distribution_from_id(distribution_id='xx')
dcat_get_distribution_from_id <- function(distribution_id) {
  api <- api_class(
    api_type = "distribution_id",
    root_url = DCAT_URL,
    id = distribution_id
  )
  api$get_response()
}