GET
/events/calendar?event_type={event_type}&symbols={symbols}&start_date={start_date}&end_date={end_date}
Get calendar events

Example URI

https://api.livevol.com/v1/events/calendar?event_type=earnings&symbols=DAL&start_date=2019-01-01&end_date=2019-06-30

Request Information

URI Parameters

Name Description Type Additional information
event_type

Event type

string

Allowed values are [ all, earnings, dividends ]

Default value is: all

symbols

Comma-separated list of symbols or special symbol ('all_symbols', 'all_optionable_symbols')

string

Required

start_date

Start date in YYYY-MM-DD format. Optional.

string

Constraint: value should be less than or equal to end_date value

Date in yyyy-MM-dd format. (i.e. 2019-01-18)

Default value is: 2003-01-01

end_date

End date in YYYY-MM-DD format. Optional.

string

Constraint: value should be greater than or equal to start_date value

Date in yyyy-MM-dd format. (i.e. 2019-01-18)

Default value is: 2100-01-01

Response Information

Resource Description

Collection of types:
EarningsEvent

Name Description Type Additional information SIP Provider
year

Earnings Year

integer

None

None

quarter

Earnings Quarter

integer

None

None

report_date

Date of earnings

string

Represented as 'YYYY-MM-DD'

None

time_of_day

Time of day: 'BMO' Before Market Open, 'DMT' During Market Trading, 'AMC' After Market Close

string

None

None

Earnings status

EarningStatus

None

None

EarningStatus

Possible enumeration values:

Value Description

verified

tentative

Report date type

ReportDateType

None

None

ReportDateType

Possible enumeration values:

Value Description

confirmed

not_confirmed

estimated

unknown

eps_actual

Actual earnings per share

decimal number

None

None

eps_estimate

Estimated earnings per share

decimal number

None

None

actual_currency

Currency code of actual eps

string

None

None

underlying_symbol

Underlying symbol

string

None

None

company_name

Company name

string

None

None

Event type

EventType

None

None

EventType

Possible enumeration values:

Value Description

dividends

earnings

DividendsEvent
Name Description Type Additional information SIP Provider
underlying_symbol

Underlying symbol of equity or ETF

string

None

None

Event type

EventType

None

None

EventType

Possible enumeration values:

Value Description

dividends

earnings

announcement_date

Date dividend was announced

string

Represented as 'YYYY-MM-DD'

None

ex_dividend_date

Ex-dividend date

string

Represented as 'YYYY-MM-DD'

None

record_date

Date before which holders-of-record will receive the dividend.

string

Represented as 'YYYY-MM-DD'

None

payment_date

Payment date

string

Represented as 'YYYY-MM-DD'

None

dividend

Distribution amount

decimal number

None

None

Status of dividend

DividendStatus

None

None

DividendStatus

Possible enumeration values:

Value Description

confirmed

projected

Frequency of dividend payment.

Frequency

None

None

Frequency

Possible enumeration values:

Value Description

annual

semi-annual

quarterly

monthly

bi-monthly

special

unknown

Type of asset

AssetType

None

None

AssetType

Possible enumeration values:

Value Description

stock

etf

Dividend code

DividendCode

None

None

DividendCode

Possible enumeration values:

Value Description

unknown

regular

special

unadjusted_dividend

Unadjusted dividend

decimal number

None

None

Data source

DataSource

None

None

DataSource

Possible enumeration values:

Value Description

unknown

projected

market_implied

Distribution breakdown. For Stocks, dividends are reported, including special dividend payments. For ETFs, dividends, short-term capital gains, long-term capital gains, return of capital, or other distributions are reported.

Collection of DistributionDetails

None

None

DistributionDetails

Name Description Type Additional information SIP Provider
amount

Actual or projected distribution amount

decimal number

None

None

Type of distribution. For Stocks, dividends are reported. For ETFs, dividends, short-term capital gains, long-term capital gains, return of capital, or other distributions are reported.

DistributionType

None

None

DistributionType

Possible enumeration values:

Value Description

dividend

st_capital_gain

lt_capital_gain

roc

other

company_name

Company name

string

None

None

Response Formats

application/json, text/json

Sample:
[
  {
    "year": 2019,
    "quarter": 1,
    "report_date": "2019-07-30",
    "time_of_day": "AMC",
    "earning_status": "verified",
    "report_date_type": "confirmed",
    "eps_actual": 2.18,
    "eps_estimate": 2.17168,
    "actual_currency": "USD",
    "underlying_symbol": "AAPL",
    "company_name": "Apple Inc.",
    "event_type": "earnings"
  },
  {
    "underlying_symbol": "AAPL",
    "event_type": "dividends",
    "announcement_date": "2016-06-30",
    "ex_dividend_date": "2019-08-08",
    "record_date": "2016-06-30",
    "payment_date": "2019-09-10",
    "dividend": 0.115,
    "dividend_status": "confirmed",
    "frequency": "annual",
    "asset_type": "stock",
    "dividend_code": "regular",
    "unadjusted_dividend": 0.115,
    "data_source": "projected",
    "distribution_details": [
      {
        "amount": 0.115,
        "distribution_type": "dividend"
      }
    ],
    "company_name": "Apple Inc."
  }
]

application/xml, text/xml

Sample:
<events xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <event xmlns="" i:type="earning">
    <company_name>Apple Inc.</company_name>
    <event_type>earnings</event_type>
    <underlying_symbol>AAPL</underlying_symbol>
    <actual_currency>USD</actual_currency>
    <earning_status>verified</earning_status>
    <eps_actual>2.18</eps_actual>
    <eps_estimate>2.17168</eps_estimate>
    <quarter>1</quarter>
    <report_date>2019-07-30</report_date>
    <report_date_type>confirmed</report_date_type>
    <time_of_day>AMC</time_of_day>
    <year>2019</year>
  </event>
  <event xmlns="" i:type="dividend">
    <company_name>Apple Inc.</company_name>
    <event_type>dividends</event_type>
    <underlying_symbol>AAPL</underlying_symbol>
    <announcement_date>2016-06-30</announcement_date>
    <asset_type>stock</asset_type>
    <data_source>projected</data_source>
    <distribution_details>
      <distribution_details>
        <amount>0.115</amount>
        <distribution_type>dividend</distribution_type>
      </distribution_details>
    </distribution_details>
    <dividend>0.115</dividend>
    <dividend_code>regular</dividend_code>
    <dividend_status>confirmed</dividend_status>
    <ex_dividend_date>2019-08-08</ex_dividend_date>
    <frequency>annual</frequency>
    <payment_date>2019-09-10</payment_date>
    <record_date>2016-06-30</record_date>
    <unadjusted_dividend>0.115</unadjusted_dividend>
  </event>
</events>