Merge pull request #53 from matthiasgomolka/api_v3

API v3

DESCRIPTION

@@ -1,7 +1,7 @@
 Type: Package
 Package: simfinapi
 Title: Accessing 'SimFin' Data
-Version: 0.2.4
+Version: 1.0.0
 Authors@R: 
  person("Matthias", "Gomolka", , "matthias.gomolka@posteo.de", role = c("aut", "cre"))
 Description: Through simfinapi, you can intuitively access the 'SimFin'
@@ -14,13 +14,11 @@ BugReports: https://github.com/matthiasgomolka/simfinapi/issues
 Depends: 
  R (>= 3.5)
 Imports: 
- bit64,
  checkmate (>= 2.0.0),
  data.table (>= 1.12.8),
- future.apply (>= 1.4.0),
- httr,
+ httr2,
+ lifecycle,
  memoise (>= 1.1.0),
- progressr,
  RcppSimdJson (>= 0.1.1),
  utils
 Suggests: 

NAMESPACE

@@ -1,16 +1,13 @@
 # Generated by roxygen2: do not edit by hand
 
-export(sfa_get_entities)
-export(sfa_get_info)
-export(sfa_get_prices)
-export(sfa_get_ref)
-export(sfa_get_shares)
-export(sfa_get_statement)
+export(sfa_load_common_shares_outstanding)
+export(sfa_load_companies)
+export(sfa_load_shareprices)
+export(sfa_load_statements)
+export(sfa_load_weighted_shares_outstanding)
 export(sfa_set_api_key)
 export(sfa_set_cache_dir)
-export(sfa_set_sfplus)
 importFrom(RcppSimdJson,fparse)
-importFrom(bit64,as.integer64)
 importFrom(checkmate,assert_character)
 importFrom(checkmate,assert_choice)
 importFrom(checkmate,assert_date)
@@ -20,24 +17,24 @@ importFrom(checkmate,assert_logical)
 importFrom(checkmate,assert_string)
 importFrom(data.table,CJ)
 importFrom(data.table,as.data.table)
-importFrom(data.table,fread)
+importFrom(data.table,data.table)
 importFrom(data.table,is.data.table)
 importFrom(data.table,rbindlist)
 importFrom(data.table,set)
 importFrom(data.table,setattr)
 importFrom(data.table,setcolorder)
 importFrom(data.table,setkeyv)
 importFrom(data.table,setnames)
-importFrom(data.table,transpose)
 importFrom(data.table,year)
-importFrom(future.apply,future_lapply)
-importFrom(future.apply,future_mapply)
-importFrom(httr,GET)
-importFrom(httr,content)
+importFrom(httr2,last_response)
+importFrom(httr2,req_headers)
+importFrom(httr2,req_perform)
+importFrom(httr2,req_url_path_append)
+importFrom(httr2,req_url_query)
+importFrom(httr2,req_user_agent)
+importFrom(httr2,request)
+importFrom(httr2,resp_body_string)
+importFrom(httr2,resp_is_error)
+importFrom(lifecycle,deprecated)
 importFrom(memoise,cache_filesystem)
 importFrom(memoise,memoise)
-importFrom(progressr,progressor)
-importFrom(progressr,with_progress)
-importFrom(utils,download.file)
-importFrom(utils,hasName)
-importFrom(utils,unzip)

NEWS.md

@@ -1,3 +1,7 @@
+# simfinapi 1.0.0
+## Features
+* The package is now compatible with the new SimFin API V3.
+
 # simfinapi 0.2.4
 ## Bug Fixes
 * Some new API keys were not accepted by `check_api_key()`. This is fixed now.

R/call_api.R

@@ -1,47 +1,34 @@
-#' @importFrom httr content
 #' @importFrom RcppSimdJson fparse
-#' @importFrom utils hasName
 #' @importFrom memoise memoise cache_filesystem
-#' @importFrom httr GET
-call_api <- function(..., cache_dir) {
- # check for cache setup
+#' @importFrom httr2 request req_url_path_append req_headers req_user_agent req_url_query
+#' req_perform last_response resp_is_error resp_body_string
+#' @noRd
+call_api <- function(url, api_key, cache_dir, ...) {
+ # check for cache setup
 
- if (is.null(cache_dir)) {
- warning(
- "'cache_dir' not set. Defaulting to 'tempdir()'. Thus, API results will ",
- "only be cached during this session. To learn why and how to cache ",
- "results over the end of this session, see `?sfa_set_cache_dir`.\n\n",
- "[This warning appears only once per session.]",
- call. = FALSE
- )
- sfa_set_cache_dir(tempdir(), create = TRUE)
- cache_dir <- getOption("sfa_cache_dir")
- }
+ if (is.null(cache_dir)) {
+ warning("'cache_dir' not set. Defaulting to 'tempdir()'. Thus, API results will ", "only be cached during this session. To learn why and how to cache ",
+ "results over the end of this session, see `?sfa_set_cache_dir`.\n\n", "[This warning appears only once per session.]",
+ call. = FALSE)
+ sfa_set_cache_dir(tempdir(), create = TRUE)
+ cache_dir <- getOption("sfa_cache_dir")
+ }
 
- checkmate::assert_directory(cache_dir, access = "rw")
+  checkmate::assert_directory(cache_dir, access = "rw")
 
- mem_GET <- memoise::memoise(
- httr::GET,
- cache = memoise::cache_filesystem(cache_dir)
- )
+ req <- httr2::request("https://prod.simfin.com/api/v3") |>
+ httr2::req_url_path_append(url) |>
+ httr2::req_headers(Authorization = api_key, accept = "application/json") |>
+ httr2::req_user_agent("simfinapi (https://github.com/matthiasgomolka/simfinapi)") |>
+ httr2::req_url_query(...)
 
- # call API and transform result to list
- response <- mem_GET(
- url = "https://legacy.simfin.com",
- ...
- )
- request <- response[["request"]][["url"]]
- content <- RcppSimdJson::fparse(
- response[["content"]],
- max_simplify_lvl = "vector",
- int64_policy = "integer64"
- )
+ mem_req_perform <- memoise::memoise(httr2::req_perform, cache = memoise::cache_filesystem(cache_dir))
 
- if (utils::hasName(content, "error")) {
- warning("From 'SimFin' API: '", content[["error"]], "'", call. = FALSE)
- return(NULL)
- }
+ resp <- tryCatch(mem_req_perform(req), error = \(error) httr2::last_response())
 
+ if (httr2::resp_is_error(resp)) {
+ handle_api_error(resp)
+ }
 
- return(list(request = request, content = content))
+  return(resp)
 }

R/check_inputs.R

@@ -1,25 +1,30 @@
+#' @noRd
 msg_sfplus_required <- function(var, verb = "Omitting") {
  stop(verb, " '", var, "' is reserved for SimFin+ users.", call. = FALSE)
 }
 
 #' @importFrom checkmate assert_string
+#' @noRd
 check_api_key <- function(api_key) {
- checkmate::assert_string(api_key, pattern = "^[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*$")
+ checkmate::assert_string(api_key)#, pattern = "^[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*$")
 }
 
 #' @importFrom checkmate assert_directory
+#' @noRd
 check_cache_dir <- function(cache_dir) {
  if (!is.null(cache_dir)) {
  checkmate::assert_directory(cache_dir, access = "rw")
  }
 }
 
 #' @importFrom checkmate assert_logical
+#' @noRd
 check_sfplus <- function(sfplus) {
  checkmate::assert_logical(sfplus, any.missing = FALSE, len = 1L)
 }
 
 #' @importFrom checkmate assert_character
+#' @noRd
 check_ticker <- function(ticker) {
  checkmate::assert_character(
  ticker,
@@ -30,28 +35,32 @@ check_ticker <- function(ticker) {
 }
 
 #' @importFrom checkmate assert_integerish
-check_simfin_id <- function(simfin_id) {
+#' @noRd
+check_id <- function(id) {
  checkmate::assert_integerish(
- simfin_id,
+ id,
  lower = 1L,
  any.missing = FALSE,
  null.ok = TRUE
  )
 }
 
 #' @importFrom checkmate assert_choice
+#' @noRd
 check_statement <- function(statement, sfplus) {
- checkmate::assert_choice(
+ checkmate::assert_subset(
  statement,
- c("pl", "bs", "cf", "derived", "all"),
+ c("pl", "bs", "cf", "derived"),
+ empty.ok = FALSE,
  fmatch = TRUE
  )
- if (statement == "all" & isFALSE(sfplus)) {
- stop('statement = "all" is reserved for SimFin+ users.', call. = FALSE)
- }
+ # if (statement == "all" & isFALSE(sfplus)) {
+ #  stop('statement = "all" is reserved for SimFin+ users.', call. = FALSE)
+ # }
 }
 
 #' @importFrom checkmate assert_choice
+#' @noRd
 check_period <- function(period, sfplus, called_from_get_shares = FALSE) {
  checkmate::assert_choice(
  period,
@@ -71,14 +80,16 @@ check_period <- function(period, sfplus, called_from_get_shares = FALSE) {
  }
 }
 
+#' @noRd
 check_period_get_shares <- function(...) {
  check_period(...)
 }
 
 
 #' @importFrom checkmate assert_integerish
+#' @noRd
 check_fyear <- function(fyear, sfplus) {
- if (is.null(fyear) & isFALSE(sfplus)) {
+ if (is.null(fyear) && isFALSE(sfplus)) {
  msg_sfplus_required("fyear")
  }
  checkmate::assert_integerish(
@@ -88,15 +99,18 @@ check_fyear <- function(fyear, sfplus) {
  null.ok = TRUE
  )
 }
+
+#' @noRd
 check_fyear_get_shares <- function(..., type) {
  if (type %in% c("wa-basic", "wa-diluted")) {
  check_fyear(...)
  }
 }
 
 #' @importFrom checkmate assert_date
+#' @noRd
 check_start <- function(start, sfplus) {
- if (!is.null(start) & isFALSE(sfplus)) {
+ if (!is.null(start) && isFALSE(sfplus)) {
  msg_sfplus_required("start", "Specifying")
  }
  checkmate::assert_date(
@@ -108,8 +122,9 @@ check_start <- function(start, sfplus) {
 }
 
 #' @importFrom checkmate assert_date
+#' @noRd
 check_end <- function(end, sfplus) {
- if (!is.null(end) & isFALSE(sfplus)) {
+ if (!is.null(end) && isFALSE(sfplus)) {
  msg_sfplus_required("end", "Specifying")
  }
  checkmate::assert_date(
@@ -121,15 +136,17 @@ check_end <- function(end, sfplus) {
 }
 
 #' @importFrom checkmate assert_logical
+#' @noRd
 check_ttm <- function(ttm) {
  checkmate::assert_logical(ttm, any.missing = FALSE, len = 1L)
 }
 
 #' @importFrom checkmate assert_logical
+#' @noRd
 check_shares <- function(shares, sfplus) {
  checkmate::assert_logical(shares, any.missing = FALSE, len = 1L)
 
- if (isTRUE(shares) & isFALSE(sfplus)) {
+ if (isTRUE(shares) && isFALSE(sfplus)) {
  stop(
  "'shares = TRUE' is reserved to SimFin+ users. As a normal user, please ",
  "use 'sfa_get_shares()' with 'type = \"wa-basic\"' or 'type = ",
@@ -140,8 +157,9 @@ check_shares <- function(shares, sfplus) {
 }
 
 #' @importFrom checkmate assert_logical
+#' @noRd
 check_ratios <- function(ratios, sfplus) {
- if (!is.null(ratios) & isFALSE(sfplus)) {
+ if (!is.null(ratios) && isFALSE(sfplus)) {
  msg_sfplus_required("ratios", "Specifying")
  }
  checkmate::assert_logical(
@@ -153,6 +171,7 @@ check_ratios <- function(ratios, sfplus) {
 }
 
 #' @importFrom checkmate assert_choice
+#' @noRd
 check_type <- function(type) {
  checkmate::assert_choice(
  type,
@@ -162,6 +181,7 @@ check_type <- function(type) {
 }
 
 #' @importFrom checkmate assert_choice
+#' @noRd
 check_ref_data <- function(ref_data) {
  checkmate::assert_choice(
  ref_data,

R/param_doc.R

@@ -7,15 +7,16 @@
 #' @param cache_dir [character] Your cache directory. It's recommended to set
 #' the cache directory globally using [sfa_set_cache_dir].
 #'
-#' @param sfplus [logical] Set`TRUE` if you have a SimFin+ account. It's
-#' recommended to set `sfplus` globally using [sfa_set_sfplus].
-#'
 #' @param ticker [integer] Ticker of the companies of interest.
 #'
-#' @param simfin_id [integer] 'SimFin' IDs of the companies of interest. Any
-#' `simfin_id` will be internally translated to the respective `ticker`. This
+#' @param id [integer] 'SimFin' IDs of the companies of interest. Any
+#' `id` will be internally translated to the respective `ticker`. This
 #' reduces the number of queries in case you query the same company via
-#' `ticker` *and* `simfin_id`.
+#' `ticker` *and* `id`.
+#'
+#' @param asreported [logical] If `TRUE`, retrieves the as-reported (not restated) data.
+#'
+#' @param ttm [logical] If `TRUE`, retrieves trailing twelve month periods.
 #'
 #' @param start [Date] Filter for the report dates (reserved for SimFin+ users).
 #' With this filter you can filter the statements by the date on which the
@@ -33,17 +34,17 @@
 #' to provide exactly one period. As SimFin+ user, this filter can be omitted
 #' to retrieve all statements available for the company.
 #'
-#' - `"q1"`: First fiscal quarter.
-#' - `"q2"`: Second fiscal quarter.
-#' - `"q3"`: Third fiscal quarter.
-#' - `"q4"`: Fourth fiscal quarter.
-#' - `"fy"`: Full fiscal year.
-#' - `"h1"`: First 6 months of fiscal year.
-#' - `"h2"`: Last 6 months of fiscal year.
-#' - `"9m"`: First nine months of fiscal year.
-#' - `"6m"`: Any fiscal 6 month period (first + second half years; reserved
+#' - `'q1'`: First fiscal quarter.
+#' - `'q2'`: Second fiscal quarter.
+#' - `'q3'`: Third fiscal quarter.
+#' - `'q4'`: Fourth fiscal quarter.
+#' - `'fy'`: Full fiscal year.
+#' - `'h1'`: First 6 months of fiscal year.
+#' - `'h2'`: Last 6 months of fiscal year.
+#' - `'9m'`: First nine months of fiscal year.
+#' - `'6m'`: Any fiscal 6 month period (first + second half years; reserved
 #' for SimFin+ users).
-#' - `"quarters"`: All quarters (q1 + q2 + q3 + q4; reserved for SimFin+
+#' - `'quarters'`: All quarters (q1 + q2 + q3 + q4; reserved for SimFin+
 #' users).
 #'
 #' @param fyear [integer] Filter for fiscal year. As a non-SimFin+ user, you