Parameters

fa_period_type()

is an optional parameter that lets you define the duration of the period(s) for which you want company financials data

Value	Period
A	Annual
Q	Quarterly
LTM	Last Twelve Month (TTM) - default

Examples

• Retrieve IBM's earnings per share (EPS) for the last reported quarter get(eps(fa_period_type=Q)) for ('IBM US')

• Retrieve IBM's earnings per share (EPS) for the last 3 quarters get(eps(fa_period_type=Q, fa_period_reference=range(2020Q1, 2023Q4))) for ('IBM US')

• Retrieve IBM's earnings per share (EPS) for the last year get(eps(fa_period_type=A)) for ('IBM US')

fa_period_reference()

is an optional parameter for company financials data items that lets you choose one or more fixed positions in time for the period(s) of data you want to return

Singe Anchor Period

value	period
'{YYYY}A' or '{YYYY}'	Annual Period
'{YYYY}Q1'	First Quarter
'{YYYY}Q2'	Second Quarter
'{YYYY}Q3'	Third Quarter
'{YYYY}Q4'	Fourth Quarter

Note: Keep in mind that the period type (A, Q) in a period reference does not determine the duration of the data period! To obtain annual, quarterly, or semi-annual data rather than a Last 12 Months (LTM) value, utilize fa_period_type() (Financials Period Type) to specify the desired period duration.

For example:

• fa_period_reference='2018'

• fa_period_reference='2016A'

• fa_period_reference='2018Q3'

Range of periods

value	period
range('{YYYY}', '{YYYY}')	Range of Annual Periods
range('{YYYY}A', '{YYYY}A')
range('{YYYY}Q1', '{YYYY}Q4')	Range of Quarters
range('{YYYY}Q2', '{YYYY}Q3')

You must assign the same period type (i.e., semi-annual or quarter) to both the start and end period.

For example:

• fa_period_reference=range('2016', '2019')

• fa_period_reference=range('2018Q1', '2019Q4')

Sampling Frequency

The period type you use in the period reference represents the length of the steps in the range between the start and end periods (i.e., annual, semi-annual, or quarterly steps). If you do not specify a period type, the step length is annual.

Examples

• Retrieve IBM's earnings per share (EPS) for the Last 12 Months (LTM) period ending at the same time as Q3 2022Q3: get(eps(fa_period_type=Q, fa_period_reference='2022Q3')) for ('IBM US')

• Retrieve IBM's last twelve months EPS at the end of each quarter between Q3 2022 and Q3 2023: get(eps(fa_period_type=LTM, fa_period_reference=range('2022Q3', '2023Q3'))) for ('IBM US')

Type and Reference interaction

Here is a reformatted version of the documentation for the API query examples, written in a clear and structured GitBook style, presented in a table with two columns for easy reference:

Example	Description
get(eps(fa_period_type=Q)) for('AAPL US')	When only the periodicity (fa_period_type=Q) is specified, the query defaults to retrieving data for the most recent fiscal period ending on or before today. "Q" indicates a quarterly periodicity. This retrieves the Earnings Per Share (EPS) for Apple's last reported quarter.
get(eps(fa_period_reference='2022Q4')) for('AAPL US')	Here, the fiscal period reference (fa_period_reference='2022Q4') is specified without a periodicity, defaulting to the Last 12 Months (LTM). This setup fetches the EPS for the period ending in the fourth quarter of 2022, reflecting data across the last 12 months from that date.
get(eps(fa_period_reference='2022Q4', fa_period_type=Q)) for('AAPL US')	Both the specific fiscal period (fa_period_reference='2022Q4') and periodicity (fa_period_type=Q) are defined. This results in the retrieval of the quarterly EPS specifically for the fourth quarter of 2022.
get(eps(fa_period_reference=range('2022', '2023'), fa_period_type=Q)) for('AAPL US')	The query specifies a range for the fiscal period (fa_period_reference=range('2022', '2023')) with a quarterly periodicity (fa_period_type=Q). This retrieves EPS data for the fourth quarters of both 2022 and 2023, as the range implies annual steps, and the periodicity confirms the data is retrieved for the final quarter of each year specified.
get(eps(fa_period_reference=range('2022Q2', '2022Q4'), fa_period_type=LTM)) for('AAPL US')	This example includes a range specifying quarters within a single year ('2022Q2' to '2022Q4') and a periodicity set to Last 12 Months (LTM). The query retrieves EPS data corresponding to the last 12 months ending at the conclusion of each specified quarter within 2022, capturing LTM data for Q2, Q3, and Q4 of 2022.

This structured format should provide clear guidance on how each type of RQL query functions within the Roic AI API environment, delineating the implications of various parameters on the data retrieval process.