StatPro Revolution Web API


The segments-tree-root-node-query Link Relation


Overview

The segments-tree-root-node-query link relation identifies a link that targets the Segments Tree Node resource, which is accessed using the HTTP GET method. More specifically, the link targets the root node of the Segments Tree, and a client application must formulate a query for the data that the web service is to provide.

See the whole-segments-tree-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 the Segments Tree one node at a time, starting at the root node, which equates to the Total segment. (An alternative way of accessing the Segments Tree is via the Whole Segments Tree resource, introduced in September 2014. See the documentation for that resource and its link relation for more details.)

Any one node in the Segments Tree represents a segment, either the Total segment or a child segment (or the child of a child, and so on). A node cannot represent a security, but any node can contain securities. In addition, tree node representations can contain client-requested measures (e.g. Portfolio Return; Alpha; Beta; Weight Mean).

The link identified by this link relation allows a client application to access the root node of the Segments Tree. Access to child segments and securities further down the tree is afforded by following links that are included in each generated representation of the Segments Tree Node resource. In addition, when using this link a client application must formulate a query for the data that it wants. Via the query, a client application specifies:-

  • the time period(s) for the requested data;
  • whether the representation should include child segments or securities (or neither) in addition to data about the segment that the node represents;
  • the measures that are required;
  • the areas of the node for which measures are required (segment / child segments / securities);
  • how the node's collection of child segments or securities (if requested) should be filtered, ordered and sliced before being included in the returned representation.

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

  • data for the 3 Month, 6 Month and Year-to-Date time periods;
  • child segments to be included in addition to the segment that the node represents;
  • the Portfolio Return, Alpha and Beta measures;
  • measures to be included for both the segment that the node represents, and its child segments;
  • the child segments to be paged, with a page size of 10.


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 string values) before requesting the target resource. A query is formulated by replacing the text-replacement parts of the link's URI (e.g. {filter}) 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}
include={dataToInclude}
measures={measuresList}
includeMeasuresFor={measuresFor}
$filter={filter}
$orderby={orderby}
$skip={skip}
$top={top}

{timePeriodsList} must be replaced by a comma-delimited list of time period codes for which data is required. If empty, the "Earliest" time period will be used. It is a bad request if this list includes an unknown/invalid time period code, or 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 that the "Earliest" time period will always exist.)

{dataToInclude} must be replaced by an indication as to what data area is to be included in the returned representation, in addition to the segment data. Valid values are "childSegments", "securities" or "none". It is a bad request if set to an unrecognised value. If set to the empty string, then "childSegments" will be used. Note that it is not possible to have both child segments and securities in the same resource representation.

{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. See this page for a full list of supported measures, their identifiers and their descriptions. Note that to actually get measure values in the returned representation, the includeMeasuresFor query string must also be set; see below for details.

{measuresFor} must be replaced by a comma-delimited list of identifiers of those parts (or areas) of the returned representation that measures are required for. Recognised identifiers are "segment", "childSegments" and "securities". It is a bad request if an unknown/invalid identifier is included in the list. If empty then measures will not be included in the returned representation. Therefore, to get measure values, both the measures and includeMeasuresFor query strings must be set correctly. Tip: if you want measures for child segments now, and measures for securities later (i.e. further down the tree), include both "childSegments" and "securities" in this comma-delimited list.

The remaining query strings determine how the segment's children (which may be child segments or securities) are to be filtered, ordered and sliced before being included in the returned representation. These query strings aren't used if the segment's children aren't included, or if the segment has no children. Even if not used, {filter}, {orderby}, {skip} and {top} must still be replaced; the easiest thing is to replace with the empty string. See the appropriate section below for further details.


Query Persistence

A query for data starts at the root node. The same choices (e.g. which measures, which time periods) are then embedded in the query strings of the emitted links that drill down into other nodes in the tree. If different data is required, a client application is expected to issue a new query that starts at the root node again. A link with the segments-tree-root-node-query link relation is provided for this purpose in every Segments Tree Node resource representation that the web service returns.

If child segments data is included in retrieved nodes, then each child segment will have a link that drills down into the next level of the tree. Normally these links will request more child segments. If the next level down is the bottom level, then the link will instead request securities, since the bottom-most level can't contain child segments by definition. (A node at the bottom-most level will represent a segment, but it can't contain child segments.) See the annotated representations for the Segments Tree Node resource for more details.


Filtering, Ordering and Slicing Children

When processing a query for a node that is to include a segment's child segments or securities (known as its children), the web service will first filter the underlying collection of children. The filtered set will then be ordered. The ordered set will then be sliced by skipping the first N children, and then by taking M children.

The $filter, $orderby, $skip and $top query strings are all ODATA system query options. Note that the web service only supports a subset of the ODATA filtering and ordering syntaxes. These two subsets are described in the section below.

To formulate a query for children, replace {filter}, {orderby}, {skip} and {top} in the URI with the correct values. (Filtering and ordering values typically contain spaces, which must be URI-encoded as %20.) All of the above can be replaced by the empty string, which will cause defaults to be used; the defaults are:-

  • no filtering
  • order will be determined by the web service
  • zero children will be skipped in the ordered set
  • a maximum of 100 children will be taken from the ordered set.

If no ordering is specified by the client, the web service will impose its own ordering (= by child name, ascending).

Certain values for the slicing query options ($skip and $top) may cause the returned collection of children to be paged. See the documentation for the Segments Tree Node resource for more details.


Query Syntax for Filtering, Ordering and Slicing Children

Filtering

The OData $filter system query option has a complex expression language, with a large set of operators and functions. The Revolution Web API currently supports only a very limited - but still useful - subset of this expression language for child filtering.

Supported filtering format:-

<numeric_measure_id> eq|ne|gt|ge|lt|le <numeric_value>

Example:-

Rp le 100.0

This example means: "filter to yield children whose Portfolio Return is less than or equal to 100".

See this page for the complete list of measures and their identifiers, although note that only the measures that are of numeric type in this list are supported for filtering. Note also that you don't have to request the measure to be included in the segments tree node in order to use it for filtering.

If specified, the filter is applied across all requested time periods, and will result in one of the following outcomes:-

  • the child is present in all requested time periods;
  • the child is present in some but not all requested time periods;
  • the child is not present in any requested time period, and so is completely filtered out and is not present in the returned representation.

See below for further filtering examples.

Ordering

The OData $orderby system query option has a sophisticated expression syntax for expressing ordering. The Revolution Web API currently supports a limited but useful subset of this syntax for child ordering.

Supported ordering formats:-

name[ asc|desc]
<measureId>-<periodCode>[ asc|desc]

Example 1:-

name desc

This example means that children will be ordered by name, descending.

Example 2:-

Rp-1Y

This example means that children will be ordered by the value of the Portfolio Return measure in the one year time period, ascending.

See this page for the complete list of measures and their identifiers, although note that only the measures that are of numeric type in this list are supported for ordering.

Note that you don't have to request the measure to be included in the segments tree node in order to use it for ordering, nor does the time period have to be one of the requested time periods. The only constraints are that the measure is numeric, and the time period exists in the portfolio analysis's results data.

See below for further ordering examples.

Slicing

$skip=N indicates how many children to skip in the set of children that results after filtering and ordering.

$top=M indicates how many children to take from the top of the set of children that results after filtering, ordering and skipping.


Querying Examples

In these examples, query string values are shown with spaces, for clarity. In the actual URIs, the space character must be URI-encoded as %20.

In the examples below, if a query string (e.g. measures) isn't shown, then it's assumed to be set to the empty string (e.g. measures=).

1) Get the Total segment and its child segments, in the one year time period.

timePeriods=1Y
include=childSegments

2) Get the Total segment and its child segments, in the one year time period. Include the Portfolio Return and Benchmark Return measures for both the Total segment and the child segments.

timePeriods=1Y
include=childSegments
measures=Rp,Rb
includeMeasuresFor=segment,childSegments

3) Get the Total segment and its child segments, in the one year and six month time periods. Include the Portfolio Return and Benchmark Return measures for both the Total segment and the child segments. In anticipation of drilling down to the bottom-most level of tree, which will contain securities and not child segments, say that we want measures for securities as well.

timePeriods=1Y,6M
include=childSegments
measures=Rp,Rb
includeMeasuresFor=segment,childSegments,securities

4) As above, except that child segments (and later on securities, when we drill down to the bottom level of the tree) are filtered, ordered and sliced.

timePeriods=1Y,6M
include=childSegments
measures=Rp,Rb
includeMeasuresFor=segment,childSegments,securities
$filter=Rp gt 0.0
$orderby=Rp-6M
$skip=0
$top=4

5) Get the Total segment and its securities, in the Earliest time period. Get the Weight Mean measure for the securities (not the Total segment). Get four securities at a time, starting at the first page of four securities.

timePeriods=Earliest
include=securities
measures=Wp
includeMeasuresFor=securities
$skip=0
$top=4


Update history

  • Updated the OData website links - September 2014
  • Updated with references to the Whole Segments Tree resource and its whole-segments-tree-query link relation - September 2014
  • Initial Version - February 2013


Last updated: September 2014


To Top