The WhaleWisdom API

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.

Access to resources

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

Per-Minute Request Limits

The API limits usage to 20 requests per minute.

Authenticating your API Call

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.

  1. If you are doing the API calls through a browser then the easiest way is by simply logging into the site with your account login/password and letting the browser maintain your session using a session cookie.
  2. The preferred option for desktop and other non-browser applications is to include a digital signature with each request.

    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.

    shared access key -
    identifies you as the party responsible for service requests. You include it in each API request so it is not a secret.
    Secret Access Key -
    used to create a digital signature with each request. Your secret access key is secret and is not actually included in any request. You should not share it with anyone.

    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]&timestamp=[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

Making an API call

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:

  • [args] - The args parameter contains the actual command to execute. It is a JSON object with the command to run and any additional parameters. View the detailed instructions for each available command and to see how the args parameter is constructed. If using a GET Request, be sure to properly URL encode the args parameter as it will likely contain spaces, quotes, and other disallowed URL characters. Use the Online Interactive Shell to experiment with the available commands and see how the args parameter is constructed.
Optional Parameters:
  • [.output_type] - By default command results are output in HTML format. If the command you are running supports outputting results in another format such as JSON or CSV then you would specify that here by adding a .json or .csv to the URL. For example:
     https://whalewisdom.com/shell/command.json?args=%7B%22command%22:%22stock_lookup%22,%20%22name%22:%22apple%20comp%22%7D
        
    would perform a stock lookup of "Apple" and return the results in JSON
  • [api_shared_key] - Used when authenticating via digital signatures. See details under the "authenticating your API call" section above
  • [api_sig] - Used when authenticating via digital signatures. See details under the "authenticating your API call" section above

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

some important concepts

  • Many commands will require you to enter the id for the quarter (time period) you wish to query against. The quarter id can be found by running the "quarters" command. Type "quarters" in the Shell and you will get a list of all quarters in the system as well as which ones you have access to. For example quarter id 1 is for 3/31/2001 while quarter id 40 is for 12/31/2010.
  • Use the "filer_lookup" command to find a 13F filer's id in the system. Provide a partial name or CIK of the filer you want to find and if the filer is in our system it will return the id to you.
  • Use the "stock_lookup" command to find a stock's id in our system. Provide a ticker symbol or partial name and the stock_lookup command will return a list of matching stocks along with their ids.
Every JSON object you build for a request will have a "command" key with the command to run as the value. For example {"command":"stock_lookup"....}

Available API Calls

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:
keyvaluetyperequired
nameNAMEstringeither name or symbol is requireda partial or complete name to search for
symbolSYMBOLstringeither name or symbol is requiredthe 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:
keyvaluetyperequired
nameNAMEstringat least one param is requireda partial or complete name to search for
cikCIKstringat least one param is requiredthe filer Central Index Key(CIK) to search for
idIDnumberat least one param is requiredthe database ID of the filer
cityIDstringat least one param is requiredthe city provided by the filer
stateIDstringat least one param is requiredthe state the filer resides in
state_incorporationIDstringat least one param is requiredthe state the filer is incorporated in
business_phoneIDstringat least one param is requiredbusiness phone provided by filer
irs_numberIDstringat least one param is requiredIRS number provided by filer
offsetIDstringoffset 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:
keyvaluetyperequired
stockidSTOCK ID - the id of the stocknumericrequired
q1idQUARTER 1 ID - the id of one of the 13F filing quarters to comparenumericrequired
q2idQUARTER 2 ID - the id of the other 13F filing quarter to comparenumericrequired
orderORDER BYstringoptionalfiler_name, q1_shares, q2_shares, or percent_change
dirDIRECTIONstringoptionalASC 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:
keyvaluetyperequired
fileridFILER IDnumericrequiredthe id of the filer
q1idQUARTER 1 IDnumericrequiredthe id of one of the 13F filing quarters to compare
q2idQUARTER 2 IDnumericrequiredthe id of the other 13F filing quarter to compare
orderORDER BYstringoptionalcolumn 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
dirDIRECTIONstringoptionalASC or DESC
filterFILTERarray of stringsoptionalAn 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
stockidDIRECTIONnumericoptionalthis 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:
keyvaluetyperequired
filer_idFILER IDnumericrequiredid of filer to export
quarters[QUARTER_ID's]array of numbersrequired array of quarter ids to export
outputOUTPUT IDnumericrequired 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 numbersrequired Columns to include in export -
  • 1 - Filer Name
  • 2 - Stock Name
  • 3 - Stock Ticker
  • 4 - Quarter Date
  • 5 - Type of Security
  • 6 - Current Shares Held
  • 7 - Current Market Value
  • 8 - Previous Shares Held
  • 9 - Previous Market Value
  • 10 - Current % of Portfolio
  • 11 - Previous % of Portfolio
  • 12 - Current Rank
  • 13 - Previous Rank
  • 14 - Change in Shares
  • 15 - Type of Change
  • 16 - Sector
  • 17 - stock_id
email"EMAIL"stringrequiredemail 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:
optional
keyvaluetyperequired
filer_ids[FILER ID]numeric arrayrequiredids of filers to include
quarter_ids[QUARTER_ID]numeric arrayoptional. leave blank to get most recent data ids of quarters to retrieve
stock_ids[STOCK ID]numeric arrayoptionalids of stocks to restrict output to
all_quarters1 or 0numberoptional. If set to 1 then all available quarters are retrieved
sort"ORDER BY"stringoptionalcolumn to sort by -
dir"DIRECTION"stringoptionalASC or DESC
limitstringnumberlimit number of results returned
columns[COLUMN ID's]array of numbersoptional - leave blank for all Columns to include -
  • 0. filer_id
  • 1. filer_name
  • 2. stock_id
  • 3. stock_name
  • 4. stock_ticker
  • 5. security_type
  • 6. shares_change
  • 7. position_change_type
  • 8. current_ranking
  • 9. previous_ranking
  • 10. current_percent_of_portfolio
  • 11. previous_percent_of_portfolio
  • 12. current_mv
  • 13. previous_mv
  • 14. current_shares
  • 15. previous_shares
  • 16. source_date
  • 17. source
  • 18. sector
  • 19. industry
  • 20. % Ownership
  • 21. filer_street_address
  • 22. filer_city
  • 23. filer_state
  • 24. filer_zip_code
  • 25. avg_price
  • 26. percent_change
  • 27. quarter_id_owned (quarter id first owned by filer)
include_13d1 or 0numberoptional. 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&timestamp=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:
optional
keyvaluetyperequired
filer_ids[FILER ID]numeric arrayoptionalids of filers to restrict output to
quarter_ids[QUARTER_ID]numeric arrayoptional. leave blank to get most recent data ids of quarters to retrieve
stock_ids[STOCK ID]numeric arrayrequiredids of stocks to restrict output to
all_quarters1 or 0numberoptional. If set to 1 then all available quarters are retrieved
sort"ORDER BY"stringoptionalcolumn to sort by -
dir"DIRECTION"stringoptionalASC or DESC
limitstringnumberlimit number of results returned
columns[COLUMN ID's]array of numbersoptional - leave blank for all Columns to include -
  • 0. filer_id
  • 1. filer_name
  • 2. stock_id
  • 3. stock_name
  • 4. stock_ticker
  • 5. security_type
  • 6. shares_change
  • 7. position_change_type
  • 8. current_ranking
  • 9. previous_ranking
  • 10. current_percent_of_portfolio
  • 11. previous_percent_of_portfolio
  • 12. current_mv
  • 13. previous_mv
  • 14. current_shares
  • 15. previous_shares
  • 16. source_date
  • 17. source
  • 18. sector
  • 19. industry
  • 20. % Ownership
  • 21. filer_street_address
  • 22. filer_city
  • 23. filer_state
  • 24. filer_zip_code
  • 25. avg_price
  • 26. percent_change
  • 27. quarter_id_owned (quarter id first owned by filer)
include_13d1 or 0numberoptional. 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_only1 or 0numberoptional. 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&timestamp=2014-2-7T15%3A33%3A43Z

WhaleWisdom Logo

Elevate your investments