StatPro Revolution Web API


The Time Series Resource


Overview

The Time Series resource represents data points in a time series, for a specific segment or security in a portfolio analysis's results data. Each data point contains values for one or more requested measures. The data points are either periodic (each has a start date and end date) or non-periodic (each exists at a single date).

The key to understanding the Time Series resource is knowing what data can be included in any one request, and how to formulate a query for that data. To this end, please see the documentation for the time-series-query link relation, which contains the full details.

Extracting Security Level Time Series

As of the March 2019 release it is now possible to extract time series data for individual securities via this resource (using new link relations from the segments tree node resource). Prior to this release it had only been possible to extract segment level results. However, when requesting time series data for a security it is possible that the time series results are not immediately available in the returned representation. A status property is emitted which indicates whether or not time series results are being calculated (= InProgress) or are ready (= Finished). This status is completely independent of the portfolio analysis's status and only represents that status of this specific request for a single security's time series. When the status is returned as Finished status then the data points are emitted as normal. When the status is returned as InProgress the caller should back-off for a period of time and poll using the self link until results are available. This is because security level results represent a more heavy duty calculation and as such may not always be immediately available on request. For segment level time series results the status is always emitted as Finished and so no such polling is required if only interested in segment levels.

See the annotated representations below for details of how the requested information is contained in XML and JSON representations of the resource.


Media types

The Time Series resource is exposed via XML and JSON representations, which have the following media type names:-

application/vnd.statpro.revolution.api.time-series+json

application/vnd.statpro.revolution.api.time-series+xml

When a response is received from the web service with status 200 (= OK), the fact that the response contains a Time Series resource representation is indicated by the presence of one of these two response headers:-

Content-Type: application/vnd.statpro.revolution.api.time-series+json; charset=utf-8

Content-Type: application/vnd.statpro.revolution.api.time-series+xml; charset=utf-8


Related resources

The Time Series resource links to the Service resource (and to itself). To do so, its resource representations use link relations:-

  • self
  • service
  • time-series-query

The self link relation identifies the Time Series resource link, in which the representation is the same as the one that has been currently retrieved (so long as the underlying data on the server hasn't changed).

The service link relation identifies the Service resource link.

The time-series-query link relation identifies the link that allows a new query for time series data to be made, for the same segment or security (= the segment/security for which the current resource representation contains time series data).

All related resources are accessed using the HTTP GET method.


Update history

  • Added support for extracting time series data at security level. In order to support this a new property status was added since security level results are not necessarily available immediately. (See Extracting Security Level Time Series for further details) - Mar 2019
  • If the requested start date falls on a weekend or a bank holiday, the actual start date of the time series may be earlier than requested; this is a change from the previous behaviour in which the actual start date could be later as opposed to earlier - July 2014
  • Changes to the annotations for a time series's start and end dates - July 2014
  • seriesType XML element and JSON member can have values "Cumulative" and "OverallCustomPeriod", in addition to "Raw" and "CumulativeIndexed" - January 2014
  • eula link relation removed - September 2013
  • Initial Version - February 2013

Annotated Representations (JSON)

Legend

Periodic Data

{
  "timeSeries": {
    "links": {
      "service": {
        "rel": "service",
        "href": "...",
        "type": "application/vnd.statpro.revolution.api.service+json"
      },
      "self": {
        "rel": "self",
        "href": "...",
        "type": "application/vnd.statpro.revolution.api.time-series+json"
      },
      "timeSeriesQuery": {
        "rel": "time-series-query",
        "href": "...?measures={measuresList}&startDate={startDate}&endDate={endDate}&seriesType={seriesType}",
        "type": "application/vnd.statpro.revolution.api.time-series+json"
      }
    },
    "segmentName": "TOTAL",
    "seriesType": "Raw",
    "status": "Finished",
    "startDate": "2012-09-26",
    "endDate": "2012-10-01",
    "measures": [
      "Rp",
      "RelR"
    ],
    "dataPoints": {
      "type": "periodic",
      "items": [
        {
          "s": "2012-09-26",
          "e": "2012-09-27",
          "m": [
            -0.224088956620961,
            -0.445544385605846
          ]
        },
        {
          "s": "2012-09-27",
          "e": "2012-09-28",
          "m": [
            0.119144341580659,
            0.715152969607115
          ]
        },
        {
          "s": "2012-09-28",
          "e": "2012-10-01",
          "m": [
            0.822106407127784,
            -0.564601572877213
          ]
        }
      ]
    }
  }
}

Non-periodic Data

{
  "timeSeries": {
    "links": {
      "service": {
        "rel": "service",
        "href": "...",
        "type": "application/vnd.statpro.revolution.api.service+json"
      },
      "self": {
        "rel": "self",
        "href": "...",
        "type": "application/vnd.statpro.revolution.api.time-series+json"
      },
      "timeSeriesQuery": {
        "rel": "time-series-query",
        "href": "...?measures={measuresList}&startDate={startDate}&endDate={endDate}&seriesType={seriesType}",
        "type": "application/vnd.statpro.revolution.api.time-series+json"
      }
    },
    "segmentName": "Materials",
    "seriesType": "CumulativeIndexed",
    "status": "Finished",
    "startDate": "2012-09-26",
    "endDate": "2012-10-01",
    "measures": [
      "Rp",
      "Rb"
    ],
    "dataPoints": {
      "type": "atDate",
      "items": [
        {
          "d": "2012-09-26",
          "m": [
            100.0,
            100.0
          ]
        },
        {
          "d": "2012-09-27",
          "m": [
            100.611282185304,
            100.99385157
          ]
        },
        {
          "d": "2012-09-28",
          "m": [
            99.6566038598803,
            101.074064084382
          ]
        },
        {
          "d": "2012-10-01",
          "m": [
            102.029071221907,
            103.218414374245
          ]
        }
      ]
    }
  }
}

Security Level Request - In Progress

{
  "timeSeries": {
    "links": {
      "service": {
        "rel": "service",
        "href": "...",
        "type": "application/vnd.statpro.revolution.api.service+json"
      },
      "self": {
        "rel": "self",
        "href": "...",
        "type": "application/vnd.statpro.revolution.api.time-series+json"
      },
      "timeSeriesQuery": {
        "rel": "time-series-query",
        "href": "...?measures={measuresList}&startDate={startDate}&endDate={endDate}&seriesType={seriesType}",
        "type": "application/vnd.statpro.revolution.api.time-series+json"
      }
    },
    "segmentName": "StatPro Group PLC",
    "seriesType": "Raw",
    "status": "InProgress"
  }
}


Annotated Representations (XML)

Legend

Periodic Data

<?xml version="1.0" encoding="utf-8"?>
<timeSeries xmlns="http://statpro.com/2012/Revolution">
  <link rel="service"
        href="..."
        type="application/vnd.statpro.revolution.api.service+xml" />
  <link rel="self"
        href="..."
        type="application/vnd.statpro.revolution.api.time-series+xml" />
  <link rel="time-series-query"
        href="...?measures={measuresList}&amp;startDate={startDate}&amp;endDate={endDate}&amp;seriesType={seriesType}"
        type="application/vnd.statpro.revolution.api.time-series+xml" />
  <segmentName>TOTAL</segmentName>
  <seriesType>Raw</seriesType>
  <status>Finished</status>
  <startDate>2012-09-26</startDate>
  <endDate>2012-10-01</endDate>
  <measures>
    <measure>Rp</measure>
    <measure>RelR</measure>
  </measures>
  <dataPoints type="periodic">
    <dp s="2012-09-26" e="2012-09-27">-0.224088956620961, -0.445544385605846</dp>
    <dp s="2012-09-27" e="2012-09-28">0.119144341580659, 0.715152969607115</dp>
    <dp s="2012-09-28" e="2012-10-01">0.822106407127784, -0.564601572877213</dp>
  </dataPoints>
</timeSeries>

Non-periodic Data

<?xml version="1.0" encoding="utf-8"?>
<timeSeries xmlns="http://statpro.com/2012/Revolution">
  <link rel="service"
        href="..."
        type="application/vnd.statpro.revolution.api.service+xml" />
  <link rel="self"
        href="..."
        type="application/vnd.statpro.revolution.api.time-series+xml" />
  <link rel="time-series-query"
        href="...?measures={measuresList}&amp;startDate={startDate}&amp;endDate={endDate}&amp;seriesType={seriesType}"
        type="application/vnd.statpro.revolution.api.time-series+xml" />
  <segmentName>Materials</segmentName>
  <seriesType>CumulativeIndexed</seriesType>
  <status>Finished</status>
  <startDate>2012-09-26</startDate>
  <endDate>2012-10-01</endDate>
  <measures>
    <measure>Rp</measure>
    <measure>Rb</measure>
  </measures>
  <dataPoints type="atDate">
    <dp d="2012-09-26">100, 100</dp>
    <dp d="2012-09-27">100.611282185304, 100.99385157</dp>
    <dp d="2012-09-28">99.6566038598803, 101.074064084382</dp>
    <dp d="2012-10-01">102.029071221907, 103.218414374245</dp>
  </dataPoints>
</timeSeries>

Security Level Request - In Progress

<?xml version="1.0" encoding="utf-8"?>
<timeSeries xmlns="http://statpro.com/2012/Revolution">
  <link rel="service"
        href="..."
        type="application/vnd.statpro.revolution.api.service+xml" />
  <link rel="self"
        href="..."
        type="application/vnd.statpro.revolution.api.time-series+xml" />
  <link rel="time-series-query"
        href="...?measures={measuresList}&amp;startDate={startDate}&amp;endDate={endDate}&amp;seriesType={seriesType}"
        type="application/vnd.statpro.revolution.api.time-series+xml" />
  <segmentName>StatPro Group PLC</segmentName>
  <seriesType>Raw</seriesType>
  <status>InProgress</status>
</timeSeries>


Last updated: Mar 2019


To Top