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 key 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

Note: You must replace YOUR_KEY with your personal API key.

Stock Returns

Get Stock Returns

This endpoint runs stock return calculations for the provided parameters. This endpoint requires API key authentication.

HTTP Request

GET https://api.customstockalerts.com/v1/getStockReturn?symbol=GOOG&startDate=1/1/2018&endDate=1/1/2019&key=DEMO_KEY

Example with Comparison

GET https://api.customstockalerts.com/v1/getStockReturn?symbol=AAPL&startDate=1/1/2018&endDate=1/1/2019&compareTo=SPY&key=DEMO_KEY

This will return the difference between AAPL's return and SPY's return. A positive number means the symbol outperformed the compareTo ticker.

Example with Multiple Symbols

GET https://api.customstockalerts.com/v1/getStockReturn?symbol=AAPL,MSFT,GOOGL&startDate=1/1/2018&endDate=1/1/2019&key=DEMO_KEY

Example with Output Format

GET https://api.customstockalerts.com/v1/getStockReturn?symbol=AAPL&startDate=1/1/2018&endDate=1/1/2019&output=json&key=DEMO_KEY

Excel Request

=WEBSERVICE("https://api.customstockalerts.com/v1/getStockReturn?symbol=GOOG&startDate=1/1/2018&endDate=1/1/2019&key=DEMO_KEY")

Google Sheets Request

=ImportData("https://api.customstockalerts.com/v1/getStockReturn?symbol=GOOG&startDate=1/1/2018&endDate=1/1/2019&key=DEMO_KEY")

Query Parameters

Parameter	Required	Description
`key`	true	This is your API key from the My Account page.
`symbol`	true	Stock ticker symbol. Can be a single ticker (e.g., `GOOG`) or comma-separated list (e.g., `AAPL,MSFT,GOOGL`).
`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). If not provided, defaults to a far future date.
`compareTo`	false	Enter another ticker symbol (or comma-separated list) to compare results against. The returned value will be the delta between the two investments. For example, a positive number means the "symbol" ticker outperformed the "compareTo" ticker, and a negative result means the "compareTo" did better.
`output`	false	Use `json` to get JSON output, `csv` to get CSV output, or leave blank for plain text (default). Plain text returns one return value per line (or delta if compareTo is used).

Response Formats

The response format depends on the output parameter:

Default (no output parameter): Plain text with one return value per line. If compareTo is used, returns the delta (difference) between symbol and compareTo returns.
output=json: Returns a JSON array of arrays containing the stock return data table.
output=csv: Returns CSV format with headers and data rows.

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

Note: Case is not important for the symbol or field.

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:

If you need additional help, please contact support regarding your error.

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 support for more information.
Invalid API Key	Check your API key or contact support 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 is correct.
Unknown X symbol	Check your ticker or compareTo field that is valid, data may not be available