alt text

Benzinga's Python Client Library's Documentation

Benzinga's Python client library focuses on financial data methods, that can be used for quantitative analysis, and on news data from Benzinga, that can help give meaningful insights that complement quantitative data.

Table of Contents

Getting Started

The installation process varies depending on your python version and system used. The basic installation instructions are as follows:

pip install benzinga

Alternatively, the package can be installed by using:

pip3 install benzinga

Once you have successfully installed the package, you can either import the Financial Data module, for quantitative financial data:

from benzinga import financial_data

or you can import the Benzinga News Data module, if you're looking into financial news:

from benzinga import news_data

Your Key

Api Key To initiate a class, an API key is used, for authentication purposes. Contact us if you don't yet have a key, we will take care of you!

Sample API Key (type: str) : "testkey892834789s9s8abshtuy"

Sample Test Financial Data Module

  1. Initiating the class:
from benzinga import financial_data
api_key = "testkey892834789s9s8abshtuy"
fin = financial_data.Benzinga(api_key)
  1. A sample test run to get ratings on a stock. (Returns a JSON object):
stock_ratings = fin.ratings()
  1. Since fin.ratings() returns a JSON dict, for a better view of the dict, you can call the fin.output() method on the result. Example:
fin.output(stock_ratings)

Sample Test News Data Module

  1. Initiating the class:
from benzinga import news_data
api_key = "testkey892834789s9s8abshtuy"
paper = news_data.News(api_key)
  1. A sample test run to get general news. (Returns a JSON Object)
stories = paper.news()
  1. Since fin.news() returns a JSON dict, for a better view of the dict, you can call the fin.output() method on the result. Example:
paper.output(stories)

It is important to note that for both the Financial Data Module and the News Data Module, there are many optional parameters for the methods. Below is a detailed listing of possible methods for the Financial Data Module and the news Data Module, their method call names, arguments, and what they return.

Financial Data Methods:

Chart

fin.bars()

Public Method: Benzinga Bars looks at detailed price values over a period of time.

  • Arguments:

    • Required - company_tickers (str)
    • Required - date_from (str) For date_from, you can enter "YTD" for the first trading day of the year. "1d", "5d" or "1m". You can also enter the date from in the "YY-MM-DD"format too.
    • Optional:
    • date_to (str) - "YY-MM-DD"
    • interval *(str) - "1MONTH", "1W", "1D", "1H", "15M". Default: "5M"
  • Returns:

    • open, high, low, close, volume, time, dateTime

Delayed Quote

fin.delayed_quote()

Public Method: Benzinga Quote looks at many different attributes of the ticker like high, low, close etc

  • Arguments:

    • Required - company_tickers (str)
    • Optional
    • cik (str) - cik identifier
    • isin (str)
  • Returns:

    • date, previousClose, change, changePercent, fiftyTwoWeekHigh, fiftyTwoWeekLow, currency, last, tradingHalted, volume, previousCloseDate

Dividends

fin.dividends()

Public Method: Benzinga Dividends looks at the relevant dividend information for a company.

  • Arguments:

    • Optional:
    • page (int) - page offset
    • pagesize (int) - limit of results returned
    • date_asof (str) - "YYYY-MM-DD"
    • date_from (str) - "YYYY-MM-DD"
    • date_to (str) - "YYYY-MM-DD"
    • company_tickers (str)
    • importance - (int) - not tested yet.
    • date_sort - (str) - Dividend date field to sort on ("ex", "payable", "record")
    • updated_params (int64) - records last updated unix time stamp. Forces the sort order to be greater or equal to the time stamp indicated.
    • div_yield_operation (str) - to filter the div yield by for eg. "gt", "gte", "eq", "lte", "lt". Not tested
    • div_yield (int) - div yield amount fo filter by. "1" for 100% or above.
  • Returns:

    • the id, date, updated, isin, ticker, name, exchange, frequency, dividend, dividend prior, dividend type, dividend yield, ex-dividend date, payable date, record date, importance

Ratings

fin.ratings()

Public Method: Benzinga Ratings looks at ratings from different firms

  • Arguments:

    • Optional:
    • page (int) - page offset
    • pagesize (int) - limit of results returned
    • date_asof (str) - "YYYY-MM-DD"
    • date_from (str) - "YYYY-MM-DD"
    • date_to (str) - "YYYY-MM-DD"
    • company_tickers (str)
    • importance - (int) - not tested yet.
    • date_sort - (str) - Dividend date field to sort on
    • updated_params (int64) - records last updated unix time stamp. Forces the sort order to be greater or equal to the time stamp indicated.
    • action - (str) - " Upgrades , Downgrades , Maintains , Lowers , Raises , Initiates Coverage On , Terminates Coverage On"
  • Returns:

    • id, date, time, ticker, exchange, name, action_pt, action_company, rating_current, pt_current, rating_prior, pt_prior, url, importance, updated, url_calendar, url_news, analyst, analyst_name

Earnings

fin.earnings()

Public Method: Benzinga Earnings looks at the quarterly earnings reports for different companies.

  • Arguments:

    • Optional:
    • page (int) - page offset
    • pagesize (int) - limit of results returned
    • date_asof (str) - "YYYY-MM-DD"
    • date_from (str) - "YYYY-MM-DD"
    • date_to (str) - "YYYY-MM-DD"
    • company_tickers (str)
    • importance - (int) - not tested yet.
    • date_sort - (str) - Dividend date field to sort on
    • updated_params (int64) - records last updated unix time stamp. Forces the sort order to be greater or equal to the time stamp indicated.
  • Returns:

    • id, date, date confirmed, time, isin, ticker, exchange, name, period, period_year, eps, eps_est, eps_prior, eps_surprise, eps_surprise_percent, revenue, revenue est, revenue_prior, revenue_surprise, revenue_surprise_percent, importance, updated

Splits

fin.splits()

Public Method: Benzinga Splits looks at the stock splits calendar data

  • Arguments:

    • Optional:
    • page (int) - page offset
    • pagesize (int) - limit of results returned
    • date_asof (str) - "YYYY-MM-DD"
    • date_from (str) - "YYYY-MM-DD"
    • date_to (str) - "YYYY-MM-DD"
    • company_tickers (str)
    • importance - (int) - not tested yet.
    • date_sort - (str) - Dividend date field to sort on
    • updated_params (int64) - records last updated unix time stamp. Forces the sort order to be greater or equal to the time stamp indicated.
  • Returns:

    • id, updated, date, time, ticker, exchange, importance, ratio, optionable, date_ex, date_recorded, date_distribution

Economics

fin.economics()

Public Method: Benzinga Economics looks at different economic events in a country.

  • Arguments:

    • Optional:
    • page (int) - page offset
    • pagesize (int) - limit of results returned
    • date_asof (str) - "YYYY-MM-DD"
    • date_from (str) - "YYYY-MM-DD"
    • date_to (str) - "YYYY-MM-DD"
    • importance - (int) - not tested yet.
    • date_sort - (str) - Dividend date field to sort on
    • updated_params (int64) - records last updated unix time stamp. Forces the sort order to be greater or equal to the time stamp indicated.
    • country (str) - 3 digit country code
  • Returns:

    • id, date, time, country, event_name, event_period, period_year, actual, actual_t consensus, consensus_t, prior, importance, updated, description

Guidance

fin.guidance()

Public Method: Benzinga Guidance looks at different attributes like revenue guidance etc.

  • Arguments:
    • Optional:
    • page (int) - page offset
    • pagesize (int) - limit of results returned
    • date_asof (str) - "YYYY-MM-DD"
    • date_from (str) - "YYYY-MM-DD"
    • date_to (str) - "YYYY-MM-DD"
    • company_tickers (str)
    • importance - (int) - not tested yet.
    • date_sort - (str) - Dividend date field to sort on
    • updated_params (int64) - records last updated unix time stamp. Forces the sort order to be greater or equal to the time stamp indicated.
    • country (str) - 3 digit country code
  • Returns:
    • id, date, time, ticker, exchange, name, period, period_year, prelim, eps_guidance_est, eps_guidance_max, eps_guidance_min, eps_guidance_prior_max, eps_guidance_prior_min, revenue_guidance_est, revenue_guidance_max, revenue_guidance_min, revenue_guidance_prior_max , revenue_guidance_prior_min, importance, updated

IPO

fin.ipo()

Public Method: Benzing IPO looks at initial public offering data for companies.

  • Arguments:
    • Optional:
    • page (int) - page offset
    • pagesize (int) - limit of results returned
    • date_asof (str) - "YYYY-MM-DD"
    • date_from (str) - "YYYY-MM-DD"
    • date_to (str) - "YYYY-MM-DD"
    • company_tickers (str)
    • importance - (int) - not tested yet.
    • date_sort - (str) - Dividend date field to sort on
    • updated_params (int64) - records last updated unix time stamp. Forces the sort order to be greater or equal to the time stamp indicated.
  • Returns:
    • id, date, time, ticker, exchange, name, pricing_date, price_min, price_max, deal_status, insider_lockup_days, insider_lockup_date, offering_value, offering_shares, lead_underwriters, underwriter_quiet_expiration_days, underwriter_quiet_expiration_date, update

Conference Calls

fin.conference_calls()

Public Method: Benzinga Conference calls looks at conference calls.

  • Arguments:

    • Optional:
    • page (int) - page offset
    • pagesize (int) - limit of results returned
    • date_asof (str) - "YYYY-MM-DD"
    • date_from (str) - "YYYY-MM-DD"
    • date_to (str) - "YYYY-MM-DD"
    • company_tickers (str)
    • importance - (int) - not tested yet.
    • date_sort - (str) - Dividend date field to sort on
    • updated_params (int64) - records last updated unix time stamp. Forces the sort order to be greater or equal to the time stamp indicated.
    • country (str) - 3 digit country code
  • Returns:

    • id, date, time, ticker, exchange, name, start_time, phone_num, international_line, reservation_num, access_code, webcase_url, importance, updated

Fundamentals

fin.fundamentals()

Public Method: Benzinga Fundamentals looks at overall financial data for a company.

  • Arguments:

    • Required - company_tickers (str)
    • Optional:
    • isin (str) - specifies company data to return.
    • cik (str) - cik identifier
    • date_asof (str) "YYYY-MM-DD"
  • Returns:

    • company, companyProfile, shareClass, earningReports, financialStatements, operation earning and valuation ratios, alphaBeta

Financials

fin.financials()

Public Method: Benzinga Financials looks at overall financial data like for a company.

  • Arguments:

    • Required - company_tickers (str)
    • Optional:
    • isin (str) - specifies company data to return.
    • cik (str) - cik identifier
    • date_asof (str) "YYYY-MM-DD"
    • period (str) - select from (3M , 6M , 9M , 12M , 1Y)
    • reporttype (str) - select from (TTM, A (default), R,P)
  • Returns:

    • company, financials such as balance sheet information, assets and liabilities

Valuation Ratios

fin.valuation_ratios()

Public Method: Benzinga Valuation Ratios looks at overall financial data like for a company.

  • Arguments:
    • Required - company_tickers (str)
    • Optional:
    • isin (str) - specifies company data to return.
    • cik (str) - cik identifier
    • date_asof (str) "YYYY-MM-DD"
  • Returns:
    • different attributes of the valuation ratios

Earning Ratios

fin.earning_ratios()

Public Method: Benzinga Earning Ratios

  • Arguments:
    • Required - company_tickers (str)
    • Optional:
    • isin (str) - specifies company data to return.
    • cik (str) - cik identifier
    • date_asof (str) "YYYY-MM-DD"
  • Returns:
    • different attributes of the earning ratios

Operation Ratios

fin.operation_ratios()

Public Method: Benzinga Operation Ratios

  • Arguments:

    • Required - company_tickers (str)
    • Optional:
    • isin (str) - specifies company data to return.
    • cik (str) - cik identifier
    • date_asof (str) - "YYYY-MM-DD"
  • Returns:

    • different attributes of the operation ratios

Share Class

fin.share_class()

Public Method: Benzinga Share Class

  • Arguments:

    • Required - company_tickers (str)
    • Optional:
    • isin (str) - specifies company data to return.
    • cik (str) - cik identifier
    • date_asof (str) - "YYYY-MM-DD"
  • Returns:

    • different attributes of the share class.

Earning Reports

fin.earning_reports()

Public Method: Benzinga Earning Reports looks at overall earning reports for a company.

  • Arguments:

    • Required - company_tickers (str)
    • Optional:
    • isin (str) - specifies company data to return.
    • cik (str) - cik identifier
    • date_asof (str) - "YYYY-MM-DD"
  • Returns:

    • different attributes of the earning reports.

Alpha Beta

fin.alpha_beta()

Public Method: Benzinga Alpha Beta

  • Arguments:

    • Required - company_tickers (str)
    • Optional:
    • isin (str) - specifies company data to return.
    • cik (str) - cik identifier
    • date_asof (str) - "YYYY-MM-DD"
  • Returns:

    • different attributes of alphabeta.

Company Profile

fin.company_profile()

Public Method: Benzinga Company Profile

  • Arguments:

    • Required - company_tickers (str)
    • Optional:
    • isin (str) - specifies company data to return.
    • cik (str) - cik identifier
    • date_asof (str) - "YYYY-MM-DD"
  • Returns:

    • different attributes of company profile.

Company

fin.company()

Public Method: Benzinga Company

  • Arguments:

    • Required - company_tickers (str)
    • Optional:
    • isin (str) - specifies company data to return.
    • cik (str) - cik identifier
    • date_asof (str) - "YYYY-MM-DD"
  • Returns:

    • different attributes of the company.

Asset Classification

fin.asset_classification()

Public Method: Benzinga Asset Classification

  • Arguments:

    • Required - company_tickers (str)
    • Optional:
    • isin (str) - specifies company data to return.
    • cik (str) - cik identifier
    • date_asof (str) - "YYYY-MM-DD"
  • Returns:

    • different attributes of the asset classification.

Summary

fin.summary()

Public Method: Summary

  • Arguments:

    • Required - company_tickers (str)
    • Optional:
    • isin (str) - specifies company data to return.
    • cik (str) - cik identifier
    • date_asof (str) - "YYYY-MM-DD"
  • Returns:

    • different attributes of the summary.

Logos

fin.logos()

Public Method: Benzinga Logos

  • Arguments:

    • Required - company_tickers (str)
    • Optional:
    • filters (str) - specifies company data to return.
  • Returns:

    • different attributes of the logos

News Data:

fin.news()

News

Public Method: Benzinga News

  • Arguments:

    • Optional:
    • pagesize (int) - default is 15
    • page (int) - default is 0
    • display_output (str) - select from (full, abstract, headline)
    • base_date (str) - "YYYY-MM-DD" The date to query for calendar data. Shorthand for date_from and date_to if they are the same. Defaults for latest.
    • date_from (str) - "YYYY-MM-DD"
    • date_to (str) - "YYYY-MM-DD"
    • last_id (str) - The last ID to start paging from and sorted by and sorted by the last updated date.
    • updated_since (str) - he last updated unix timestamp (UTC) to pull and sort by.
    • publish_since (str) - The last publish unix timestamp (UTC) to pull and sort by.
    • company_tickers (str)
    • channel (str) - multiple channels separated by comma.
  • Returns:

    • Author, created, updated, title, teaser, body, url, image, channels, stocks, tags

Top News

paper.top_news()

Public Method: Benzinga Top News

  • Arguments:

    • Optional:
    • type (str) - The type of content to select
    • channel (str) - multiple channels separated by comma.
    • limit (str) - max period
    • display_output (str) - select from (full, abstract, headline)
  • Returns:

    • Author, created, updated, title, teaser, body, url, image, channels, stocks, tags