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.


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


{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.)

NOTE: Some period codes are of the form “SpecificDate-yyyyMMdd:SpecificDate-yyyyMMdd” to represent a specific time period between two specified dates. A more compact form of “yyyyMMdd:yyyyMMdd” is supported to help alleviate potential problems with requesting a large number of such time periods and breaching the 4K character URI limit (See here for further details). So for example, “SpecificDate-20180101:SpecificDate-20180131” and “20180101:20180131” are semantically equivalent when requested in the {timePeriodsList}. But in the CSV output it will always use the longer form in the column header irrespective of the form requested.

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

TotalThe TOTAL segment only
SegmentsAll segments, including the TOTAL segment; no securities
SecuritiesAll securities; no segments
TotalAndSecuritiesThe TOTAL segment and all securities; no child segments
AllAll 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.


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


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


Update history

  • Added support for a more compact form of periodCode for “SpecificDate-yyyyMMdd:SpecificDate-yyyyMMdd” - October 2018
  • Initial Version - September 2014

Last updated: September 2018