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:

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