SG Markets Analytics API - ROTB - Rates Options Trade Builder v1

1- Introduction

This repo is meant to make it easy for clients (and employees) to tap SG Research APIs.

This is a work in progress and subject to change.
In particular only a few endpoints of the Rates Option Trade Builder V1 API are covered.

The usual way to expose an API is to make a swagger available and also a GUI, typically a web page.
These have the following drawbacks:

• A swagger is as precise as it is dull. Unless clients are (working with) IT savvy people they will have a hard time taking advantage of it. In short it is not enough.
• A GUI is easy to use but often as much a help as a hindrance: They are very slow/costly to build/adapt, are seldom as flexible as the underlying API, and are no help for industrial use of the API.

To fill the gap, we introduce the Jupyter notebook as an API consumption tool (It as many other uses).
The associated Python package used here has a very simple interface, but can be arbitrarily modified for (and by) an advanced user. It has the same display capabilities as a web page (being one itself). Most importantly is is written in Python so can be evolved by a business user (as opposed to web front end which is invariably delegated to specialist developpers).

This repo contains:

• a ready-to-use demo notebook
• the underlying library in folder sgmarkets_api_analytics_rotb

Here, the notebook is a convenient and versatile interface to

• hide the plumbing
  • going through the corporate proxy
  • getting the SG API access token (Auth v1.0)
• make API calls explicit and readable
• analyse the API response
• slice and display the results as tables and graphs - and save them

2 - Install

From terminal:

# download and install package from pypi.org
pip install sgmarkets_api_analytics_rotb

# launch notebook
jupyter notebook

Create a notebook or run the demo notebook and modify it to your own use case.

3 - User guide

Read the demo notebook.

The key steps are the following.

3.1 - Read the info

The package contains the corresponding API swagger url and contact info:

import sgmarkets_api_analytics_rotb as ROTB
# info about ROTB
ROTB.info()

3.2 - Define you credentials

See the user guide in the sgmarkets-api-auth repo

3.3 - Pick an endpoint

Select it from the list of those available in the package.

import sgmarkets_api_analytics_rotb as ROTB
# Examples
ep = ROTB.endpoint..v1_curves
ep = ROTB.endpoint.v1_compute_strategy_components

3.4 - Create the associated request

Each end point comes with a Request object.

# For all endpoints
rq = ep.request()

And fill the object with the necessary data.
This part is specific to the endpoint selected.
See the demo notebook for examples.

Then explore your Request object to make sure it is properly set.

# For all endpoints
# display the structure of the object
rq.info()

IMPORTANT:
You should make sure the request will not overload the server. If not the API call may time out.
To this effect the Request object will display information, warnings and recommendations.

3.5 - Call the API

You can call the API directly from the Request object.

# For all endpoints
# a is an Api object (see 3.2)
res = rq.call_api(a)

The returned object is a Response object associated to this endpoint.
You can explore it starting with

# For all endpoints
# display the structure of the object
res.info()

3.6 - Save and show the results

As .csv and .xlsx files.

# For all endpoints
# save to disk
res.save_result(excel=True)

The Response objects are different for each endpoint.
See the demo notebook for examples.

3.7 - Slice the results

For those endpoints which return a large amount of data, slicing the result is usually the best/only way to exploit the results.
Then use the associated Slice results down to a 1-D or 2-D or 3-D dataframe.

# example - see demo notebook for the context
dic_req_fix = {'date': pd.Timestamp('2016-11-11')}
s1 = ep.slice(res, x='expiry', y='tenor', dic_req_fix=dic_req_fix, value='volNormal')

# display the structure of the object
s1.info()

# save to disk
s1.save()

3.8 - Plot a slice

See the user guide in the sgmarkets-api-plot repo