Warning

The YCharts API is available to our API customers for their internal use only. Any redistribution or commercial use of data from the API is strictly prohibited without prior written consent from YCharts. For more details on our API’s capabilities and pricing please contact sales@ycharts.com or call (866) 965-7552.

Company Dividends

The Company Dividends Endpoint is used to return a list of dividend objects that within the date range specified by the optional start and end date parameters.

Request Info

Request Method	GET
URL	https://api.ycharts.com/v3/companies/symbol[s]/dividends?start_date=start_date&end_date=end_date

Request Parameters

Parameter	Required	Description
symbol[s]	Y	The exchange symbol for a company, or a comma separated list of exchange symbols.
start_date	N	The first ex date of the desired date range.
end_date	N	The last ex date of the desired data range.
dividend_type	N	The Dividend Type

Dividend Type Options

Filter	Description
normal	Normal
non_qualified	Non-qualified
qualified	Qualified
tax_free_income	Tax-free Income
interest_income	Interest Income
foreign	Foreign
domestic	Domestic
cap_gains	Capital Gains
long_term	Long Term Capital Gains
short_term	Short Term Capital Gains
mid_term	Middle Term Capital Gains
roc	ROC
special	Special

Note

• There is a maximum of 100 symbols per request.

Response Info

The response will contain one or more company objects. The key for each company object is the exchange symbol passed in the request.

Company Object Fields

Field	Type	Description
meta	Meta	This object contains information about the query for the company object
results	Results	This object contains one or more dividend event objects.

Dividend Object Fields

Field	Type	Description
dividend_amount	decimal	Dividend Amount
adjusted_dividend_amount	decimal	Adjusted Dividend Amount
dividend_type	string	Dividend Type
currency_code	string	Currency Code
ex_date	date	Ex Date
declared_date	date	Declared Date
record_date	date	Record Date
pay_date	date	Pay Date

Examples

The following is an example successful request for 1 company.

Request URL

https://api.ycharts.com/v3/companies/AAPL/dividends?start_date=-2015-01-01&end_date=2015-06-01

Response

{
    "meta": {
        "status": "ok",
        "url": "https://api.ycharts.com/v3/companies/AAPL/dividends?start_date=-2015-01-01&end_date=2015-06-01"
    },
    "response": {
        "AAPL": {
            "meta": {
                "status": "ok"
            },
            "results": [
               {
                   "adjusted_dividend_amount": 0.47,
                   "currency_code": "USD",
                   "declared_date": "2015-01-27",
                   "dividend_amount": 0.47,
                   "dividend_type": "normal",
                   "ex_date": "2015-02-05",
                   "pay_date": "2015-02-12",
                   "record_date": "2015-02-09"
               },
               {
                   "adjusted_dividend_amount": 0.52,
                   "currency_code": "USD",
                   "declared_date": "2015-04-28",
                   "dividend_amount": 0.52,
                   "dividend_type": "normal",
                   "ex_date": "2015-05-07",
                   "pay_date": "2015-05-14",
                   "record_date": "2015-05-11"
               }
            ]
        }
    }
}

The following is an example successful request for multiple companies.

Request URL

https://api.ycharts.com/v3/companies/AAPL,MSFT/dividends?start_date=-2015-01-01&end_date=2015-06-01

Response

{
    "meta": {
        "status": "ok",
        "url": "https://api.ycharts.com/v3/companies/AAPL,MSFT/dividends?start_date=-2015-01-01&end_date=2015-06-01"
    },
    "response": {
        "AAPL": {
            "meta": {
                "status": "ok"
            },
            "results": [
               {
                   "adjusted_dividend_amount": 0.47,
                   "currency_code": "USD",
                   "declared_date": "2015-01-27",
                   "dividend_amount": 0.47,
                   "dividend_type": "normal",
                   "ex_date": "2015-02-05",
                   "pay_date": "2015-02-12",
                   "record_date": "2015-02-09"
               },
               {
                   "adjusted_dividend_amount": 0.52,
                   "currency_code": "USD",
                   "declared_date": "2015-04-28",
                   "dividend_amount": 0.52,
                   "dividend_type": "normal",
                   "ex_date": "2015-05-07",
                   "pay_date": "2015-05-14",
                   "record_date": "2015-05-11"
               }
            ]
        },
        "MSFT": {
           "meta": {
              "status": "ok"
           },
           "results": [
               {
                   "adjusted_dividend_amount": 0.31,
                   "currency_code": "USD",
                   "declared_date": "2014-12-03",
                   "dividend_amount": 0.31,
                   "dividend_type": "normal",
                   "ex_date": "2015-02-17",
                   "pay_date": "2015-03-12",
                   "record_date": "2015-02-19"
               },
               {
                   "adjusted_dividend_amount": 0.31,
                   "currency_code": "USD",
                   "declared_date": "2015-03-10",
                   "dividend_amount": 0.31,
                   "dividend_type": "normal",
                   "ex_date": "2015-05-19",
                   "pay_date": "2015-06-11",
                   "record_date": "2015-05-21"
               }
           ]
    }

    }
}

The following is an example incorrect request with an invalid date parameter.

Request URL

https://api.ycharts.com/v3/companies/AAPL/dividends?start_date=-2015-01-01&end_date=bad-date

Response

{
    "meta": {
        "error_code": 400,
        "error_message": "Invalid end_date format.",
        "status": "error",
        "url": "https://api.ycharts.com/v3/companies/AAPL,MSFT/dividends?start_date=2015-01-01&end_date=bad-date"
    },
    "response": {}
}