Merge branch 'main' into feature/translate-data-ids

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: eesyapi
 Title: EES-y API
-Version: 0.2.1
+Version: 0.3.0
 Authors@R: 
     c(
     person("Rich", "Bielby", , "[email protected]", role = c("aut", "cre"),

NAMESPACE

@@ -4,23 +4,37 @@ export(api_url)
 export(api_url_pages)
 export(api_url_query)
 export(example_data_raw)
+export(convert_api_filter_type)
+export(example_geography_query)
 export(example_id)
+export(example_json_query)
 export(get_data_catalogue)
 export(get_dataset)
 export(get_meta)
 export(get_meta_response)
 export(get_publications)
 export(http_request_error)
 export(parse_api_dataset)
-export(parse_filter_in)
 export(parse_meta_filter_columns)
 export(parse_meta_filter_item_ids)
 export(parse_meta_location_ids)
 export(parse_meta_time_periods)
 export(parse_sqids_filters)
 export(parse_sqids_indicators)
+export(parse_tojson_filter)
+export(parse_tojson_filter_eq)
+export(parse_tojson_filter_in)
+export(parse_tojson_geographies)
+export(parse_tojson_indicators)
+export(parse_tojson_location)
+export(parse_tojson_params)
+export(parse_tojson_time_periods)
+export(parse_tourl_filter_in)
+export(post_dataset)
 export(query_dataset)
+export(validate_ees_filter_type)
 export(validate_ees_id)
 export(validate_page_size)
+export(validate_time_periods)
 export(warning_max_pages)
 importFrom(data.table,":=")

NEWS.md

@@ -1,6 +1,17 @@
+# eesyapi 0.3.0
+
+* Created capacity to query data using POST:
+  - `query_dataset()`: Now defaults to using POST instead of GET
+  - `post_dataset()`: Sends a query of a data set, either using a json file, json string or 
+  parameters
+* Updated how `example_id()` works to allow more complex examples
+
 # eesyapi 0.2.1
 
-* Updated `get_meta()` to work with new API meta output (addition of id alongside col_name and label)
+* Created initial `query_dataset()` function that queries a data set using `get_dataset()`
+* Created `get_dataset()` function that queries a data set using GET and URL parameters
+* Updated `get_meta()` to work with new API meta output (addition of id alongside col_name and 
+label)
 * Removed redundant function: `parse_meta_filter_columns()`
 * Hex logo added for documentation
 

R/api_url.R

@@ -24,8 +24,7 @@
 #' @param page Page number of query results to return
 #' @param api_version EES API version
 #' @param environment EES environment to connect to: "dev", "test", "preprod" or "prod"
-#' @param verbose Add extra contextual information whilst running
-#'
+#' @param verbose Run with additional contextual messaging, logical, default = FALSE
 #' @return A string containing the URL for connecting to the EES API
 #' @export
 #'

R/api_url_query.R

@@ -27,17 +27,17 @@ api_url_query <- function(
   eesyapi::validate_ees_id(indicators, level = "indicator")
   # Create the appropriate query strings for each level provided
   if (!is.null(time_periods)) {
-    query_time_periods <- eesyapi::parse_filter_in(time_periods, "time_periods")
+    query_time_periods <- eesyapi::parse_tourl_filter_in(time_periods, "time_periods")
   }
   if (!is.null(geographic_levels)) {
-    query_geographic_levels <- eesyapi::parse_filter_in(
+    query_geographic_levels <- eesyapi::parse_tourl_filter_in(
       geographic_levels,
-      type = "geographic_levels"
+      filter_type = "geographic_levels"
     )
   }
   if (!is.null(locations)) {
     eesyapi::validate_ees_id(locations, level = "location")
-    query_locations <- eesyapi::parse_filter_in(locations, type = "locations")
+    query_locations <- eesyapi::parse_tourl_filter_in(locations, filter_type = "locations")
   }
   if (!is.null(filter_items)) {
     # Note the idea below was to differentiate the logic between AND / OR based on whether
@@ -50,11 +50,14 @@ api_url_query <- function(
       for (filter_set in filter_items) {
         query_filter_items <- paste0(
           query_filter_items,
-          eesyapi::parse_filter_in(filter_set, type = "filter_items")
+          eesyapi::parse_tourl_filter_in(filter_set, filter_type = "filter_items")
         )
       }
     } else {
-      query_filter_items <- eesyapi::parse_filter_in(filter_items, type = "filter_items")
+      query_filter_items <- eesyapi::parse_tourl_filter_in(
+        filter_items,
+        filter_type = "filter_items"
+      )
     }
   }
   query_indicators <- paste0(

R/api_url_query_utils.R

@@ -5,25 +5,21 @@
 #' use with querying a data set via GET.
 #'
 #' @param items items to be included in the "in" statement
-#' @param type type of filter items being queried: "time_periods", "geographic_levels",
+#' @param filter_type type of filter being queried: "time_periods", "geographic_levels",
 #' "locations" or "filter_items"
 #'
 #' @return Query string for use in URL based API queries
 #' @export
 #'
 #' @examples
-#' parse_filter_in(c("2024|W11", "2024|W12"), type = "time_periods")
-parse_filter_in <- function(
+#' parse_tourl_filter_in(c("2024|W11", "2024|W12"), filter_type = "time_periods")
+parse_tourl_filter_in <- function(
     items,
-    type) {
-  if (!(type %in% c("time_periods", "geographic_levels", "locations", "filter_items"))) {
-    stop("type keyword should be one of time_periods, geographic_levels, locations or filter_items")
-  }
-  type_string <- type |>
-    stringr::str_replace("_item", "")
-  type_string <- gsub("_(\\w?)", "\\U\\1", type_string, perl = TRUE)
+    filter_type) {
+  eesyapi::validate_ees_filter_type(filter_type)
+  type_string <- eesyapi::convert_api_filter_type(filter_type)
   if (!is.null(items)) {
-    if (type %in% c("time_period", "locations")) {
+    if (filter_type %in% c("time_period", "locations")) {
       items <- gsub("\\|", "%7C", items)
     }
     paste0(

R/convert_api_filter_type.R

@@ -0,0 +1,23 @@
+#' Convert filter type to API filter type
+#'
+#' @description
+#' The API uses a slightly different naming convention for the different types of
+#' filters to what is used by analysts within data files. The function just converts
+#' from the file versions to the API versions.
+#'
+#' @inheritParams parse_tourl_filter_in
+#'
+#' @return String containing API friendly filter type descriptor
+#' @export
+#'
+#' @examples
+#' convert_api_filter_type("filter_items")
+#' convert_api_filter_type("geographic_levels")
+#' convert_api_filter_type("locations")
+#' convert_api_filter_type("filter_items")
+convert_api_filter_type <- function(filter_type) {
+  eesyapi::validate_ees_filter_type(filter_type)
+  filter_type <- filter_type |>
+    stringr::str_replace("_item", "")
+  gsub("_(\\w?)", "\\U\\1", filter_type, perl = TRUE)
+}

R/examples.R

@@ -15,92 +15,80 @@ example_id <- function(
     level = "dataset",
     environment = "dev",
     group = "public-api-testing") {
-  example_ids <- data.frame(
-    levels = c(
-      "publication",
-      "dataset",
-      "location_id",
-      "location_code",
-      "filter",
-      "filter_item",
-      "indicator",
-      "publication",
-      "dataset",
-      "location_id",
-      "location_code",
-      "filter",
-      "filter_item",
-      "indicator"
-    ),
-    environments = c(
-      "dev",
-      "dev",
-      "dev",
-      "dev",
-      "dev",
-      "dev",
-      "dev",
-      "dev",
-      "dev",
-      "dev",
-      "dev",
-      "dev",
-      "dev",
-      "dev"
-    ),
-    example_group = c(
-      "attendance",
-      "attendance",
-      "attendance",
-      "attendance",
-      "attendance",
-      "attendance",
-      "attendance",
-      "public-api-testing",
-      "public-api-testing",
-      "public-api-testing",
-      "public-api-testing",
-      "public-api-testing",
-      "public-api-testing",
-      "public-api-testing"
+  example_id_list <- list(
+    attendance = list(
+      dev = list(
+        publication = "b6d9ed96-be68-4791-abc3-08dcaba68c04",
+        dataset = "7c0e9201-c7c0-ff73-bee4-304e731ec0e6",
+        time_period = "2024|W23",
+        time_periods = c("2024|W21", "2024|W23"),
+        location_id = "NAT|id|dP0Zw",
+        location_ids = c("NAT|id|dP0Zw", "REG|id|rg3Nj"),
+        location_code = "NAT|code|E92000001",
+        filter = "4kdUZ",
+        filter_item = "5UNdi",
+        filter_items_long = list(
+          attendance_status = c("pmRSo", "7SdXo"),
+          attendance_type = c("CvuId", "6AXrf", "0k3T5", "YdkHK"),
+          education_phase = c("ThDPJ", "crH31"),
+          day_number = c("uLQo4"),
+          reason = c("bBrtT")
+        ),
+        filter_items_short = list(
+          attendance_status = c("pmRSo"),
+          attendance_type = c("CvuId", "6AXrf"),
+          education_phase = c("ThDPJ", "crH31"),
+          day_number = c("uLQo4"),
+          reason = c("bBrtT")
+        ),
+        indicator = "bqZtT"
+      )
     ),
-    examples = c(
-      "b6d9ed96-be68-4791-abc3-08dcaba68c04",
-      "7c0e9201-c7c0-ff73-bee4-304e731ec0e6",
-      "NAT|id|dP0Zw",
-      "NAT|code|E92000001",
-      "4kdUZ",
-      "5UNdi",
-      "bqZtT",
-      "d823e4df-626f-4450-9b21-08dc8b95fc02",
-      "830f9201-9e11-ad75-8dcd-d2efe2834457",
-      "LA|id|ml79K",
-      "NAT|code|E92000001",
-      "5mvdi",
-      "HsQzL",
-      "h8fyW"
+    `public-api-testing` = list(
+      dev = list(
+        publication = "d823e4df-626f-4450-9b21-08dc8b95fc02",
+        dataset = "830f9201-9e11-ad75-8dcd-d2efe2834457",
+        location_id = "LA|id|ml79K",
+        location_code = "NAT|code|E92000001",
+        filter = "01tT5",
+        filter_item = "wEZcb",
+        indicator = "PbNeb"
+      )
     )
   )
-  if (level == "all") {
-    return(example_ids)
+  if (!(group %in% names(example_id_list))) {
+    stop(paste0("Chosen group (", group, ") not found in examples list."))
+  }
+  if (!(environment %in% c("dev"))) {
+    stop(paste0("Chosen environment (", environment, ") should be one of: \"dev\"."))
+  }
+
+  group_examples <- example_id_list |>
+    magrittr::extract2(group) |>
+    magrittr::extract2(environment)
+
+  if (any(level == "all")) {
+    return(group_examples)
   } else {
-    if (!(level %in% example_ids$levels)) {
+    if (any(!(level %in% names(group_examples)))) {
       stop(
         paste0(
           "Non-valid element level received by validate_id.\n",
-          "Should be one of:\n",
-          paste(example_ids$levels, collapse = "\", \"")
+          "Should be one of:\n\"",
+          paste(names(group_examples), collapse = "\", \""),
+          "\"."
         )
       )
     }
     return(
-      example_ids |>
-        dplyr::filter(
-          example_ids$levels == level,
-          example_ids$environments == environment,
-          example_ids$example_group == group
-        ) |>
-        dplyr::pull("examples")
+      if (length(level) > 1) {
+        group_examples |>
+          magrittr::extract(level) |>
+          unlist()
+      } else {
+        group_examples |>
+          magrittr::extract2(level)
+      }
     )
   }
 }
@@ -129,3 +117,57 @@ example_data_raw <- function(
     jsonlite::fromJSON() |>
     magrittr::use_series("results")
 }
+
+#' Create an example json query string
+#' @description
+#' Create an example json query string for use in examples and tests
+#'
+#' @return String containing an example json query
+#' @export
+#'
+#' @examples
+#' example_json_query() |> cat()
+example_json_query <- function() {
+  eesyapi::parse_tojson_params(
+    indicators = example_id("indicator", group = "attendance"),
+    time_periods = "2024|W23",
+    geographies = c("NAT|id|dP0Zw", "REG|id|rg3Nj"),
+    filter_items = list(
+      attendance_status = c("pmRSo"),
+      attendance_type = c("CvuId", "6AXrf"),
+      education_phase = c("ThDPJ", "crH31"),
+      day_number = c("uLQo4"),
+      reason = c("bBrtT")
+    )
+  )
+}
+
+#' Create an example geography-query data frame
+#'
+#' @param level Query level within available options, can be one of \"nat_yorks\" or
+#' \"nat_yorks_yorkslas\"
+#'
+#' @return Data frame containing an example geography query
+#' @export
+#'
+#' @examples
+#' example_geography_query()
+example_geography_query <- function(level = "nat_yorks") {
+  example_geography_queries <- list(
+    nat_yorks =
+      data.frame(
+        return_level = c("NAT", "REG"),
+        search_level = c("NAT", "REG"),
+        identifier_type = c("code", "code"),
+        identifier = c("E92000001", "E12000002")
+      ),
+    nat_yorks_yorkslas = data.frame(
+      return_level = c("NAT", "REG", "LA"),
+      search_level = c("NAT", "REG", "REG"),
+      identifier_type = c("code", "code", "code"),
+      identifier = c("E92000001", "E12000004", "E12000004")
+    )
+  )
+  example_geography_queries |>
+    magrittr::extract2(level)
+}

R/get_dataset.R

@@ -18,7 +18,7 @@
 #' @examples
 #' get_dataset(
 #'   example_id(),
-#'   geographic_levels = "NAT",
+#'   geographic_levels = c("SCH"),
 #'   filter_items = example_id("filter_item"),
 #'   indicators = example_id("indicator")
 #' )