API for Abnormal Return Calculator

by Anton Levchenko | 23 Nov 2014

The calculation engine of EventStudyTools' abnormal return calculators is also accessible through a JSON RPC application programming interface (API). Third parties can use our event study capabilities through this API to build own products and services or simply automate their analyses. This page serves as the technical documentation of the API and thus functions as a manual for third party integration. If you need help in implementing the API, please refer to the contact provided at the bottom of this page.

The triggering of an analysis in the standard format of aARC (referred to as 'API task' hereafter) implies five stages: 

  1. Authorization
  2. Task configuration
  3. Upload of user's data
  4. Data validation
  5. Launch of calculations
  6. Receival of results

Communication with the API occurs under the HTTP protocol using POST requests with a header in which the content-type field is set to application/json. The API's responses will show identical header fields. If your proxy server does not allow for custom headers, you will not be able to use our API (at this point). To check your proxy please send the following request to the API: HTTP GET /test


1. Authorization

Access to the API is restricted to authorized requests. Authorization takes place through an API key, which needs to be provided for every analysis.

HTTP request: POST /task/create

The API key needs to be transmitted to the API within the custom HTTP header's field X-Customer-Key.

After successful authorization, the API returns an authorization token which has to be used in all further requests to the API. The token needs to be used within the current API task's custom HTTP header's field X-Task-Token. Requests without valid authorization token will not be performed. The lifetime of each token elapses 15 minutes after the last valid request of the task.


2. Task configuration

HTTP Request: POST /task/conf

On this stage of the API task tune-ups are set and transmitted to the API as a JSON object with the following object structure:

{
     "task": {
          "email": string,
          "locale": string
     },

     "application": {
          "key": string,
          "data_sources": object[]
     },

     "parameters": {
     }
}

Within the object structure, the following parameter requirements apply:

  • email (optional): if an email address is provided, a notification about the successful calculation will be prompted to you
  • locale (optional): language of reports; at this point, the only language supported is English (en)
  • key (required): research app to be triggered; at this point, the only research app supported is the abnormal return calculator (b_arc)
  • data_sources (required): application's data sources as array of objects of the structure:

{
     "key": string,
     "type": string,
     "hash": string
}

  • key (required): identificator of data source
  • type (required): data source type
  • hash (optional): MD5 hash of data for validation purposes
  • parameters (optional): additional application specific parameters

2.1 bARC configuration

Specific for bARC JSON fields keys and values are placed here.

  • datasource/key values:

Value

Description

firm_data

Firm data source

market_data

Market data source

request_file

Request file

  • datasource/type values

Value

Description

csv

user-uploaded CSV files

yahoo

Yahoo!Finance

  • parameters:
    • return_type (optional): string - default value is log, available values are: {simple, log}
    • non_trading_days (optional): string - default value is keep, available values are: {earlier, later, keep}
    • benchmark_model (optional): string – default value is mm, available values are {mm, mm-sw}
    • test_statistics (optional): hashed array ('test statistics abbreviation' => (boolean)enabled/disabled)
       
Example of bARC request

{
     "task": {

          "email": "email@example.com",
          "locale": "en"
     },

     "application": {
          "key": "b_arc",
          "data_sources": [
                {
                     "key": "request_file",
                     "type": "csv",
                     "hash": "e82b691e212d7d55425ab318b25ce11b"
                },
                {
                     "key": "firm_data",
                     "type": "csv",
                     "hash": "29ec0695c3fa929921f69e0cf05aedfb"
                },
                {
                     "key": "market_data",
                     "type": "csv",
                     "hash": ""
                }
          ],
          "parameters": {
                "return_type": "simple",
                "non_trading_days": "keep",
                "benchmark_model": "mm"
                "test_statistics": [
                ]
          }
     }
}


3. User data upload

HTTP request: POST /task/content/{key}/{part_number}

In this stage user data is uploaded to the API server (if it is semantically needed). Upload happens by POST request with the HTTP header's Content-Type field being set to application/octet-stream. Partial upload is supported. Available keys are:

  • key: datasource/key
  • part_number: file's part number
     
Example of request sample (by single part):

POST /task/content/request_file/0 HTTP/1.1
X-Task-Key: 01fbb0f5ca717e7754352ff8e8bc1abb
Content-Type: application/octet-stream
Host: api.eventstudytool.com
Connection: close
User-Agent: Paw 2.0.9 (Macintosh; Mac OS X 10.9.4; en_US_POSIX@currency=UAH)
Content-Length: 699

75510;Adobe Systems;SP500;30.04.1997;120;-11
64390;Progressive ;SP500;25.07.1997;120;-11
23473;Cincinnati;SP500;16.12.1997;120;-11
70500;Coca-Cola Enterprises;SP500;01.10.1998;120;-11
70519;Travelers Group;SP500;01.10.1998;120;-11
76149;Safeway;SP500;05.11.1998;120;-11
49680;Danaher;SP500;11.11.1998;120;-11
75154;Carnival;SP500;10.12.1998;120;-11
57904;AFLAC;SP500;26.04.1999;120;-11
75573;Office Depot;SP500;02.06.1999;120;-11
85914;Best Buy;SP500;22.06.1999;120;-11
77178;Qualcomm;SP500;08.07.1999;120;-11

Error is indicated by API HTTP response 500, which means re-upload of file.


4. Data check

HTTP Request: POST task/commit

Before calculations are started, a data check is performed. In case of an error, the API server delivers an HTTP response 500 and provides a respective error message.


5. Lauch of calculations

HTTP Request: POST task/process

If the calculations were performed successful, the API will prompt a JSON object with links to the execution log and results files. Otherwise, the server returns an HTTP 500.

References and further studies

S. Benninga 2008. Financial modeling (3 ed.).
Anton Levchenko

Anton is a lead programmer of the EST analytical core. If you want to use our APIs in one of your applications, please get in contact with Anton.