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:

Authorization
Task configuration
Upload of user's data
Data validation
Launch of calculations
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.