openapi: 3.0.0
info:
  title: A7 Analytics Platform - Algo management Algo management API Pace of the Roll API
  description: 'A7 Analytics Platform for the main T7 trading venues of Deutsche Börse Group and for the MDP feed of CME Group. The platform enables clients to perform pre/at/post trade analysis and to interact with market data and analytics.It provides clients access to the most granular un-normalized/genuine historical order book data (EOBI, MDP) as well as constructed order books, off-the-shelf analytics and allows them to build their own custom analytics utilizing algo functionality, which is a flexible high-performance framework based on historical order book data.<br/><br/> The A7 data can be accessed either via the <a href="https://a7.deutsche-boerse.com/">user interface</a> or via RESTful API.</br></br>

    The algo management API provides access to the A7 algos and their results. With the API it is possible to create, update, delete and run algos and to access the results of the algo runs. All available endpoints are described in detail below.<br/><br/>

    <b>Security measures:</b></br> In order to prevent unauthorized access to the API an authentication token must be used. A7 utilises the bearer authentication scheme for this purpose. The authentication token must be added to the header of each request message. Depending on the implementation it might be necessary to add the keyword "Bearer" to the token string as a prefix followed by a space.</br></br> A token can be generated at the <a href="https://a7.deutsche-boerse.com/">A7 user interface</a>. After login the user has to click on the user icon in the upper right corner, click on <b>API token generation</b> and finally click on <b>Request API key</b>. The generated token will be displayed directly in the user interface.<br/><br/>

    '
  contact:
    name: Deutsche Börse Data & Analytics
    url: https://www.mds.deutsche-boerse.com
    email: analytics@deutsche-boerse.com
  version: 1.0.2
servers:
- url: /api/v1
  description: A7 production environment
security:
- bearerAuth: []
tags:
- name: Pace of the Roll
paths:
  /insights/por:
    get:
      tags:
      - Pace of the Roll
      summary: Retrieve list of market segments
      description: The request delivers all available market segments as a list of strings.
      operationId: getMarketSegments
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  MarketSegments:
                    type: array
                    items:
                      $ref: '#/components/schemas/MarketSegment'
                required:
                - MarketSegments
            application/gzip:
              schema:
                type: object
                properties:
                  MarketSegments:
                    type: array
                    items:
                      $ref: '#/components/schemas/MarketSegment'
                required:
                - MarketSegments
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
  /insights/por/{MarketSegment}:
    get:
      tags:
      - Pace of the Roll
      summary: Retrieve list of rolls
      description: The request delivers all available rolls for the selected market segment as a list of dates (format =  YYYYMM).
      operationId: getRolls
      parameters:
      - $ref: '#/components/parameters/MarketSegment'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  Rolls:
                    type: array
                    items:
                      $ref: '#/components/schemas/Roll'
                required:
                - Rolls
            application/gzip:
              schema:
                type: object
                properties:
                  Rolls:
                    type: array
                    items:
                      $ref: '#/components/schemas/Roll'
                required:
                - Rolls
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
  /insights/por/{MarketSegment}/{Roll}:
    get:
      tags:
      - Pace of the Roll
      summary: Retrieve roll details
      description: "The request delivers the detailes for the selected roll as a JSON object.<br><br>  The details contain the current `r_0`, previous `r_1` and the one before the previous roll `r_2` as well as other previous rolls upto `n` (`r_3`, ..., `r_n`). The roll is defined as a ratio of adjusted open interest of a back-month contract to a sum of back- and front-month contract, for example Dec-2012 / (Sep-2012 + Dec-2012) for September 2012 roll. For each roll this ratio is calculated for a given number of days till expiry (`days`). The corresponding number of days till expiry `dte` is also provided in the output. Additionally, six quantiles (`q_0 = min`, `q_1 = 10%`, `q_2 = 25%`, `q_3 = 75%`, `q_4 = 90%`, `q_5 = max`) based on `n` previous rolls. In the selection of past rolls two alternative comparison methods can be used: consecutive (`comp=c`, i.e. Jun-2012, Mar-2012, Dec-2011, Sep-2011 etc. for Sep-2012 roll) or the same month (`comp=s`, i.e. Sep-2011, Sep-2010, Sep-2009, Sep-2008 for Sep-2012 roll).<br><br> Quantile `q` is the value of the largest `m`-th element such that `m / n <= q`, where `n` is the number of elements in an ordered list (in other words, `int index = q(double) * (n(int) - 1)`, where `index` is 0-based index of an element in an sorted list).\n\n  <b>Example:</b> `n = 30`:\n\n  `q_0 = min`: `m = 1` (`index = 0`, always the 1st element)\n  \n  `q_1 = 10%`: `m = 3` (`index = 2`, the 3rd element)\n  \n  `q_2 = 25%`: `m = 8` (`index = 7`, the 8th element)\n  \n  `q_3 = 75%`: `m = 22` (`index = 21`, the 22rd element)\n  \n  `q_4 = 90%`: `m = 27` (`index = 26`, the 27th element)\n  \n  `q_5 = max`: `m = n = 30` (`index = 29`, always the last element)\n"
      operationId: getRollDetails
      parameters:
      - $ref: '#/components/parameters/MarketSegment'
      - $ref: '#/components/parameters/Roll'
      - $ref: '#/components/parameters/days'
      - $ref: '#/components/parameters/n'
      - $ref: '#/components/parameters/comp'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RollDetails'
            application/gzip:
              schema:
                $ref: '#/components/schemas/RollDetails'
                format: binary
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
components:
  schemas:
    MarketSegment:
      description: market segment represented by a product
      type: string
      example: FDAX
    Ratio:
      description: ratio of adjusted open interest of a back-month contract to a sum of back- and front-month contract
      type: number
      format: float
      nullable: true
      minimum: 0
      maximum: 1
      example: 0.887223
    Roll:
      description: roll represented by a date (format = YYYYMM)
      type: integer
      format: int32
      pattern: ^\d{6}$
      example: 202103
    RollDetails:
      type: object
      required:
      - dte
      - r_0
      - q_0
      - q_1
      - q_2
      - q_3
      - q_4
      - q_5
      properties:
        dte:
          description: days till expiry
          type: array
          items:
            type: integer
            minimum: 0
            example: 1
        r_0:
          description: current roll
          type: array
          items:
            $ref: '#/components/schemas/Ratio'
        r_1:
          description: previous roll
          type: array
          items:
            $ref: '#/components/schemas/Ratio'
        r_2:
          description: one before the previous roll
          type: array
          items:
            $ref: '#/components/schemas/Ratio'
        r_n:
          description: n-th previous roll
          type: array
          items:
            $ref: '#/components/schemas/Ratio'
        q_0:
          description: 0% quantile (minimum)
          type: array
          items:
            $ref: '#/components/schemas/Ratio'
        q_1:
          description: 10% quantile
          type: array
          items:
            $ref: '#/components/schemas/Ratio'
        q_2:
          description: 25% quantile
          type: array
          items:
            $ref: '#/components/schemas/Ratio'
        q_3:
          description: 25% quantile
          type: array
          items:
            $ref: '#/components/schemas/Ratio'
        q_4:
          description: 90% quantile
          type: array
          items:
            $ref: '#/components/schemas/Ratio'
        q_5:
          description: 100% quantile (maximum)
          type: array
          items:
            $ref: '#/components/schemas/Ratio'
  parameters:
    days:
      name: days
      in: query
      description: Number of days till expiry including the expiry day
      example: 15
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 31
        default: 10
    MarketSegment:
      name: MarketSegment
      in: path
      description: Name of the market segment
      example: FDAX
      required: true
      schema:
        $ref: '#/components/schemas/MarketSegment'
    Roll:
      name: Roll
      in: path
      description: Roll in the format YYYYMM
      example: 202103
      required: true
      schema:
        $ref: '#/components/schemas/Roll'
    n:
      name: n
      in: query
      description: Maximal number of previous rolls for quantile calculation
      example: 20
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 99
        default: 30
    comp:
      name: comp
      in: query
      description: "Comparison parameter to control which past rolls are considered for the calculation. <br>\n  * `s` = Data from the same expiration month from previous years\n  * `c` = Data from `n` consecutive months prior to the selected roll\n"
      required: false
      schema:
        type: string
        default: c
        enum:
        - c
        - s
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer