Introduction
Welcome to the Custom Stock Alerts API! You can use this to access CSA endpoints, which can get information on data points for stocks and for stock return calculations.
Authentication
Custom Stock Alerts uses an API token to allow access to the API. You can get your API from the My Account page after registering for a paid access plan.
The API expects the API key to be included in all API requests to the server in a parameter that looks like the following:
key=YOUR_KEY
Stock Returns
Get Stock Returns
This endpoint runs stock return calculations for the provided parameters.
HTTP Request
https://api.customstockalerts.com/v1/getStockReturn?symbol=GOOG&startDate=1/1/2018&endDate=1/1/2019&compareTo=SPY&key=DEMO_KEY
Excel Request
=WEBSERVICE("https://api.customstockalerts.com/v1/getStockReturn?symbol=GOOG&startDate=1/1/2018&endDate=1/1/2019&compareTo=SPY&key=DEMO_KEY")
Google Sheets Request
=ImportData("https://api.customstockalerts.com/v1/getStockReturn?symbol=GOOG&startDate=1/1/2018&endDate=1/1/2019&compareTo=SPY&key=DEMO_KEY")
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| key | true | This is your API key from the My Account page. |
| symbol | true | This is the stock ticker to use, single value expected |
| startDate | true | MM/dd/yyyy format or days since 1900 (e.g. 43240 used in Excel) |
| endDate | false | MM/dd/yyyy format or days since 1900 (e.g. 43240 used in Excel) |
| compareTo | false | Enter another ticker symbol to compare results against. Returned value will be the delta between the two investments. For example; a positive number will mean the “symbol” ticker outperformed the “compareTo” ticker and a negative result would mean the “compareTo” did better. |
| output | no | Use either "csv" or "json" to get that type of output, otherwise leave blank. |
Not Yet Active Query Parameters
| Parameter | Required | Description |
|---|---|---|
| reinvestDividends | no | This will be used to change the calculations of the stock returns whether dividends are reinvested or not. |
Data Points
Get Data
This endpoint returns a specified data point for either an individual stock or group of stocks.
HTTP Request
https://api.customstockalerts.com/v1/getData?symbol=GOOG&field=creditrating&key=DEMO_KEY
Excel Request
=WEBSERVICE("https://api.customstockalerts.com/v1/getData?symbol=GOOG&field=creditrating&key=DEMO_KEY")
Google Sheets Request
=ImportData("https://api.customstockalerts.com/v1/getData?symbol=GOOG&field=creditrating&key=DEMO_KEY")
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| key | true | This is your API key from the My Account page. |
| symbol | true | This is the stock ticker to use, can either be a single ticker or comma separated list (e.g. AMZN,GOOG,MSFT) |
| field | true | The name of the field to select |
Text Fields
| Field | Description |
|---|---|
| companyname | The name of the company for the ticker |
| creditrating | The credit rating assigned by S&P |
| sector | The name of the GICS sector the company is in |
Numeric Fields
| Field | Description |
|---|---|
| chowderrule | The rule popularized by Seeking Alpha author Chowder; this is the sum of the current dividend yield and the 5-year dividend growth rate. |
| oneyeardividendgrowth | The one year dividend growth rate from the previous closed year. |
| threeyeardividendgrowth | The average three year dividend growth rate. |
| fiveyeardividendgrowth | The average five year dividend growth rate. |
| tenyeardividendgrowth | The average ten year dividend growth rate. |
| mostrecentincrease | The most recent increase percentage. |
| peratio | The P/E ratio for the company |
| dividendrate | The stated dividend rate. |
| safetyscore | The dividend safety score (percentile based; 100 highest, 0 is lowest). |
| growthscore | The dividend growth score (percentile based; 100 highest, 0 is lowest). |
| yieldscore | The dividend yield score (percentile based; 100 highest, 0 is lowest). |
| dividendyield | The forward looking dividend yield. |
Date Fields
| Field | Description |
|---|---|
| exdividend | The date of the next stated ex-dividend date (you must own prior to this day to get the dividend). |
Errors
The Custom Stock Alerts API uses the following error codes:
| Error Code | Meaning |
|---|---|
| Visit customstockalerts.com and subscribe for access | Replace the DEMO_KEY text in the key field with your key. |
| X parameter required | Make sure the value in single quotes is included in your request. |
| Unknown field | Check your 'field' request, it is not known. |
| Quota Exceeded Today | Make sure you aren't making too many daily requests, contact me for more information. |
| Invalid API Key | Check your API key or contact me for help. |
| X must be in MM/dd/yyyy format or days since 1900 (e.g. 43240 used in Excel) | Check that your date format. |
| Unknown X symbol | Check your ticker or compareTo field that is valid, data may not be available |