API for Abnormal Return Calculator

The calculation engine behind the Abnormal Return Calculator (ARC) and the other research apps of EventStudyTools is accessible through a JSON-based HTTP application programming interface (API). Researchers and third parties can use it to automate their analyses or to integrate the research apps into their own products and workflows. This page is the technical reference for the API protocol.

Access requires an API key. Academic researchers can request a free API key with their university email address; keys are valid for one month and can be renewed. General (non-academic) key access is currently paused.

Client libraries

For most users, the recommended way to use the API is one of our open-source client libraries at github.com/EventStudyTools. They implement the full protocol described below, so you only supply your data files, your parameters, and your API key:

  • R: EventStudy (repository api-wrapper.r), the classic full-featured R package with parameter objects, result parsers, and an RStudio addin. The package is archived on CRAN, so install it via remotes::install_github("EventStudyTools/api-wrapper.r"). Alternatively, r-wrapper is a new lightweight R client whose only dependencies are curl and jsonlite.
  • Python: python-wrapper, standard library only, no third-party dependencies
  • Stata: stata-wrapper, the est_arc command
  • MATLAB: matlab-wrapper, the EventStudyAPI class
  • SAS: sas-wrapper, the %est_arc macro
  • PHP: php-wrapper, the client that also powers this website

Each repository contains installation instructions, a quickstart example, and sample data. If you build your own integration, the protocol reference below is the authoritative documentation.

Protocol overview

The API server is reached at http://api.eventstudytools.com. All endpoints below are relative to this base URL. Communication uses HTTP POST requests with the Content-Type header field set to application/json; file uploads use application/octet-stream. The API responds with JSON and identical header fields. Errors are indicated by an HTTP 500 status and a JSON object with an error field. If your proxy server does not allow custom headers, you will not be able to use the API; to check your setup, send GET /test to the API. GET /version returns the API server version.

Running an analysis (referred to as an 'API task' hereafter) involves six steps:

  1. Authorization
  2. Task configuration
  3. Upload of the input data
  4. Data validation
  5. Launch of the calculation
  6. Retrieval of results

1. Authorization

HTTP request: POST /task/create

Access to the API is restricted to authorized requests. Authorization takes place through an API key, which needs to be provided for every analysis. Transmit the API key in the custom HTTP header field X-Customer-Key.

After successful authorization, the API returns an authorization token as a JSON object:

{ "token": "01fbb0f5ca717e7754352ff8e8bc1abb" }

This task token has to be sent with all further requests of the current API task in the custom HTTP header field X-Task-Key. Requests without a 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

In this step, the task settings are transmitted to the API as a JSON object with the following 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 is sent to it
  • locale (optional): language of the reports; at this point, the only supported language is English (en)
  • key (required): the research app to be triggered. This page documents the Abnormal Return Calculator (arc); the other research apps (avc, avyc, cata, edi) follow the same protocol with their own data sources and parameters, as implemented in the client libraries
  • data_sources (required): the app's data sources as an array of objects with the following structure:
{
    "key": string,
    "type": string,
    "hash": string
}
  • key (required): identifier of the data source
  • type (required): data source type
  • hash (optional): MD5 hash of the data for validation purposes
  • parameters (optional): additional app-specific parameters

2.1 ARC configuration

The ARC-specific JSON keys and values are listed here.

data_sources/key values:

Value Description
request_file Request file (one line per event)
firm_data Firm data source
market_data Market data source

data_sources/type values:

Value Description
csv user-uploaded CSV file
csv_zip user-uploaded zipped CSV file
xls, xls_zip user-uploaded Excel file (plain or zipped)
xlsx, xlsx_zip user-uploaded Excel file, XLSX format (plain or zipped)

Note: the former yahoo data source type (automatic download from Yahoo!Finance) is no longer available, as Yahoo discontinued this data service. Please upload your data as files.

parameters values:

  • 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, skip}
  • benchmark_model (optional): string, default value is mm; available values are listed below, the models are described on Expected Return Models
  • regression_method (optional): string, default value is ols
  • result_file_type (optional): string, default value is csv; available values are {csv, xls, xlsx, ods}
  • test_statistics (optional): array of test statistic abbreviations to be computed; available values are listed below, the statistics are described on Significance Tests. If omitted, a default selection is applied (aart, caart, aarptlz, caarptlz, aarbmpz, caarbmpz)

benchmark_model values:

Value Model
mm Market Model
mm-sw Scholes/Williams Model
mam Market Adjusted Model
cpmam Comparison Period Mean Adjusted Model
capm CAPM
ff3fm Fama-French 3-Factor Model
ffm4fm Fama-French-Momentum 4-Factor Model
ff5fm Fama-French 5-Factor Model
garch GARCH(1,1) Model
egarch EGARCH(1,1) Model

test_statistics values:

Value Test statistic
art AR t-test
cart CAR t-test
aart AAR cross-sectional t-test (Csect T)
caart CAAR cross-sectional t-test (Csect T)
abhart ABHAR t-test
aarptlz AAR Patell Z
caarptlz CAAR Patell Z
aaraptlz AAR Adjusted Patell Z (Kolari/Pynnönen)
caaraptlz CAAR Adjusted Patell Z (Kolari/Pynnönen)
aarbmpz AAR BMP Z (StdCSect Z)
caarbmpz CAAR BMP Z (StdCSect Z)
aarabmpz AAR Adjusted BMP Z (Kolari/Pynnönen)
caarabmpz CAAR Adjusted BMP Z (Kolari/Pynnönen)
aarskewadjt AAR skewness-corrected t-test
caarskewadjt CAAR skewness-corrected t-test
abharskewadjt ABHAR skewness-corrected t-test
aarrankz AAR Rank Z (Corrado)
caarrankz CAAR Rank Z (Corrado)
aargrankt AAR Generalized Rank T
caargrankt CAAR Generalized Rank T
aargrankz AAR Generalized Rank Z
caargrankz CAAR Generalized Rank Z
aargsignz AAR Generalized Sign Z
caargsignz CAAR Generalized Sign Z

Example of an ARC configuration request:

{
    "task": {
        "email": "[email protected]",
        "locale": "en"
    },
    "application": {
        "key": "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": ["aart", "caart", "aarptlz", "caarptlz", "aarbmpz", "caarbmpz"]
    }
}

3. User data upload

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

In this step, the user data is uploaded to the API server (where semantically needed). The upload happens via POST request with the HTTP header field Content-Type set to application/octet-stream. Partial upload is supported. The URL parameters are:

  • key: the data_sources/key of the file being uploaded
  • part_number: the file's part number; use 0 when uploading a file in a single part

Example of an upload request (single part):

POST /task/content/request_file/0 HTTP/1.1
X-Task-Key: 01fbb0f5ca717e7754352ff8e8bc1abb
Content-Type: application/octet-stream
Host: api.eventstudytools.com
Connection: close
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

An upload error is indicated by an HTTP 500 response, in which case the file should be re-uploaded.

4. Data validation

HTTP request: POST /task/commit

Before the calculation is started, the server validates the configuration and the uploaded data. In case of an error, the API delivers an HTTP 500 response and provides a respective error message.

5. Launch of the calculation

HTTP request: POST /task/process

This request launches the calculation. On success, the API returns a JSON object announcing the result files, including the analysis results and the execution log:

{
    "results": [
        {
            "url": string,
            "name": string,
            "basename": string,
            "ext": string,
            "contentType": string
        }
    ]
}

Otherwise, the server returns an HTTP 500 response.

6. Retrieval of results

The calculation runs asynchronously. Poll the announced result file URLs with GET requests: while the calculation is still running, the server returns a non-200 status. Once a file is ready, the server responds with HTTP 200 and the file contents. Download each file listed in the results array; the execution log is useful for diagnosing data or parameter issues.

Questions and support

Current service availability of the research apps and the API is shown on the status page. If you run into problems with one of the client libraries, please open an issue in the respective repository at github.com/EventStudyTools. For questions about API keys, see the API access page.