StatPro Revolution Web API


The whole-segments-tree-query Link Relation


Overview

The whole-segments-tree-query link relation identifies a link that targets the Whole Segments Tree resource, which is accessed using the HTTP GET method.

See the segments-tree-root-node-query link relation for alternative way of getting Segments Tree data.


Notes

A portfolio analysis with results data always exposes a hierarchical collection of segments and securities, known as the Segments Tree. Using this link relation, the web service affords access to data for the tree's root node (the Total segment), or all segments, or all securities, or the Total segment and all securities, or all segments and securities (i.e. the whole tree) - for one or more measures across one or more time periods.

Client applications should use this link relation to access Segments Tree data for three reasons:-

  1. To get (potentially) the whole of the segments tree in one request, rather than a request per node in the tree.
  2. To get segments, securities and measures data in a compact, tabular format (CSV, not XML / JSON).
  3. To get the segment identifiers that are needed when formulating a request for data from the Multiple OCP Time Series resource for the same set of analysis results, using the multiple-ocp-time-series-query link relation.


Querying for Data

A link relation whose name ends with -query indicates that the client application 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:-

timePeriods={timePeriodsList}
measures={measuresList}
include={dataToInclude}

{timePeriodsList} must be replaced by a comma-delimited list of one or more time period codes for which data is required. It is a bad request if this list is empty, contains a duplicated code, contains an unknown/invalid code, or contains the code of a time period that doesn't exist in the analysis results. (Refer to the portfolio's Portfolio Analysis resource for information about which time periods exist in the analysis results.)

{measuresList} must be replaced by a comma-delimited list of one or more identifiers of required measures. See this page for a full list of supported measures, their identifiers and their descriptions. It is a bad request if this list is empty, contains a duplicated identifier, contains an invalid identifier, or contains the identifier of a measure that is not supported by the Segments Tree.

{dataToInclude} must be replaced by an identifier that indicates what data to include, one of:-

Identifier Includes...
Total The TOTAL segment only
Segments All segments, including the TOTAL segment; no securities
Securities All securities; no segments
TotalAndSecurities The TOTAL segment and all securities; no child segments
All All segments and all securities


Querying Examples

1) Get all segments and all securities (i.e. the whole tree), in the one year time period. Include the Portfolio Return and Benchmark Return measures.

timePeriods=1Y
measures=Rp,Rb
include=All

2) Get the TOTAL segment only, in the one year and six month time periods. Include the Portfolio Return and Benchmark Return measures.

timePeriods=1Y,6M
measures=Rp,Rb
include=Total

3) Get all segments, in the Earliest time period. Include the Weight Mean measure.

timePeriods=Earliest
measures=Wp
include=Segments


Update history

  • Initial Version - September 2014


Last updated: September 2014


To Top