The Whalewisdom 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.

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/, '')
         

3. A third option is to use basic HTTP authentication. Your login/password are sent in the header of each HTTP request. This is simple to use and widely supported, but considered insecure.

Each API call is an HTTP GET or POST 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.

• [.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.