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/ |
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.
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. |
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": {}
}