add missing functions

Author: aberuiz

R/getDatasetRaw.R

@@ -0,0 +1,47 @@
+#' Download dataset archive as a ZIP file
+#'
+#' @description
+#' Download a specific dataset as a binary ZIP archive written directly to disk,
+#' containing all bills, votes, and people data for the specified session
+#'
+#' @param sessionID session_id integer value (use session_id from getDatasetList)
+#'
+#' @param accessKey access_key string value (use access_key from getDatasetList)
+#'
+#' @param format File format of the ZIP contents, either "json" or "csv"
+#'
+#' @param file File path to write the ZIP archive to. Defaults to legiscan_dataset_<sessionID>.zip in the working directory
+#'
+#' @param legiKey 32 character string provided by legiscan
+#'
+#' @returns File path of the downloaded ZIP archive, invisibly
+#'
+#' @examples
+#' \dontrun{
+#' getDatasetRaw(sessionID = 1234, accessKey = "abc123def456")
+#' getDatasetRaw(sessionID = 1234, accessKey = "abc123def456", format = "csv")
+#' }
+#'
+#' @export
+getDatasetRaw <- function(sessionID = NULL, accessKey = NULL, format = "json", file = NULL, legiKey = NULL){
+
+  if (is.null(sessionID) || is.null(accessKey)){
+    stop("Specify both a sessionID and accessKey from `getDatasetList` to download a dataset")
+  }
+
+  response <- legiRequest(
+    op = "getDatasetRaw",
+    id = sessionID,
+    access_key = accessKey,
+    format = format,
+    legiKey = legiKey,
+    raw = TRUE
+  )
+
+  if (is.null(file)){
+    file <- paste0("legiscan_dataset_", sessionID, ".zip")
+  }
+  writeBin(response, file)
+  print(paste0("Dataset saved to ", file))
+  return(invisible(file))
+}

R/getMasterListRaw.R

@@ -0,0 +1,42 @@
+#' Return legiscan Master List for change detection
+#'
+#' @description
+#' Returns a Master List of bill_id and change_hash values for a specified session
+#' or the most recent regular session if only state is provided. Optimized for
+#' detecting which bills have changed and need updating via `getBill`.
+#'
+#' @param session Session id integer value. Can be found with `getSessions`
+#'
+#' @param state US state abbreviation
+#'
+#' @param legiKey 32 character string provided by legiscan
+#'
+#' @returns Master List of bill_id and change_hash in dataframe format
+#'
+#' @examples
+#' \dontrun{
+#' getMasterListRaw(session = 2108)
+#' getMasterListRaw(state = "TX")
+#' }
+#'
+#' @export
+getMasterListRaw <- function(session = NULL, state = NULL, legiKey = NULL){
+
+  if (is.null(session) && is.null(state)){
+    stop("Specify a Session or a State to return a Master List")
+  }
+
+  response <- legiRequest(
+    op = "getMasterListRaw",
+    state = state,
+    id = session,
+    legiKey = legiKey
+  )
+
+  masterlist <- response$masterlist
+  if (!is.null(masterlist$session)){
+    print(masterlist$session$session_name)
+    masterlist$session <- NULL
+  }
+  return(dplyr::bind_rows(masterlist))
+}

R/getMonitorListRaw.R

@@ -0,0 +1,30 @@
+#' Return associated monitor list for change detection
+#'
+#' @description
+#' Return bill_id and change_hash values from the monitor list of the account
+#' associated with the legiKey provided. Optimized for detecting which bills
+#' have changed and need updating via `getBill`.
+#'
+#' @param record Record filter: "current" or "archived", or an exact year >= 2010
+#'
+#' @param legiKey 32 character API key from legiscan
+#'
+#' @returns Monitored bills with bill_id and change_hash in dataframe format
+#'
+#' @examples
+#' \dontrun{
+#' getMonitorListRaw()
+#' getMonitorListRaw(record = "archived")
+#' }
+#'
+#' @export
+getMonitorListRaw <- function(record = "current", legiKey = NULL){
+
+  response <- legiRequest(
+    op = "getMonitorListRaw",
+    record = record,
+    legiKey = legiKey
+  )
+
+  return(dplyr::bind_rows(response$monitorlist))
+}

R/legiSearchRaw.R

@@ -0,0 +1,66 @@
+#' Return raw search results from legiscan's database
+#'
+#' @description
+#' Return search results from legiscan's full text engine with simplified details,
+#' 2000 results at a time. Returns relevance, bill_id, and change_hash only,
+#' appropriate for automated keyword monitoring. Check legiscan.com for specific search syntax for more details.
+#'
+#' @param query Enter your search text. Your query may use grammatically correct spacing. Use legiscan's search syntax for more powerful results.
+#'
+#' @param state Search the entire nation by default with 'ALL' or specify state using letter abbreviations
+#'
+#' @param year Should be an integer. 1=All, 2=Current, 3=Recent, 4=Prior, >1900=Exact Year
+#'
+#' @param session Limit search to specific session with a session_id
+#'
+#' @param page Default is set to return Page 1. `legiSearchRaw` will paginate and include results.
+#'
+#' @param legiKey 32 character string provided by legiscan
+#'
+#' @returns Search results with relevance, bill_id, and change_hash in dataframe format
+#'
+#' @examples
+#' \dontrun{
+#' legiSearchRaw(
+#'   query = "intro:month AND wage theft",
+#'   state = "TX"
+#' )
+#' }
+#'
+#' @export
+legiSearchRaw <- function(query = NULL, state = "ALL", year = 2, session = NULL, page = 1, legiKey = NULL){
+
+  all_data <- list()
+
+  while (TRUE) {
+    response <- legiRequest(
+      op = "getSearchRaw",
+      state = state,
+      query = query,
+      year = year,
+      id = session,
+      page = page,
+      legiKey = legiKey
+    )
+
+    results <- response$searchresult$results
+    if (is.null(results) || length(results) == 0) {
+      break
+    }
+
+    all_data <- dplyr::bind_rows(all_data, dplyr::bind_rows(results))
+
+    if (page >= response$searchresult$summary$page_total) {
+      break
+    }
+
+    page <- page + 1
+  }
+  if (length(all_data) == 0) {
+    warning("No results found. Reference <https://legiscan.com/fulltext-search> for help with search syntax.")
+    return(NULL)
+  } else {
+    message(paste0(nrow(all_data), " Results Found"))
+    return(all_data)
+  }
+}

R/setMonitor.R

@@ -0,0 +1,51 @@
+#' Add or remove bills from the monitor list
+#'
+#' @description
+#' Interact with GAITS to add or remove bills from the monitor list of the
+#' account associated with the legiKey provided, or set a stance on monitored bills
+#'
+#' @param billIDs One or more bill_id integer values to operate on
+#'
+#' @param action Action to take on the bill list: "monitor", "remove", or "set"
+#'
+#' @param stance Position on the bill: "watch", "support", or "oppose"
+#'
+#' @param legiKey 32 character API key from legiscan
+#'
+#' @returns Status of each bill_id and the action taken in dataframe format
+#'
+#' @examples
+#' \dontrun{
+#' setMonitor(billIDs = c(150334, 141690), action = "monitor")
+#' setMonitor(billIDs = 1533377, action = "set", stance = "support")
+#' }
+#'
+#' @export
+setMonitor <- function(billIDs = NULL, action = NULL, stance = "watch", legiKey = NULL){
+
+  if (is.null(billIDs)){
+    stop("Specify one or more billIDs to operate on")
+  }
+  if (is.null(action) || !action %in% c("monitor", "remove", "set")){
+    stop("action must be one of 'monitor', 'remove', or 'set'")
+  }
+  if (!stance %in% c("watch", "support", "oppose")){
+    stop("stance must be one of 'watch', 'support', or 'oppose'")
+  }
+
+  response <- legiRequest(
+    op = "setMonitor",
+    list = paste(billIDs, collapse = ","),
+    action = action,
+    stance = stance,
+    legiKey = legiKey
+  )
+
+  return(
+    data.frame(
+      bill_id = names(response$`return`),
+      result = unlist(response$`return`),
+      row.names = NULL
+    )
+  )
+}