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.
Each API call starts with an endpoint of
https://whalewisdom.com/shell/command
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.
You must have an account in order to access the API. Access is further restricted into two types: subscribers and non-subscribers. Subscribers have full access to all quarterly 13F data. Non-subscribers have access to the last 8 quarters worth of data not including the current quarter.
An interactive testing shell is available to enter commands and test outputs: Interactive Testing Shell
The API limits usage to 20 requests per minute.
When you send a request to the WhaleWisdom API, you must have your credentials verified to authenticate yourself to the system. There are 3 separate ways to authenticate your API call. Which one you use really depends on how you are making the call and personal preference.
Every API user has the ability to create access keys for signing each request. Two access keys are used: a shared access key and a secret access key.
Each request you make must be digitally signed as follows:
https://whalewisdom.com/shell/command?args=[args]&api_shared_key=[api_shared_key]&api_sig=[api_sig]×tamp=[timestamp]
[args] is the JSON formatted object that contains the actual command and other par They are discussed in detail under "Making an API call".
[timestamp] a date-time value that marks the day and time the request was sent. Requests expire after a certain length of time to prevent malicious users from capturing requests and resubmitting them at a later time. This parameter is only used when authenticated via digital signatures.
For example: 2011-06-01T13:00:01Z
[api_shared_key] is the API Shared Access Key that has been assigned to your account. You can see your shared access key by going to your user profile.
[api_sig] is a signature of the args parameter created using your secret access key. The api_sig is constructed using the HMAC-SHA1 algorithm. You take the HMAC-SHA1 digest of the [args] parameter and then encode the results in base64. The process is similar to how OAuth signs requests except with our API we are using the args and timestamp query parameters (before they are URL encoded). When creating the signature, combine the args and timestamp with an ASCII newline ("\n") character. For Ruby the process would look like this:
require 'digest/sha1' t=Time.now digest = OpenSSL::Digest::Digest.new( 'sha1' ) hmac = OpenSSL::HMAC.digest( digest, secret_access_key, args+"\n"+t.utc.strftime('%Y-%m-%dT%H:%M:%SZ') ) sig=Base64.encode64( hmac ).chomp.gsub(/\n/, '')Click here for a complete sample using Python3
Each API call is an HTTP GET request. The GET request is constructed as follows:
https://whalewisdom.com/shell/command[.output_type]?args=[args]&api_shared_key=[api_shared_key]&api_sig=[api_sig]
Required parameters:
https://whalewisdom.com/shell/command.json?args=%7B%22command%22:%22stock_lookup%22,%20%22name%22:%22apple%20comp%22%7Dwould perform a stock lookup of "Apple" and return the results in JSON
There is an Online Interactive Shell that lets you execute API command and see what the correct API call format will be. Get more details here
{"command":"quarters"}
https://whalewisdom.com/shell/command.html?args=%7B%22command%22:%22quarters%22%7D
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 |
{"command":"stock_lookup", "name":"Apple Comp"}
{"command":"stock_lookup", "symbol":"aapl"}
https://whalewisdom.com/shell/command.html?args=%7B%22command%22:%22stock_lookup%22,%20%22name%22:%22apple%20comp%22%7D
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 |
{"command":"filer_lookup", "name":"berkshire"}
{"command":"filer_lookup", "cik":"0001067983"}
https://whalewisdom.com/shell/command.html?args=%7B%22command%22:%22filer_lookup%22,%20%22name%22:%22berkshire%22%7D
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 |
{"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)
https://whalewisdom.com/shell/command.html?args=%7B%22command%22:%22stock_comparison%22,%22stockid%22:3598,%22q1id%22:39,%22q2id%22:40%7D
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 |
{"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)
https://whalewisdom.com/shell/command.html?args=%7B%22command%22:%22holdings_comparison%22,%22filerid%22:163,%22q1id%22:39,%22q2id%22:40%7D
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 |
{"command":"export","quarters":[40,41,42],"columns":[1,2,3,4,5,6,7,8],"filer_id":349,"output":1,"email":"testemail@test.com"}
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
Download the latest list of filer_ids here. Download the latest list of stock_ids here.
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 |
{"command":"holdings","filer_ids":[349,2182],"include_13d":1}
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
Download the latest list of filer_ids here. Download the latest list of stock_ids here.
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 |
{"command":"holders","stock_ids":[195,411],"include_13d":1}
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