Type: Package
Title: Accessing 'SimFin' Data
Version: 1.0.1
Description: Through simfinapi, you can intuitively access the 'SimFin' Web-API (https://www.simfin.com/) to make 'SimFin' data easily available in R. To obtain an 'SimFin' API key (and thus to use this package), you need to register at https://app.simfin.com/login.
License: GPL-3
URL: https://github.com/matthiasgomolka/simfinapi
BugReports: https://github.com/matthiasgomolka/simfinapi/issues
Depends: R (≥ 4.1)
Imports: checkmate (≥ 2.0.0), data.table (≥ 1.12.8), httr2, lifecycle, memoise (≥ 1.1.0), RcppSimdJson (≥ 0.1.1), utils
Suggests: knitr, rmarkdown, spelling, testthat
VignetteBuilder: knitr
Config/testthat/edition: 3
Config/testthat/parallel: true
Config/testthat/start-first: check_inputs
Encoding: UTF-8
Language: en-US
RoxygenNote: 7.3.2
NeedsCompilation: no
Packaged: 2025-09-04 16:19:46 UTC; matth
Author: Matthias Gomolka [aut, cre]
Maintainer: Matthias Gomolka <matthias.gomolka@posteo.de>
Repository: CRAN
Date/Publication: 2025-09-04 17:00:02 UTC

simfinapi: Accessing 'SimFin' Data

Description

logo

Through simfinapi, you can intuitively access the 'SimFin' Web-API (https://www.simfin.com/) to make 'SimFin' data easily available in R. To obtain an 'SimFin' API key (and thus to use this package), you need to register at https://app.simfin.com/login.

Author(s)

Maintainer: Matthias Gomolka matthias.gomolka@posteo.de

See Also

Useful links:

Parameter documentation

Description

Parameter documentation

Arguments

api_key

character Your 'SimFin' API key. It's recommended to set the API key globally using sfa_set_api_key.

cache_dir

character Your cache directory. It's recommended to set the cache directory globally using sfa_set_cache_dir.

ticker

integer Ticker of the companies of interest.

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 id.

asreported

logical If TRUE, retrieves the as-reported (not restated) data.

ttm

logical If TRUE, retrieves trailing twelve month periods.

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 reported period ended ('Report Date'). By specifying a value here, only statements will be retrieved with report dates ending AFTER the specified date.

end

Date Filter for the report dates (reserved for SimFin+ users). With this filter you can filter the statements by the date on which the reported period ended ('Report Date'). By specifying a value here, only statements will be retrieved with report dates ending BEFORE the specified date.

period

character Filter for periods. As a non-SimFin+ user, you have 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 for SimFin+ users).

  • 'quarters': All quarters (q1 + q2 + q3 + q4; reserved for SimFin+ users).

fyear

integer Filter for fiscal year. As a non-SimFin+ user, you have to provide exactly one fiscal year. As SimFin+ user, this filter can be omitted to retrieve all data available for the company.

ratios

logical With TRUE, you can display some price related ratios along with the share price data (reserved for SimFin+ users). The ratios that will be displayed are:

  • Market-Cap

  • Price to Earnings Ratio (quarterly)

  • Price to Earnings Ratio (ttm)

  • Price to Sales Ratio (quarterly)

  • Price to Sales Ratio (ttm)

  • Price to Book Value (ttm)

  • Price to Free Cash Flow (quarterly)

  • Price to Free Cash Flow (ttm)

  • Enterprise Value (ttm)

  • EV/EBITDA (ttm)

  • EV/Sales (ttm)

  • EV/FCF (ttm)

  • Book to Market Value (ttm)

  • Operating Income/EV (ttm).

Parallel processing

This function supports parallel processing via future.apply. If your machine has several cores (most have), you can make the API calls in parallel. To do so, define a future::plan() before calling the function.

Common Shares Outstanding

Description

Get the number of common shares outstanding for a company.

Usage

sfa_load_common_shares_outstanding(
  id = NULL,
  ticker = NULL,
  start = NULL,
  end = NULL,
  api_key = getOption("sfa_api_key"),
  cache_dir = getOption("sfa_cache_dir")
)

Arguments

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 id.

ticker

integer Ticker of the companies of interest.

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 reported period ended ('Report Date'). By specifying a value here, only statements will be retrieved with report dates ending AFTER the specified date.

end

Date Filter for the report dates (reserved for SimFin+ users). With this filter you can filter the statements by the date on which the reported period ended ('Report Date'). By specifying a value here, only statements will be retrieved with report dates ending BEFORE the specified date.

api_key

character Your 'SimFin' API key. It's recommended to set the API key globally using sfa_set_api_key.

cache_dir

character Your cache directory. It's recommended to set the cache directory globally using sfa_set_cache_dir.

Value

data.table::data.table containing the common shares outstanding.

List Companies

Description

Get a list of all companies in the SimFin database. See https://simfin.readme.io/reference/list-1 and https://simfin.readme.io/reference/general-1 for more information.

Usage

sfa_load_companies(
  api_key = getOption("sfa_api_key"),
  cache_dir = getOption("sfa_cache_dir"),
  details = FALSE
)

Arguments

api_key

character Your 'SimFin' API key. It's recommended to set the API key globally using sfa_set_api_key.

cache_dir

character Your cache directory. It's recommended to set the cache directory globally using sfa_set_cache_dir.

details

logical(1): If TRUE, return a more detailed data.table with additional columns. Default: FALSE.

Value

data.table::data.table() containing basic company information.

Load share prices

Description

Retrieve share price data and ratios.

Usage

sfa_load_shareprices(
  ticker = NULL,
  id = NULL,
  start = NULL,
  end = NULL,
  ratios = FALSE,
  asreported = FALSE,
  api_key = getOption("sfa_api_key"),
  cache_dir = getOption("sfa_cache_dir")
)

Arguments

ticker

integer Ticker of the companies of interest.

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 id.

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 reported period ended ('Report Date'). By specifying a value here, only statements will be retrieved with report dates ending AFTER the specified date.

end

Date Filter for the report dates (reserved for SimFin+ users). With this filter you can filter the statements by the date on which the reported period ended ('Report Date'). By specifying a value here, only statements will be retrieved with report dates ending BEFORE the specified date.

ratios

logical If TRUE, additional ratios and derived metrics are included.

asreported

logical If TRUE, retrieves the as-reported (not restated) data.

api_key

character Your 'SimFin' API key. It's recommended to set the API key globally using sfa_set_api_key.

cache_dir

character Your cache directory. It's recommended to set the cache directory globally using sfa_set_cache_dir.

Value

data.table::data.table with share price data.

Get financial statements

Description

Fundamentals and derived figures can be retrieved here.

Usage

sfa_load_statements(
  ticker = NULL,
  id = NULL,
  statements,
  period = "fy",
  fyear = NULL,
  start = NULL,
  end = NULL,
  ttm = FALSE,
  asreported = FALSE,
  api_key = getOption("sfa_api_key"),
  cache_dir = getOption("sfa_cache_dir")
)

Arguments

ticker

integer Ticker of the companies of interest.

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 id.

statements

character vector of statements, available values: pl (Profit & Loss), bs (Balance Sheet), cf (Cash Flow), derived (Derived Ratios and Indicators).

period

character Filter for periods. As a non-SimFin+ user, you have 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 for SimFin+ users).

  • 'quarters': All quarters (q1 + q2 + q3 + q4; reserved for SimFin+ users).

fyear

integer Filter for fiscal year. As a non-SimFin+ user, you have to provide exactly one fiscal year. As SimFin+ user, this filter can be omitted to retrieve all data available for the company.

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 reported period ended ('Report Date'). By specifying a value here, only statements will be retrieved with report dates ending AFTER the specified date.

end

Date Filter for the report dates (reserved for SimFin+ users). With this filter you can filter the statements by the date on which the reported period ended ('Report Date'). By specifying a value here, only statements will be retrieved with report dates ending BEFORE the specified date.

ttm

logical If TRUE, retrieves trailing twelve month periods.

asreported

logical If TRUE, retrieves the as-reported (not restated) data.

api_key

character Your 'SimFin' API key. It's recommended to set the API key globally using sfa_set_api_key.

cache_dir

character Your cache directory. It's recommended to set the cache directory globally using sfa_set_cache_dir.

Value

data.table::data.table containing the statement(s) data.

Parallel processing

This function supports parallel processing via future.apply. If your machine has several cores (most have), you can make the API calls in parallel. To do so, define a future::plan() before calling the function.

Weighted Shares Outstanding

Description

Get the number of weighted shares outstanding for a company.

Usage

sfa_load_weighted_shares_outstanding(
  id = NULL,
  ticker = NULL,
  fyear = NULL,
  period = NULL,
  start = NULL,
  end = NULL,
  ttm = NULL,
  api_key = getOption("sfa_api_key"),
  cache_dir = getOption("sfa_cache_dir")
)

Arguments

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 id.

ticker

integer Ticker of the companies of interest.

fyear

integer Filter for fiscal year. As a non-SimFin+ user, you have to provide exactly one fiscal year. As SimFin+ user, this filter can be omitted to retrieve all data available for the company.

period

character Filter for periods. As a non-SimFin+ user, you have 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 for SimFin+ users).

  • 'quarters': All quarters (q1 + q2 + q3 + q4; reserved for SimFin+ users).

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 reported period ended ('Report Date'). By specifying a value here, only statements will be retrieved with report dates ending AFTER the specified date.

end

Date Filter for the report dates (reserved for SimFin+ users). With this filter you can filter the statements by the date on which the reported period ended ('Report Date'). By specifying a value here, only statements will be retrieved with report dates ending BEFORE the specified date.

ttm

logical If TRUE, retrieves trailing twelve month periods.

api_key

character Your 'SimFin' API key. It's recommended to set the API key globally using sfa_set_api_key.

cache_dir

character Your cache directory. It's recommended to set the cache directory globally using sfa_set_cache_dir.

Value

data.table::data.table containing the common shares outstanding.

Set your 'SimFin' API key globally

Description

It is highly recommended to set the API key globally as it makes specifying the api_key argument of other ⁠sfa_*⁠ functions obsolete.

There are two ways to set your API key globally:

  1. Provide the API key directly as a string (api_key = 'YourApiKey').

  2. Create a system-wide environment variable containing you API key and refer to that (env_var = 'YourEnvVar'). How to create a system-wide environment variable depends on your operating system.

The second option is recommended because your R scripts won't contain your API key and it is safe to keep your scripts in an open repository like GitHub.

Usage

sfa_set_api_key(api_key, env_var)

Arguments

api_key

character You API key. Ignored if you specify env_var as well.

env_var

character Name of an environment variable holding you API key, e.g. SIMFIN_API_KEY. Leave empty (NULL, default) if you want to set your API key directly.

Value

character The API key (invisibly).

Examples

## Not run: 
# set API key directly
sfa_set_api_key(api_key = "YourApiKey")

# set API key via environment variable
# (this assumes you already created an environment variable called
# 'SIMFIN_API_KEY' which contains you API key)
sfa_set_api_key(env_var = "SIMFIN_API_KEY")

## End(Not run)

Set cache directory globally

Description

It is highly recommended to set the cache directory globally. This has two advantages:

  1. Results from the 'SimFin' API calls are cached over the end of the session. This is especially interesting if you don't have a SimFin+ account and the number of API calls is limited to 2,000 per day.

  2. It makes specifying the cache_dir argument of other ⁠sfa_*⁠ functions obsolete.

Usage

sfa_set_cache_dir(path, create = FALSE)

Arguments

path

character The directory where you want to cache the responses from the 'SimFin' API calls.

create

logical Set TRUE if you want to create path automatically if it does not yet exist.

Value

character The cache directory (invisibly).