Calendar API Reference

Free Trial ➡

This REST API returns structured data for dividends, earnings, future earnings dates, conference calls, economics, guidance, IPOs, ratings, retail sales, splits.

API Endpoint

https://api.benzinga.com/api/v2

Response Content-Types

application/json, application/xml

Schemes

https, http

Version

2.0.0

Authentication

`token` authentication

Type:: apiKey
Name:: token
In:: query

Playground

Endpoints

GET /calendar/conference-calls

Returns retail sales data

Parameters

Name	Type	Location	Description
`accept`	string , x ∈ { application/json , application/xml (default) }	header	Specifies return format. Query parameters work the same for both formats.
`page`	integer	query	Page offset.
`pagesize`	integer	query	Number of results returned. Limit 1000
`parameters[date]`	string (YYYY-MM-DD)	query	Date to query for calendar data. Shorthand for date_from and date_to if they are the same. Defaults for latest.
`parameters[date_from]`	string (YYYY-MM-DD)	query	Date to query from point in time.
`parameters[date_to]`	string (YYYY-MM-DD)	query	Date to query to point in time.
`parameters[tickers]`	string (csv)	query	One or more ticker symbols separated by a comma. All calendar accept this parameter. Ignored by Economics.
`parameters[updated]`	integer (int64)	query	Records last Updated Unix timestamp (UTC). This will force the sort order to be Greater Than or Equal to the timestamp indicated.

Responses

Code	Model	Description
`200 OK`	conferenceCalls	success

Response (200 OK)

[
  {
    "id": "string",
    "date": "string (YYYY-MM-DD)",
    "time": "string (HH:MM:SS)",
    "name": "string",
    "exchange": "string",
    "ticker": "string",
    "start_time": "string (HH:MM:SS)",
    "phone_num": "string (NNN-NNN-NNNN)",
    "international_num": "string (NNN-NNN-NNNN)",
    "reservation_num": "string (NNN-NNN-NNNN)",
    "access_code": "string",
    "webcase_url": "string (URI)",
    "importance": "string",
    "notes": "string",
    "updated": "integer (int64)"
  }
]


token

GET /calendar/dividends

Dividends Events

Returns dividends data for a selected period and/or security.

Parameters

Name	Type	Location	Description
`accept`	string , x ∈ { application/json , application/xml (default) }	header	Specifies return format. Query parameters work the same for both formats.
`page`	integer	query	Page offset.
`pagesize`	integer	query	Number of results returned. Limit 1000
`parameters[date]`	string (YYYY-MM-DD)	query	Date to query for calendar data. Shorthand for date_from and date_to if they are the same. Defaults for latest.
`parameters[date_from]`	string (YYYY-MM-DD)	query	Date to query from point in time.
`parameters[date_to]`	string (YYYY-MM-DD)	query	Date to query to point in time.
`parameters[tickers]`	string (csv)	query	One or more ticker symbols separated by a comma. All calendar accept this parameter. Ignored by Economics.
`parameters[importance]`	integer , x ∈ { 0 , 1 , 2 , 3 , 4 , 5 }	query	The importance level to filter by. Uses Greater Than or Equal To the importance indicated
`parameters[date_sort]`	string , x ∈ { announced , ex , payable , record }	query	Dividend date field to sort on
`parameters[updated]`	integer (int64)	query	Records last Updated Unix timestamp (UTC). This will force the sort order to be Greater Than or Equal to the timestamp indicated.
`parameters[dividend_yield_operation]`	string , x ∈ { gt , gte , eq , lte , lt }	query	Specifies how to filter using dividend yield. gt = Greater Than, gte = Greater Than Equal, eq = Equal, lt = Less Than, lte = Less Than Equal
`parameters[dividend_yield]`	number (double)	query	The dividend yield amount to filter by. Defaults to using Equal To the amount indicated. 1 =100%eater Than or Equal To’, ‘Equal To’, ‘Less Than or Equal To’, and ‘Less Than’ filters respectively.

Responses

Code	Model	Description
`200 OK`	dividends	Success

Response (200 OK)

[
  {
    "id": "string",
    "date": "string (YYYY-DD-MM)",
    "updated": "integer",
    "isin": "string",
    "ticker": "string",
    "name": "string",
    "exchange": "string",
    "currency": "string",
    "frequency": "integer",
    "dividend": "string (double)",
    "dividend_prior": "string (double)",
    "dividend_type": "string",
    "dividend_yield": "string",
    "ex_dividend_date": "string",
    "payable_date": "string",
    "record_date": "string",
    "importance": "integer"
  }
]


token

GET /calendar/earnings

Returns the earnings data

Parameters

Name	Type	Location	Description
`accept`	string , x ∈ { application/json , application/xml (default) }	header	Specifies return format. Query parameters work the same for both formats.
`page`	integer	query	Page offset.
`pagesize`	integer	query	Number of results returned. Limit 1000
`parameters[date]`	string (YYYY-MM-DD)	query	Date to query for calendar data. Shorthand for date_from and date_to if they are the same. Defaults for latest.
`parameters[date_from]`	string (YYYY-MM-DD)	query	Date to query from point in time.
`parameters[date_to]`	string (YYYY-MM-DD)	query	Date to query to point in time.
`parameters[tickers]`	string (csv)	query	One or more ticker symbols separated by a comma. All calendar accept this parameter. Ignored by Economics.
`parameters[importance]`	integer , x ∈ { 0 , 1 , 2 , 3 , 4 , 5 }	query	The importance level to filter by. Uses Greater Than or Equal To the importance indicated
`parameters[updated]`	integer (int64)	query	Records last Updated Unix timestamp (UTC). This will force the sort order to be Greater Than or Equal to the timestamp indicated.

Responses

Code	Model	Description
`200 OK`		success

Response (200 OK)

{
  "earnings": [
    {
      "id": "string",
      "date": "string",
      "date_confirmed": "string (Y/N)",
      "time": "string (HH:MM:SS)",
      "isin": "string",
      "ticker": "string",
      "exchange": "string",
      "name": "string",
      "currency": "string",
      "period": "string",
      "period_year": "integer",
      "eps": "string",
      "eps_est": "string (double)",
      "eps_prior": "string (double)",
      "eps_surprise": "string (double)",
      "eps_surprise_percent": "string (double)",
      "revenue": "string",
      "revenue_est": "string",
      "revenue_prior": "string",
      "revenue_surprise": "string",
      "revenue_surprise_percent": "string (double)",
      "importance": "integer",
      "notes": "string",
      "updated": "integer"
    }
  ]
}


token

GET /calendar/economics

Returns the economic calendar data

Parameters

Name	Type	Location	Description
`accept`	string , x ∈ { application/json , application/xml (default) }	header	Specifies return format. Query parameters work the same for both formats.
`page`	integer	query	Page offset.
`pagesize`	integer	query	Number of results returned. Limit 1000
`parameters[date]`	string (YYYY-MM-DD)	query	Date to query for calendar data. Shorthand for date_from and date_to if they are the same. Defaults for latest.
`parameters[date_from]`	string (YYYY-MM-DD)	query	Date to query from point in time.
`parameters[date_to]`	string (YYYY-MM-DD)	query	Date to query to point in time.
`parameters[tickers]`	string (csv)	query	One or more ticker symbols separated by a comma. All calendar accept this parameter. Ignored by Economics.
`parameters[importance]`	integer , x ∈ { 0 , 1 , 2 , 3 , 4 , 5 }	query	The importance level to filter by. Uses Greater Than or Equal To the importance indicated
`parameters[updated]`	integer (int64)	query	Records last Updated Unix timestamp (UTC). This will force the sort order to be Greater Than or Equal to the timestamp indicated.
`country`	string (A-Z:3)	query	3-Digit Country Code

Responses

Code	Model	Description
`200 OK`	economics	success

Response (200 OK)

[
  {
    "id": "string",
    "date": "string (YYYY-MM-DD)",
    "time": "string (HH:MM)",
    "country": "string",
    "event_name": "string",
    "event_period": "string",
    "period_year": "integer",
    "actual": "string",
    "actual_t": "string",
    "consensus": "string",
    "consensus_t": "string",
    "prior": "string",
    "importance": "integer",
    "updated": "integer",
    "description": "string"
  }
]


token

GET /calendar/guidance

Returns guidance data

Parameters

Name	Type	Location	Description
`accept`	string , x ∈ { application/json , application/xml (default) }	header	Specifies return format. Query parameters work the same for both formats.
`page`	integer	query	Page offset.
`pagesize`	integer	query	Number of results returned. Limit 1000
`parameters[date]`	string (YYYY-MM-DD)	query	Date to query for calendar data. Shorthand for date_from and date_to if they are the same. Defaults for latest.
`parameters[date_from]`	string (YYYY-MM-DD)	query	Date to query from point in time.
`parameters[date_to]`	string (YYYY-MM-DD)	query	Date to query to point in time.
`parameters[tickers]`	string (csv)	query	One or more ticker symbols separated by a comma. All calendar accept this parameter. Ignored by Economics.
`parameters[importance]`	integer , x ∈ { 0 , 1 , 2 , 3 , 4 , 5 }	query	The importance level to filter by. Uses Greater Than or Equal To the importance indicated
`parameters[updated]`	integer (int64)	query	Records last Updated Unix timestamp (UTC). This will force the sort order to be Greater Than or Equal to the timestamp indicated.
`parameters[is_primary]`	string , x ∈ { Y , N , All }	query	Determines if guidance returned is primary, secondary or all. Default set to Y.
`country`	string (A-Z:3)	query	3-Digit Country Code

Responses

Code	Model	Description
`200 OK`	guidance	success

Response (200 OK)

[
  {
    "id": "string",
    "date": "string (YYYY-MM-DD)",
    "time": "string (HH:MM:SS)",
    "ticker": "string",
    "exchange": "string",
    "name": "string",
    "currency": "string",
    "period": "string",
    "period_year": "integer",
    "prelim": "string",
    "is_primary": "string",
    "eps_type": "string",
    "eps_guidance_est": "string (float)",
    "eps_guidance_max": "string (float)",
    "eps_guidance_min": "string (float)",
    "eps_guidance_prior_max": "string (float)",
    "eps_guidance_prior_min": "string (float)",
    "revenue_guidance_est": "string (float)",
    "revenue_guidance_max": "string (float)",
    "revenue_guidance_min": "string (float)",
    "revenue_guidance_prior_max": "string (float)",
    "revenue_guidance_prior_min": "string (float)",
    "importance": "string",
    "notes": "string",
    "updated": "integer (int64)"
  }
]


token

GET /calendar/ipos

Returns ipo data

Parameters

Name	Type	Location	Description
`accept`	string , x ∈ { application/json , application/xml (default) }	header	Specifies return format. Query parameters work the same for both formats.
`page`	integer	query	Page offset.
`pagesize`	integer	query	Number of results returned. Limit 1000
`parameters[date]`	string (YYYY-MM-DD)	query	Date to query for calendar data. Shorthand for date_from and date_to if they are the same. Defaults for latest.
`parameters[date_from]`	string (YYYY-MM-DD)	query	Date to query from point in time.
`parameters[date_to]`	string (YYYY-MM-DD)	query	Date to query to point in time.
`parameters[tickers]`	string (csv)	query	One or more ticker symbols separated by a comma. All calendar accept this parameter. Ignored by Economics.
`parameters[importance]`	integer , x ∈ { 0 , 1 , 2 , 3 , 4 , 5 }	query	The importance level to filter by. Uses Greater Than or Equal To the importance indicated
`parameters[updated]`	integer (int64)	query	Records last Updated Unix timestamp (UTC). This will force the sort order to be Greater Than or Equal to the timestamp indicated.

Responses

Code	Model	Description
`200 OK`	ipos	success

Response (200 OK)

[
  {
    "id": "string",
    "date": "string (YYYY-MM-DD)",
    "time": "string (HH:MM:SS)",
    "ticker": "string",
    "exchange": "string",
    "name": "string",
    "currency": "string",
    "pricing_date": "string",
    "price_min": "string",
    "price_max": "string",
    "deal_status": "string",
    "insider_lockup_days": "integer",
    "insider_lockup_date": "string",
    "offering_value": "integer (int64)",
    "offering_shares": "integer (int64)",
    "lead_underwriters": [
      "string"
    ],
    "other_underwriters": [
      "string"
    ],
    "underwriter_quiet_expiration_days": "string",
    "underwriter_quiet_expiration_date": "string",
    "notes": "string",
    "updated": "integer (int64)"
  }
]


token

GET /calendar/ratings

Returns analyst ratings data

Parameters

Name	Type	Location	Description
`accept`	string , x ∈ { application/json , application/xml (default) }	header	Specifies return format. Query parameters work the same for both formats.
`page`	integer	query	Page offset.
`pagesize`	integer	query	Number of results returned. Limit 1000
`parameters[date]`	string (YYYY-MM-DD)	query	Date to query for calendar data. Shorthand for date_from and date_to if they are the same. Defaults for latest.
`parameters[date_from]`	string (YYYY-MM-DD)	query	Date to query from point in time.
`parameters[date_to]`	string (YYYY-MM-DD)	query	Date to query to point in time.
`parameters[tickers]`	string (csv)	query	One or more ticker symbols separated by a comma. All calendar accept this parameter. Ignored by Economics.
`parameters[importance]`	integer , x ∈ { 0 , 1 , 2 , 3 , 4 , 5 }	query	The importance level to filter by. Uses Greater Than or Equal To the importance indicated
`parameters[updated]`	integer (int64)	query	Records last Updated Unix timestamp (UTC). This will force the sort order to be Greater Than or Equal to the timestamp indicated.
`parameters[action]`	string , x ∈ { Upgrades , Downgrades , Maintains , Lowers , Raises , Initiates Coverage On , Terminates Coverage On }	query	Filter by a specific action

Responses

Code	Model	Description
`200 OK`	ratings	success

Response (200 OK)

[
  {
    "id": "string",
    "date": "string (YYYY-MM-DD)",
    "time": "string (HH:MM:SS)",
    "ticker": "string",
    "exchange": "string",
    "name": "string",
    "currency": "string",
    "action_pt": "string",
    "action_company": "string",
    "rating_current": "string",
    "pt_current": "string",
    "rating_prior": "string",
    "pt_prior": "string",
    "url": "string (URL)",
    "url_calendar": "string (URI)",
    "url_news": "string (URI)",
    "analyst": "string",
    "analyst_name": "string",
    "importance": "string",
    "notes": "string",
    "updated": "integer (int64)"
  }
]


token

GET /calendar/ma

Returns the mergers and acquisitions data

Parameters

Name	Type	Location	Description
`accept`	string , x ∈ { application/json , application/xml (default) }	header	Specifies return format. Query parameters work the same for both formats.
`page`	integer	query	Page offset.
`pagesize`	integer	query	Number of results returned. Limit 1000
`parameters[date]`	string (YYYY-MM-DD)	query	Date to query for calendar data. Shorthand for date_from and date_to if they are the same. Defaults for latest.
`parameters[date_from]`	string (YYYY-MM-DD)	query	Date to query from point in time.
`parameters[date_to]`	string (YYYY-MM-DD)	query	Date to query to point in time.
`parameters[tickers]`	string (csv)	query	One or more ticker symbols separated by a comma. All calendar accept this parameter. Ignored by Economics.
`parameters[importance]`	integer , x ∈ { 0 , 1 , 2 , 3 , 4 , 5 }	query	The importance level to filter by. Uses Greater Than or Equal To the importance indicated
`parameters[updated]`	integer (int64)	query	Records last Updated Unix timestamp (UTC). This will force the sort order to be Greater Than or Equal to the timestamp indicated.
`parameters[date_sort]`	string , x ∈ { expected , completed , announced }	query	M&A date field to sort on

Responses

Code	Model	Description
`200 OK`	ma	success

Response (200 OK)

[
  {
    "id": "string",
    "date": "string (YYYY-MM-DD)",
    "date_expected": "string ([\"YYYY-MM-DD\", \"YYYY-QN\", \"YYYY-MM\"])",
    "date_completed": "string (YYYY-MM-DD)",
    "acquirer_ticker": "string",
    "acquirer_exchange": "string",
    "acquirer_name": "string",
    "target_ticker": "string",
    "target_exchange": "string",
    "target_name": "string",
    "currency": "string",
    "deal_type": "string",
    "deal_size": "number (double)",
    "deal_payment_type": "string",
    "deal_status": "string",
    "deal_terms_extra": "string",
    "importance": "integer",
    "notes": "string",
    "updated": "integer (int64)"
  }
]


token

GET /calendar/retail

Returns retail sales data

Parameters

Name	Type	Location	Description
`accept`	string , x ∈ { application/json , application/xml (default) }	header	Specifies return format. Query parameters work the same for both formats.
`page`	integer	query	Page offset.
`pagesize`	integer	query	Number of results returned. Limit 1000
`parameters[date]`	string (YYYY-MM-DD)	query	Date to query for calendar data. Shorthand for date_from and date_to if they are the same. Defaults for latest.
`parameters[date_from]`	string (YYYY-MM-DD)	query	Date to query from point in time.
`parameters[date_to]`	string (YYYY-MM-DD)	query	Date to query to point in time.
`parameters[tickers]`	string (csv)	query	One or more ticker symbols separated by a comma. All calendar accept this parameter. Ignored by Economics.
`parameters[importance]`	integer , x ∈ { 0 , 1 , 2 , 3 , 4 , 5 }	query	The importance level to filter by. Uses Greater Than or Equal To the importance indicated
`parameters[updated]`	integer (int64)	query	Records last Updated Unix timestamp (UTC). This will force the sort order to be Greater Than or Equal to the timestamp indicated.

Responses

Code	Model	Description
`200 OK`	retail	success

Response (200 OK)

[
  {
    "id": "string",
    "date": "string (YYYY-MM-DD)",
    "time": "string (HH:MM:SS)",
    "ticker": "string",
    "exchange": "string",
    "name": "string",
    "currency": "string",
    "period": "string",
    "period_year": "integer",
    "sss": "string (float)",
    "sss_est": "string (float)",
    "retail_surprise": "string",
    "importance": "string",
    "notes": "string",
    "updated": "integer (int64)"
  }
]


token

GET /calendar/splits

Returns the splits calendar data

Parameters

Name	Type	Location	Description
`accept`	string , x ∈ { application/json , application/xml (default) }	header	Specifies return format. Query parameters work the same for both formats.
`page`	integer	query	Page offset.
`pagesize`	integer	query	Number of results returned. Limit 1000
`parameters[date]`	string (YYYY-MM-DD)	query	Date to query for calendar data. Shorthand for date_from and date_to if they are the same. Defaults for latest.
`parameters[date_from]`	string (YYYY-MM-DD)	query	Date to query from point in time.
`parameters[date_to]`	string (YYYY-MM-DD)	query	Date to query to point in time.
`parameters[tickers]`	string (csv)	query	One or more ticker symbols separated by a comma. All calendar accept this parameter. Ignored by Economics.
`parameters[importance]`	integer , x ∈ { 0 , 1 , 2 , 3 , 4 , 5 }	query	The importance level to filter by. Uses Greater Than or Equal To the importance indicated
`parameters[updated]`	integer (int64)	query	Records last Updated Unix timestamp (UTC). This will force the sort order to be Greater Than or Equal to the timestamp indicated.

Responses

Code	Model	Description
`200 OK`	splits	success

Response (200 OK)

[
  {
    "id": "integer",
    "updated": "integer",
    "date": "string (YYYY-DD-MM)",
    "time": "string (HH:MM:SS)",
    "ticker": "string",
    "exchange": "string",
    "ratio": "string (x/x)",
    "optionable": "boolean",
    "date_ex": "string (YYYY-MM-DD)",
    "date_recorded": "string (YYYY-MM-DD)",
    "date_distribution": "string (YYYY-MM-DD)",
    "importance": "integer",
    "notes": "string"
  }
]


token

GET /calendar-removed

Returns the removed calendar data

Parameters

Name	Type	Location	Description
`accept`	string , x ∈ { application/json , application/xml (default) }	header	Specifies return format. Query parameters work the same for both formats.
`page`	integer	query	Page offset.
`pageSize`	integer	query	Number of results returned. Limit 1000. Default 50.
`type`	string , x ∈ { ratings , earnings , guidance , ipos , offering , economics , ma , retail , splits , dividends , conference calls }	query	Calendar type
`updated`	integer (int64)	query	Records removed after Unix timestamp (UTC). This will force the sort order to be Greater Than or Equal to the timestamp indicated.

Responses

Code	Model	Description
`200 OK`	calendar-removed	success

Response (200 OK)

[
  {
    "id": "string",
    "type": "string",
    "updated": "integer (int64)"
  }
]


token

Models

dividends: object

Property	Type	Description
`id`	string	Unique ID of this entry
`date`	string (YYYY-DD-MM)	Announced Date on calendar
`updated`	integer	Last updated timestamp, UTC
`isin`	string	ISIN identifier for the security. Optional based on client access.
`ticker`	string	Ticker Symbol (F, MSFT, etc...)
`name`	string	Name of security
`exchange`	string	Exchange (NYSE, NASDAQ, etc...)
`currency`	string	Currency the data is denominated in
`frequency`	integer	Frequency of the dividend
`dividend`	string (double)	Dividend value. Expected value is a double if set or empty if null.
`dividend_prior`	string (double)	Period prior dividend value. Expected value is a double if set or empty if null.
`dividend_type`	string	Type of dividend
`dividend_yield`	string	Yield of dividend. Expected value is a double if set or empty if null.
`ex_dividend_date`	string	Dividend Ex Date
`payable_date`	string	Dividend Payable Date
`record_date`	string	Dividend Recorded Date
`importance`	integer , x ∈ { 0 , 1 , 2 , 3 , 4 , 5 }	Subjective basis of how important event is to market. 5 = high

Structure (JSON)

{
  "id": "string",
  "date": "string (YYYY-DD-MM)",
  "updated": "integer",
  "isin": "string",
  "ticker": "string",
  "name": "string",
  "exchange": "string",
  "currency": "string",
  "frequency": "integer",
  "dividend": "string (double)",
  "dividend_prior": "string (double)",
  "dividend_type": "string",
  "dividend_yield": "string",
  "ex_dividend_date": "string",
  "payable_date": "string",
  "record_date": "string",
  "importance": "integer"
}

earnings: object[]

object

Property	Type	Description
`id`	string	-
`date`	string	Announced Date on Calendar
`date_confirmed`	string (Y/N)	If the report date was confirmed (vs est)
`time`	string (HH:MM:SS)	Announced Time on Calendar, 24hr format
`isin`	string	ISIN identifier for the security. Optional based on client access.
`ticker`	string	Ticker Symbol (F, MSFT, etc...)
`exchange`	string	Exchange (NYSE, NASDAQ, etc...)
`name`	string	Name of security
`currency`	string	Currency the data is denominated in
`period`	string , x ∈ { Q1 , Q2 , Q3 , Q4 }	Period of the earnings actual
`period_year`	integer	Period Year of the earnings actual
`eps`	string	Comparable and Adjusted Earnings Per Share
`eps_est`	string (double)	Adjusted EPS Consensus Aggregate Analyst Estimate
`eps_prior`	string (double)	Adjusted EPS from Prior Period
`eps_surprise`	string (double)	EPS deviation from estimate
`eps_surprise_percent`	string (double)	Deviation from estimate as percentage
`revenue`	string	Revenue
`revenue_est`	string	Revenue estimate
`revenue_prior`	string	Revenue value for previous period
`revenue_surprise`	string	Revenue deviation from estimate
`revenue_surprise_percent`	string (double)	Deviation from estimate as percentage
`importance`	integer , x ∈ { 0 , 1 , 2 , 3 , 4 , 5 }	Subjective basis of how important event is to market. 5 = high
`notes`	string	Additional notes provided by the Benzinga Newsdesk where applicable. Notes may include HTML.
`updated`	integer	Last updated timestamp, UTC

Structure (JSON)

[
  {
    "id": "string",
    "date": "string",
    "date_confirmed": "string (Y/N)",
    "time": "string (HH:MM:SS)",
    "isin": "string",
    "ticker": "string",
    "exchange": "string",
    "name": "string",
    "currency": "string",
    "period": "string",
    "period_year": "integer",
    "eps": "string",
    "eps_est": "string (double)",
    "eps_prior": "string (double)",
    "eps_surprise": "string (double)",
    "eps_surprise_percent": "string (double)",
    "revenue": "string",
    "revenue_est": "string",
    "revenue_prior": "string",
    "revenue_surprise": "string",
    "revenue_surprise_percent": "string (double)",
    "importance": "integer",
    "notes": "string",
    "updated": "integer"
  }
]

splits: object

Property	Type	Description
`id`	integer	Unique ID of this entry
`updated`	integer	Last updated timestamp, UTC
`date`	string (YYYY-DD-MM)	Announced Date on calendar
`time`	string (HH:MM:SS)	Announced Time on Calendar, 24hr format
`ticker`	string	Ticker Symbol (F, MSFT, etc...)
`exchange`	string	Exchange (NYSE, NASDAQ, etc...)
`ratio`	string (x/x)	Ratio of the split
`optionable`	boolean	is the script optionable?
`date_ex`	string (YYYY-MM-DD)	Ex date
`date_recorded`	string (YYYY-MM-DD)	Recorded date
`date_distribution`	string (YYYY-MM-DD)	Distribution date
`importance`	integer , x ∈ { 0 , 1 , 2 , 3 , 4 , 5 }	Subjective basis of how important event is to market. 5 = high
`notes`	string	Additional notes provided by the Benzinga Newsdesk where applicable. Notes may include HTML.

Structure (JSON)

{
  "id": "integer",
  "updated": "integer",
  "date": "string (YYYY-DD-MM)",
  "time": "string (HH:MM:SS)",
  "ticker": "string",
  "exchange": "string",
  "ratio": "string (x/x)",
  "optionable": "boolean",
  "date_ex": "string (YYYY-MM-DD)",
  "date_recorded": "string (YYYY-MM-DD)",
  "date_distribution": "string (YYYY-MM-DD)",
  "importance": "integer",
  "notes": "string"
}

economics: object

Property	Type	Description
`id`	string	Unique identifier for each data point
`date`	string (YYYY-MM-DD)	-
`time`	string (HH:MM)	Announced Time on Calendar, 24hr format
`country`	string	3-Character Country Code (USA, CA, etc...)
`event_name`	string	Economic Event
`event_period`	string	Period of Time (Q1, September, Third Week of August,...)
`period_year`	integer	Period Year
`actual`	string	Value of economic indicator
`actual_t`	string	Unit of actual field
`consensus`	string	Estimate for actual field
`consensus_t`	string	Unit for consensus field
`prior`	string	Value of actual field for previous period
`importance`	integer , x ∈ { 0 , 1 , 2 , 3 , 4 , 5 }	Subjective basis of how important event is to market. 5 = High
`updated`	integer	Last updated timestamp, UTC
`description`	string	Event Description

Structure (JSON)

{
  "id": "string",
  "date": "string (YYYY-MM-DD)",
  "time": "string (HH:MM)",
  "country": "string",
  "event_name": "string",
  "event_period": "string",
  "period_year": "integer",
  "actual": "string",
  "actual_t": "string",
  "consensus": "string",
  "consensus_t": "string",
  "prior": "string",
  "importance": "integer",
  "updated": "integer",
  "description": "string"
}

guidance: object

Property	Type	Description
`id`	string	Unique ID of this entry
`date`	string (YYYY-MM-DD)	Announced Date on Calendar
`time`	string (HH:MM:SS)	Announced Time on Calendar, 24hr format
`ticker`	string	Ticker symbol of company guidance data is for
`exchange`	string	Exchange (NYSE, NASDAQ, etc...)
`name`	string	The name of the publicly traded company that the guidance data is for
`currency`	string	Currency the data is denominated in
`period`	string , x ∈ { Q1 , Q2 , Q3 , Q4 }	-
`period_year`	integer	Period Year of the earnings actual
`prelim`	string , x ∈ { Y , N }	Yes or No for if guidance is a preliminary earnings report
`is_primary`	string , x ∈ { Y , N , All }	Specifies type of guidance returned - primary, secondary or all
`eps_type`	string , x ∈ { Adj , GAAP , FFO }	Reported EPS Type can be Adjusted, GAAP or FFO. FFO is only used for REITs.
`eps_guidance_est`	string (float)	Adjusted EPS Consensus Estimate
`eps_guidance_max`	string (float)	Adjusted EPS from Prior Period Max
`eps_guidance_min`	string (float)	Adjusted EPS from Prior Period Min
`eps_guidance_prior_max`	string (float)	Adjusted EPS from Prior Period Max
`eps_guidance_prior_min`	string (float)	Adjusted EPS from Prior Period Min
`revenue_guidance_est`	string (float)	Revenue guidance estimate
`revenue_guidance_max`	string (float)	Revenue guidance max
`revenue_guidance_min`	string (float)	Revenue guidance min
`revenue_guidance_prior_max`	string (float)	Revenue guidance max from previous period
`revenue_guidance_prior_min`	string (float)	Revenue guidance min from previous period
`importance`	string , x ∈ { 0 , 1 , 2 , 3 , 4 , 5 }	Subjective basis of how important event is to market. 5 = high
`notes`	string	Additional notes provided by the Benzinga Newsdesk where applicable. Notes may include HTML.
`updated`	integer (int64)	Last updated timestamp, UTC

Structure (JSON)

{
  "id": "string",
  "date": "string (YYYY-MM-DD)",
  "time": "string (HH:MM:SS)",
  "ticker": "string",
  "exchange": "string",
  "name": "string",
  "currency": "string",
  "period": "string",
  "period_year": "integer",
  "prelim": "string",
  "is_primary": "string",
  "eps_type": "string",
  "eps_guidance_est": "string (float)",
  "eps_guidance_max": "string (float)",
  "eps_guidance_min": "string (float)",
  "eps_guidance_prior_max": "string (float)",
  "eps_guidance_prior_min": "string (float)",
  "revenue_guidance_est": "string (float)",
  "revenue_guidance_max": "string (float)",
  "revenue_guidance_min": "string (float)",
  "revenue_guidance_prior_max": "string (float)",
  "revenue_guidance_prior_min": "string (float)",
  "importance": "string",
  "notes": "string",
  "updated": "integer (int64)"
}

ipos: object

Property	Type	Description
`id`	string	Unique ID of this entry
`date`	string (YYYY-MM-DD)	Date of IPO
`time`	string (HH:MM:SS)	Time of IPO
`ticker`	string	Ticker symbol for IPO
`exchange`	string	Exchange (NYSE, NASDAQ, etc...)
`name`	string	The name of the publicly traded company that the guidance data is for
`currency`	string	Currency the data is denominated in
`pricing_date`	string	date of IPO pricing
`price_min`	string	Minimum open price
`price_max`	string	Maximum open price
`deal_status`	string	status of IPO
`insider_lockup_days`	integer	Insider lockup period in days
`insider_lockup_date`	string	Insider lockup date
`offering_value`	integer (int64)	Value of IPO
`offering_shares`	integer (int64)	Number of shares offered in IPO
`lead_underwriters`	string[]	List of lead underwriter(s)
`other_underwriters`	string[]	List of other/secondary underwriter(s)
`underwriter_quiet_expiration_days`	string	Underwriter quite expiration period in days
`underwriter_quiet_expiration_date`	string	Underwriter quite expiration date
`notes`	string	Additional notes provided by the Benzinga Newsdesk where applicable. Notes may include HTML.
`updated`	integer (int64)	Last updated timestamp, UTC

Structure (JSON)

{
  "id": "string",
  "date": "string (YYYY-MM-DD)",
  "time": "string (HH:MM:SS)",
  "ticker": "string",
  "exchange": "string",
  "name": "string",
  "currency": "string",
  "pricing_date": "string",
  "price_min": "string",
  "price_max": "string",
  "deal_status": "string",
  "insider_lockup_days": "integer",
  "insider_lockup_date": "string",
  "offering_value": "integer (int64)",
  "offering_shares": "integer (int64)",
  "lead_underwriters": [
    "string"
  ],
  "other_underwriters": [
    "string"
  ],
  "underwriter_quiet_expiration_days": "string",
  "underwriter_quiet_expiration_date": "string",
  "notes": "string",
  "updated": "integer (int64)"
}

ma: object

Property	Type	Description
`id`	string	Undque ID of this entry
`date`	string (YYYY-MM-DD)	Date of deal announcment
`date_expected`	string (["YYYY-MM-DD", "YYYY-QN", "YYYY-MM"])	Date deal is expected to complete
`date_completed`	string (YYYY-MM-DD)	Date of deal completion
`acquirer_ticker`	string	Ticker symbol of acquiring company
`acquirer_exchange`	string	Exchange for the acquirer ticker
`acquirer_name`	string	Name of acquiring company
`target_ticker`	string	Ticker symbol of target company
`target_exchange`	string	Exchange for the target ticker
`target_name`	string	Name of the target company
`currency`	string	Currency the data is denominated in
`deal_type`	string , x ∈ { Acquisition , Merger , Asset Sale }	Type of deal
`deal_size`	number (double)	Aggregate deal value
`deal_payment_type`	string , x ∈ { Cash , Stock , Cash & Stock }	Deal payment type
`deal_status`	string , x ∈ { Rumored , Announced , Regulatory Review , Completed , Canceled }	Deal status
`deal_terms_extra`	string	Any additional relevant terms
`importance`	integer	Benzinga assigned score for how important an earning is
`notes`	string	Any supplimentarty details. Used in conjunction with Deal Terms for non term notes
`updated`	integer (int64)	Last updated timestamp, UTC

Structure (JSON)

{
  "id": "string",
  "date": "string (YYYY-MM-DD)",
  "date_expected": "string ([\"YYYY-MM-DD\", \"YYYY-QN\", \"YYYY-MM\"])",
  "date_completed": "string (YYYY-MM-DD)",
  "acquirer_ticker": "string",
  "acquirer_exchange": "string",
  "acquirer_name": "string",
  "target_ticker": "string",
  "target_exchange": "string",
  "target_name": "string",
  "currency": "string",
  "deal_type": "string",
  "deal_size": "number (double)",
  "deal_payment_type": "string",
  "deal_status": "string",
  "deal_terms_extra": "string",
  "importance": "integer",
  "notes": "string",
  "updated": "integer (int64)"
}

ratings: object

Property	Type	Description
`id`	string	Unique ID of this entry
`date`	string (YYYY-MM-DD)	Date for rating
`time`	string (HH:MM:SS)	Time for rating
`ticker`	string	Ticker symbol of company that is subject of rating
`exchange`	string	Exchange (NYSE, NASDAQ, etc...)
`name`	string	Name of company that is subject of rating
`currency`	string	Currency the data is denominated in
`action_pt`	string , x ∈ { , Raises , Lowers }	Description of the change in price target for rating
`action_company`	string , x ∈ { Upgrades , Downgrades , Maintains , Lowers , Raises , Initiates Coverage On , Terminates Coverage On }	Description of the action for rating
`rating_current`	string	The analyst's rating for the company
`pt_current`	string	Analyst's current price target
`rating_prior`	string	Prior analyst rating for the company
`pt_prior`	string	Analyst's prior price target
`url`	string (URL)	URL for analyst ratings page for this ticker on Benzinga.com
`url_calendar`	string (URI)	URI for analyst ratings page for this ticker on Benzinga.com
`url_news`	string (URI)	URI for analyst ratings news articles for this ticker on Benzinga.com
`analyst`	string	Name of the analyst firm that published the rating
`analyst_name`	string	Name of the analyst (person) that published the rating
`importance`	string , x ∈ { 0 , 1 , 2 , 3 , 4 , 5 }	Subjective Basis of How Important Event is to Market. 5 = High
`notes`	string	Additional notes provided by the Benzinga Newsdesk where applicable. Notes may include HTML.
`updated`	integer (int64)	Last updated timestamp, UTC

Structure (JSON)

{
  "id": "string",
  "date": "string (YYYY-MM-DD)",
  "time": "string (HH:MM:SS)",
  "ticker": "string",
  "exchange": "string",
  "name": "string",
  "currency": "string",
  "action_pt": "string",
  "action_company": "string",
  "rating_current": "string",
  "pt_current": "string",
  "rating_prior": "string",
  "pt_prior": "string",
  "url": "string (URL)",
  "url_calendar": "string (URI)",
  "url_news": "string (URI)",
  "analyst": "string",
  "analyst_name": "string",
  "importance": "string",
  "notes": "string",
  "updated": "integer (int64)"
}

retail: object

Property	Type	Description
`id`	string	Unique ID of this entry
`date`	string (YYYY-MM-DD)	Date for sales announcement
`time`	string (HH:MM:SS)	Time for sales announcement
`ticker`	string	Ticker symbol of security
`exchange`	string	Name of exchange where security is listed
`name`	string	Name of security
`currency`	string	Currency the data is denominated in
`period`	string , x ∈ { Q1 , Q2 , Q3 , Q4 }	Period of the retail sales
`period_year`	integer	Year for the period of the retail sales
`sss`	string (float)	Same-Store Sales
`sss_est`	string (float)	Same-Store Sales estimate
`retail_surprise`	string	Deviation from estimate
`importance`	string , x ∈ { 0 , 1 , 2 , 3 , 4 , 5 }	Subjective Basis of How Important Event is to Market. 5 = High
`notes`	string	Additional notes provided by the Benzinga Newsdesk where applicable. Notes may include HTML.
`updated`	integer (int64)	Last updated timestamp, UTC

Structure (JSON)

{
  "id": "string",
  "date": "string (YYYY-MM-DD)",
  "time": "string (HH:MM:SS)",
  "ticker": "string",
  "exchange": "string",
  "name": "string",
  "currency": "string",
  "period": "string",
  "period_year": "integer",
  "sss": "string (float)",
  "sss_est": "string (float)",
  "retail_surprise": "string",
  "importance": "string",
  "notes": "string",
  "updated": "integer (int64)"
}

conferenceCalls: object

Property	Type	Description
`id`	string	Unique ID of this entry
`date`	string (YYYY-MM-DD)	Announced Date on Calendar
`time`	string (HH:MM:SS)	Announced Time on Calendar
`name`	string	Name of company
`exchange`	string	Exchange (NYSE, NASDAQ, etc...)
`ticker`	string	Ticker symbol of company
`start_time`	string (HH:MM:SS)	Time of earnings conference call, in local time
`phone_num`	string (NNN-NNN-NNNN)	Phone number of conference call
`international_num`	string (NNN-NNN-NNNN)	International number to call if outside USA
`reservation_num`	string (NNN-NNN-NNNN)	Reservation number for conference call if avaliable
`access_code`	string	Access code for conference call if available
`webcase_url`	string (URI)	URI of webcast for conference call if avaliable
`importance`	string , x ∈ { 0 , 1 , 2 , 3 , 4 , 5 }	Subjective Basis of How Important Event is to Market. 5 = High
`notes`	string	Additional notes provided by the Benzinga Newsdesk where applicable. Notes may include HTML.
`updated`	integer (int64)	Last updated timestamp, UTC

Structure (JSON)

{
  "id": "string",
  "date": "string (YYYY-MM-DD)",
  "time": "string (HH:MM:SS)",
  "name": "string",
  "exchange": "string",
  "ticker": "string",
  "start_time": "string (HH:MM:SS)",
  "phone_num": "string (NNN-NNN-NNNN)",
  "international_num": "string (NNN-NNN-NNNN)",
  "reservation_num": "string (NNN-NNN-NNNN)",
  "access_code": "string",
  "webcase_url": "string (URI)",
  "importance": "string",
  "notes": "string",
  "updated": "integer (int64)"
}

calendar-removed: object

Property	Type	Description
`id`	string	id of removed calendar content
`type`	string , x ∈ { ratings , earnings , guidance , ipo , offering , economics , ma , retail , splits , dividends , conference calls }	Calendar type of removed content
`updated`	integer (int64)	UTC Unix epoch timestamp (seconds)

Structure (JSON)

{
  "id": "string",
  "type": "string",
  "updated": "integer (int64)"
}

Documentation

Calendar API Reference

API Endpoint

Response Content-Types

Schemes

Version

Authentication

token authentication

Playground

Endpoints

GET /calendar/conference-calls

Parameters

Responses

Response (200 OK)

GET /calendar/dividends

Parameters

Responses

Response (200 OK)

GET /calendar/earnings

Parameters

Responses

Response (200 OK)

GET /calendar/economics

Parameters

Responses

Response (200 OK)

GET /calendar/guidance

Parameters

Responses

Response (200 OK)

GET /calendar/ipos

Parameters

Responses

Response (200 OK)

GET /calendar/ratings

Parameters

Responses

Response (200 OK)

GET /calendar/ma

Parameters

Responses

Response (200 OK)

GET /calendar/retail

Parameters

Responses

Response (200 OK)

GET /calendar/splits

Parameters

Responses

Response (200 OK)

GET /calendar-removed

Parameters

Responses

Response (200 OK)

Models

dividends: object

Structure (JSON)

earnings: object[]

Structure (JSON)

splits: object

Structure (JSON)

economics: object

Structure (JSON)

guidance: object

Structure (JSON)

ipos: object

Structure (JSON)

ma: object

Structure (JSON)

ratings: object

Structure (JSON)

retail: object

Structure (JSON)

conferenceCalls: object

Structure (JSON)

calendar-removed: object

Structure (JSON)

`token` authentication