Pricing

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"....}

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 -
  • 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" 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:
optional
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 ID to sort by -
dir "DIRECTION" string optional ASC or DESC
limit string numberlimit number of results returned
columns [COLUMN ID's] array of numbers optional - 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_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&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 {"command":"holders","stock_ids":[195],"include_13d":1,"sort":"percent_ownership","dir":"DESC","limit":"25","columns":[1,14,16,17,20]}'
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 ID to sort by -
dir "DIRECTION" string optional ASC or DESC
limit string numberlimit number of results returned
columns [COLUMN ID's] array of numbers optional - 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_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
(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