SG Markets Analytics API - Rates 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 one endpointa of the Rates V1 API is 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_rates

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_rates

# 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:

from sgmarkets_api_analytics_rates as rates.endpoint import endpoint as ep
# info about ROTB

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. At that time only v1_curves_price is available, but other are in the pipe.

from sgmarkets_api_analytics_rates.endpoint import endpoint as ep
# Examples
ep = ep.v1_curves_price

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.

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.

3.6 - 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='value')