StatPro Revolution Web API


The time-series-query Link Relation


Overview

The time-series-query link relation identifies a link that targets the Time Series resource, which is accessed using the HTTP GET method. The Time Series resource provides time series data for an individual segment (e.g. the Total segment) in a portfolio analysis's results data. Where the link is embedded in XML and JSON resource representations determines what that segment is. When retrieving time series data, a client application must formulate a query for the data that the web service is to provide (measures; start/end dates; series type).


Notes

A portfolio analysis with results data always contains a hierarchical collection of segments. Any one of these segments can have associated time series data: i.e. measure values associated with the segment, where values are recorded over a series of consecutive working-day periods:-

  • 2012-09-26 -> 2012-09-27   (wednesday to thursday)
  • 2012-09-27 -> 2012-09-28   (thursday to friday)
  • 2012-09-28 -> 2012-10-01   (friday to monday)

When accessing the Time Series resource for a particular segment, a client application must formulate a query for the data that it wants. Via the query, a client application specifies:-

  • the start and end dates of the time series
  • the required measure(s)
  • the series type (raw, or processed in some way)

For example, a client application can say that it wants:-

  • data between the earliest date in the portfolio analysis and the most recent
  • values for the Rp (Portfolio Return) and Rb (Benchmark Return) measures
  • raw data (unprocessed measure values over consecutive working-day periods).

The client application does not identify the segment in the query. The segment is identified by the context of the time-series-query link, i.e. its location within XML or JSON representations of the Portfolio Analysis, Segments Tree Node and Time Series resources. A Portfolio Analysis representation contains a link that targets the Total segment. A Segments Tree Node representation contains a link that targets the segment that the node represents, as well as links that target each child segment that the node contains (if any). A Time Series representation contains a link that targets the segment that is represented by that time series; i.e. a client app can issue a new query for time series data for the same segment.


Querying for Data

A link relation whose name ends with -query indicates that the client application may or must formulate a query (in this case via query strings) before requesting the target resource. A query is formulated by replacing the text-replacement parts of the link's URI (e.g. {measuresList}) with values before making the request. Failing to replace all the text-replacement parts of the query string, or specifying invalid values, will result in a 400 (= Bad Request) response.

The link's URI contains the following query strings:-

measures={measuresList}
startDate={startDate}
endDate={endDate}
seriesType={seriesType}

{measuresList} must be replaced by a comma-delimited list of identifiers of required measures. If set to the empty string, then no measures are requested (which is an error). See the list of supported measures for details of what measures can be requested. Note that, although approximately 150 measures are available, the maximum number that can be included in any one request is 10. Note also that, when compounding, certain measures require other, extra measures to be involved, and these count towards the no-more-than-10-per-request limit. See Extra measures required for compounding below for more details.

{startDate} must be replaced by the starting date for the time series, in ISO 8601 date format (e.g. "2010-10-30"). If set to the empty string, then the earliest date in the analysis results will be used (= the earliest time period's start date).

{endDate} must be replaced by the ending date for the time series, in ISO 8601 date format (e.g. "2012-09-21"). If set to the empty string, then the latest date in the analysis results will be used (= the latest time period's end date).

{seriesType} must be replaced by the series type. Currently supported values are "raw", "cumulativeIndexed", "cumulative" and "overallCustomPeriod" (without the quotes). If set to the empty string, then the Raw series type will be requested.


Series Types

Raw data is periodic and unprocessed. Missing / unavailable / null values (e.g. for benchmark measures, where the portfolio in question doesn't have a benchmark) are returned as nulls.

Cumulative Indexed data is non-periodic (each measure value exists at a single date) and is compounded from the raw data. Cumulative Indexed data starts from a base value of 100 at the first date, and all subsequent dates represent the cumulative effect on the base value from the first date.

Cumulative data is periodic, and is compounded from the raw data. Each period starts at the very first date of the requested time series. The very last period in a Cumulative series represents the effect of compounding values from the very first date in the requested time series to the last.

Overall Custom Period data is identical to Cumulative data, except that only the last period is returned to the client application. This represents the effect of compounding values over the whole of the requested time period (which may be any custom period within the earliest-date to latest-date range).


Compounding Notes

Where a selected measure cannot be compounded - or is incompatible with Cumulative Indexed compounding - its value in the returned time series is always null.

The list of supported time series measures indicates if a measure can be compounded or not. This information is also available in XML and JSON form; see Requestable analytics measures for more details.

For Cumulative Indexed compounding, null values in the raw data are treated as zeroes.

For Cumulative and Overall Custom Period compounding, null values in the raw data are treated as zeroes in most cases. For simple measures, such as Portfolio Return and Benchmark Return, however, null values can be returned if there is missing / unavailable / null values for those measures in the raw data.

Measures 'Benchmark Held for Full Period' and 'Held for Full Period' are useful when compounding time series. They indicate whether the benchmark and the portfolio (respectively) were held for the full compounding period; a value of 1.0 means true (held), 0.0 means false (not held). Where benchmark-related and/or portfolio-related values are returned, these measures can be used to assess the relevance of those values.


Extra measures required for compounding

There are a few measures that, when compounded, require extra measures to be used in the compounding computation. For example, the compounding of Relative Return requires the use of Return (aka Portfolio Return) and Benchmark Return.

If explicitly requested by the calling application, these extra measures will be returned in the XML or JSON resource representation, as per normal. If one or more required extra measures aren't explicitly requested however, internally the Web API will extract data for those measures, and will use the data in the computation. Because the measures weren't requested, their values won't be returned to the calling client, but they will count towards the maximum limit of 10 measures per request. Therefore it is possible to exceed the maximum limit even if less than 10 measures were explicitly requested. In this case, the response status will be 400 (i.e. Bad Request) and the reason phrase will be:

Too many time series measures were requested, after adding additional measures that are required for compounding to the list of measures that were explicitly requested. (REVAPI_ERROR=855)

The following table lists the seven measures in question, along with their required extra measures.

Measure Required extras
Currency Compounding ([CUR]) Total Attribution MC ([CUR]), Total Market (local), Currency Allocation ([CUR]), Currency Timing ([CUR])
Total Currency ([CUR]) Total Attribution MC ([CUR]), Total Market (local)
Relative Return ([CUR]) Return ([CUR]), Benchmark Return ([CUR])
Relative Return (Geometric) ([CUR]) Return ([CUR]), Benchmark Return ([CUR])
Relative Return (Geometric) (Local) Return (Local), Benchmark Return (Local)
Relative Return (Local) Return (Local), Benchmark Return (Local)
Stock Picking Effect MC Stock Allocation (local), Stock Currency ([CUR]), Stock Timing and Trading Local


Differences between the first version and second versions of Time Series

Feature First version Second version
Requestable measures Supports 7 measures Supports ~143 measures
Series types Raw, Cumulative Indexed Raw, Cumulative Indexed, Cumulative, Overall Custom Period
Restrictions Certain measures are incompatible with Cumulative Indexed Maximum of 10 measures per request


Querying Examples

1) Get measure Rp (Portfolio Return), from the earliest available date to the latest, in raw time series data.

measures=Rp
startDate=
endDate=
seriesType=

2) Get measures Rp (Portfolio Return) and Rb (Benchmark Return), from a specific date range, in cumulative indexed time series data.

measures=Rp,Rb
startDate=2009-10-01
endDate=2012-09-30
seriesType=cumulativeIndexed


Update history

  • Added measure Stock Picking Effect MC to the table of measures that require extra measures for compounding - July 2014.
  • Revision of the material to describe the second version of the Time Series resource - January 2014.
  • Initial Version - February 2013


Last updated: July 2014


To Top