The WhaleWisdom API lets you interact with our 13F database in a variety of ways. Although most of the functionality provided through the API is already available by utilizing the website, the API is provided to help streamline and automate data retrieval.
In order to use the API you must have an account registered with WhaleWisdom.com. Once registered you will need to login and go to your user profile to create new API access keys. These will be used to authenticate your API calls.
What follows the endpoint depends on a number of factors including how you are to be authenticated, what command you want to execute and how you want the results formatted. The following documentation provides details into using the API.
The API limits usage to 20 requests per minute.
quarters
The quarters command lists all 13F filing dates currently in the database and their availability for use by your account.
JSON object/value pairs:
None
Available Outputs: html, json, csv
Example:
{"command":"quarters"} Sample format for a GET request API call:
https://whalewisdom.com/shell/command.html?args=%7B%22command%22:%22quarters%22%7D
stock_lookup
stock_lookup returns a list of stocks that match either the ticker symbol or name provided. The stock identifier, name, symbol, and status (active or delisted) will be returned.
JSON object/value pairs:
| key | value | type | required | |
|---|---|---|---|---|
| name | NAME | string | either name or symbol is required | a partial or complete name to search for |
| symbol | SYMBOL | string | either name or symbol is required | the stock ticker symbol to search for |
Available Outputs: html, json, csv
examples:
{"command":"stock_lookup", "name":"Apple Comp"} {"command":"stock_lookup", "symbol":"aapl"}A complete GET API call would look similarly to:
https://whalewisdom.com/shell/command.html?args=%7B%22command%22:%22stock_lookup%22,%20%22name%22:%22apple%20comp%22%7D
filer_lookup
The filer_lookup command returns a list of 13F filers including the filer identifier, name and CIK. The maximum number of records returned is 1,000.
JSON object/value pairs:
| key | value | type | required | |
|---|---|---|---|---|
| name | NAME | string | at least one param is required | a partial or complete name to search for |
| cik | CIK | string | at least one param is required | the filer Central Index Key(CIK) to search for |
| id | ID | number | at least one param is required | the database ID of the filer |
| city | ID | string | at least one param is required | the city provided by the filer |
| state | ID | string | at least one param is required | the state the filer resides in |
| state_incorporation | ID | string | at least one param is required | the state the filer is incorporated in |
| business_phone | ID | string | at least one param is required | business phone provided by filer |
| irs_number | ID | string | at least one param is required | IRS number provided by filer |
| offset | ID | string | offset to return if bringing back over 1,000 records |
Available Outputs: html, json, csv
examples:
{"command":"filer_lookup", "name":"berkshire"} {"command":"filer_lookup", "cik":"0001067983"}A complete GET request API call would look similarly to:
https://whalewisdom.com/shell/command.html?args=%7B%22command%22:%22filer_lookup%22,%20%22name%22:%22berkshire%22%7D
stock_comparison
The stock_comparison allows for Quarterly comparison of 13F holders of a specific stock
JSON object/value pairs:
| key | value | type | required | |
|---|---|---|---|---|
| stockid | STOCK ID - the id of the stock | numeric | required | |
| q1id | QUARTER 1 ID - the id of one of the 13F filing quarters to compare | numeric | required | |
| q2id | QUARTER 2 ID - the id of the other 13F filing quarter to compare | numeric | required | |
| order | ORDER BY | string | optional | filer_name, q1_shares, q2_shares, or percent_change |
| dir | DIRECTION | string | optional | ASC or DESC |
Available Outputs: html, json, csv
examples:
{"command":"stock_comparison","stockid":3598,"q1id":39,"q2id":40} (This will do a stock comparison of E*Trade for the 9/30/2010 and 12/31/2010 quarters)
{"command":"stock_comparison","stockid":3598,"q1id":39,"q2id":40,"order":"q2_shares","dir":"DESC"} (This will do a stock comparison of E*Trade for the 9/30/2010 and 12/31/2010 quarters ordering by q2 shares in descending order)
A complete API call would look similarly to:
https://whalewisdom.com/shell/command.html?args=%7B%22command%22:%22stock_comparison%22,%22stockid%22:3598,%22q1id%22:39,%22q2id%22:40%7D
holdings_comparison
The holdings_comparison lets you compare a filer's 13F holdings between two quarters
JSON object/value pairs:
| key | value | type | required | |
|---|---|---|---|---|
| filerid | FILER ID | numeric | required | the id of the filer |
| q1id | QUARTER 1 ID | numeric | required | the id of one of the 13F filing quarters to compare |
| q2id | QUARTER 2 ID | numeric | required | the id of the other 13F filing quarter to compare |
| order | ORDER BY | string | optional | column to sort by - stock, q2_market_value, q1_percent_of_portfolio, q2_percent_of_portfolio, q2_shares, q1_shares, q1_market_value, percent_change, or absolute_change |
| dir | DIRECTION | string | optional | ASC or DESC |
| filter | FILTER | array of strings | optional | An array with possible values of SHARES, CALL, PUT, or PRN. if set to one or more of these values then the results will be restricted to those types of assets |
| stockid | DIRECTION | numeric | optional | this will restrict results to the stock id you provide |
Available Outputs: html, json, csv
examples:
{"command":"holdings_comparison","filerid":163,"q1id":39,"q2id":40} (This will do a 13F holdings comparison of Appaloosa for the 9/30/2010 and 12/31/2010 quarters and display the results on screen)
{"command":"holdings_comparison","filerid":163,"q1id":39,"q2id":40,"order":"q2_shares","dir":"DESC"} (This will do a holdings comparison of Appaloosa for the 9/30/2010 and 12/31/2010 quarters ordering by q2 shares in descending order)
{"command":"holdings_comparison","filerid":163,"q1id":39,"q2id":40,"order":"q2_shares","filter":["CALL","PUT"]} (This will do a holdings comparison of Appaloosa for the 9/30/2010 and 12/31/2010 quarters and only return any CALL or PUT holdings)
A complete API call would look similarly to:
https://whalewisdom.com/shell/command.html?args=%7B%22command%22:%22holdings_comparison%22,%22filerid%22:163,%22q1id%22:39,%22q2id%22:40%7D
export
The export lets you export the entire 13f holdings history for a single filer. Standard subscription users are limited to exporting 50 filers per quarter.
JSON object/value pairs:
| key | value | type | required | |
|---|---|---|---|---|
| filer_id | FILER ID | numeric | required | id of filer to export |
| quarters | [QUARTER_ID's] | array of numbers | required | array of quarter ids to export |
| output | OUTPUT ID | numeric | required | either 1 or 2. 1 to output all 13f holdings into a single CSV file. 2 to output all 13f holdings into separate CSV files per quarter |
| columns | [COLUMN ID's] | array of numbers | required | Columns to include in export -
|
| "EMAIL" | string | required | email address to send export to |
Available Outputs: html, json, csv
examples:
(This will export the 13f holdings of Berkshire Hathaway for the 12/31/2010, 3/31/2011 and 6/30/2011 quarters to a single CSV file and email it to testemail@test.com)
{"command":"export","quarters":[40,41,42],"columns":[1,2,3,4,5,6,7,8],"filer_id":349,"output":1,"email":"testemail@test.com"}A complete API call would look similarly to:
https://whalewisdom.com/shell/command.html?args=%7B%22command%22%3A%22export%22%2C%22quarters%22%3A%5B40%2C41%2C42%5D%2C%22columns%22%3A%5B16%2C17%2C18%5D%2C%22filer_id%22%3A349%2C%22output%22%3A1%2C%22email%22%3A%22testemail%40test.com%22%7D
holdings
The holdings lets you output all holdings for a filer or list of filers. Holdings data is taken from 13F filings and you can optionally incorporate Schedule 13D/G information as well. This command is limited to your subscription level.
Download the latest list of filer_ids here. Download the latest list of stock_ids here.
JSON object/value pairs:
| key | value | type | required | |
|---|---|---|---|---|
| filer_ids | [FILER ID] | numeric array | required | ids of filers to include |
| quarter_ids | [QUARTER_ID] | numeric array | optional. leave blank to get most recent data | ids of quarters to retrieve |
| stock_ids | [STOCK ID] | numeric array | optional | ids of stocks to restrict output to |
| all_quarters | 1 or 0 | number | optional. | If set to 1 then all available quarters are retrieved |
| sort | "ORDER BY" | string | optional | column to sort by - |
| dir | "DIRECTION" | string | optional | ASC or DESC |
| limit | string | number | optionallimit number of results returned | |
| columns | [COLUMN ID's] | array of numbers | optional - leave blank for all | Columns to include -
|
| include_13d | 1 or 0 | number | optional. | If set to 1 and pulling latest quarterly data then any 13D/G filing after the 13F filing data will replace the 13F holdings information |
Available Outputs: json, csv
examples:
(This will retrieve all current holdings of Berkshire Hathaway and Paulson & Co augmented with any available 13D/G filings
{"command":"holdings","filer_ids":[349,2182],"include_13d":1} A complete API call would look similarly to: https://whalewisdom.com/shell/command.json?args=%7B%22command%22%3A%22holdings%22%2C%22filer_ids%22%3A%5B349%2C2182%5D%2C%22include_13d%22%3A1%7D%20×tamp=2014-2-7T15%3A33%3A43Z
holders
The holders lets you output all holders for a stock or group of stocks. Holders data is taken from 13F filings and you can optionally incorporate Schedule 13D/G information as well. This command is limited to your subscription level.
Download the latest list of filer_ids here. Download the latest list of stock_ids here.
JSON object/value pairs:
| key | value | type | required | |
|---|---|---|---|---|
| filer_ids | [FILER ID] | numeric array | optional | ids of filers to restrict output to |
| quarter_ids | [QUARTER_ID] | numeric array | optional. leave blank to get most recent data | ids of quarters to retrieve |
| stock_ids | [STOCK ID] | numeric array | required | ids of stocks to restrict output to |
| all_quarters | 1 or 0 | number | optional. | If set to 1 then all available quarters are retrieved |
| sort | "ORDER BY" | string | optional | column to sort by - |
| dir | "DIRECTION" | string | optional | ASC or DESC |
| limit | string | number | optionallimit number of results returned | |
| columns | [COLUMN ID's] | array of numbers | optional - leave blank for all | Columns to include -
|
| include_13d | 1 or 0 | number | optional. | If set to 1 and pulling latest quarterly data then any 13D/G filing after the 13F filing data will replace the 13F holdings information |
| hedge_funds_only | 1 or 0 | number | optional. | If set to 1 then only funds that have been classified as hedge funds will be included in results |
Available Outputs: json, csv
examples:
(This will retrieve all current holdings of Apple and Halliburton augmented with any available 13D/G filings
{"command":"holders","stock_ids":[195,411],"include_13d":1} A complete API call would look similarly to: https://whalewisdom.com/shell/command.json?args=%7B%22command%22%3A%22holdings%22%2C%22filer_ids%22%3A%5B349%2C2182%5D%2C%22include_13d%22%3A1%7D%20×tamp=2014-2-7T15%3A33%3A43Z
