The Whole Segments Tree resource represents (potentially) the whole of the Segments Tree, which contains analysis results data in the form of segments, securities and measure values. (The Segments Tree Node resource, by contrast, represents only one node of the tree, where the node represents a segment. The resource can include that segment’s children, which are either child segments or securities.)
A portfolio analysis with results data always exposes a hierarchical collection of segments and securities, known as the Segments Tree. Through this resource, calling applications can obtain 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.
Unlike virtually all other resources exposed by the web service, the Whole Segments Tree resource is represented by CSV (comma-separated values) only. There are no XML and JSON representations, and the request’s Accept header is ignored.
The Whole Segments Tree resource has been designed to support requests for the Multiple OCP Time Series resource, in that it exposes the segment identifiers that the latter needs. See the documentation on the
multiple-ocp-time-series-query link relation for further details.
The key to understanding the Whole Segments Tree 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
whole-segments-tree-query link relation, which contains the full details.
The Whole Segments Tree resource is exposed via a single CSV representation, which has the following media type name:- > application/vnd.statpro.revolution.api.whole-segments-tree+csv
When a response is received from the web service with status 200 (= OK), the fact that the response contains a Whole Segments Tree resource representation is indicated by the presence of the response header:- > Content-Type: application/vnd.statpro.revolution.api.whole-segments-tree+csv; charset=utf-8
isSecurity,id,parentId,name,Rp.Earliest,Wp.Earliest,Rp.1D,Wp.1D 1,27,7,"FICTIONAL SECURITY, SE",5.2,-6.3,7.4,9.8 0,6,5,Energy,,,-2.185802267485,-3.9586464194388 1,31,6,BP PLC,,,, 0,5,-1,TOTAL,3.77732459631624,81.3540101895826,27.1858022674852,53.9586464194388 1,28,6,BG GROUP PLC,-0.224088956620961,-0.445544385605846,,0.119144341580659 1,15,7,AIR LIQUIDE,2.0,-3.1,, 0,7,5,Materials,81.3540101895826,0.2340101895826,-5.000802267485, 1,18,7,ANGLO AMERICAN PLC,4.2,5.3,6.4,7.8
For this example, the query strings in the URI that requested the data were:
See below for an explanation of the data format.
nameare static and are always present in every representation.
Wp.1D(in the above example) are dynamic, and reflect the requested time periods and measures.
measuresquery strings, with the measures changing more rapidly.
isSecuritycolumn:- 0 = a segment; 1 = a security
idcolumn:- the values are unique segment and security identifiers. They are guaranteed to be positive integers (greater than or equal to zero). They are scoped to the current, finished analysis only. They do not have global scope, and do not persist beyond the lifetime of the current set of analysis results. When a new set of analysis results is generated for the same portfolio, the segment and security identifiers will be new. These identifiers are opaque, i.e. they have no meaning. If the TOTAL segment has id N in one set of analysis results, it is NOT guaranteed that it will have the same id N in another set of analysis results (even for the same portfolio). The same goes for the other segments, and for securities.
parentIdcolumn:- for any one row, the value is the identifier of the segment’s or security’s parent segment. Special value -1 is reserved as the parent segment id of the TOTAL segment (aka the Total segment, which sits at the root of the tree).
namecolumn:- the values are the names of each segment / security. These strings are normally unquoted. A name will be surrounded by leading and trailing double-quote characters if a) it is empty or contains only whitespace (which is unlikely), or b) it contains a comma and/or a double-quote character - as in
"FICTIONAL SECURITY, SE"in the example above. Genuine double-quote characters within segment / security names are encoded as two consecutive double-quote characters; e.g. name
CITIGROUP INC - DPS (RE: 1/10TH PFD SER "V" FXD ADJ)will exist in the CSV as
"CITIGROUP INC - DPS (RE: 1/10TH PFD SER ""V"" FXD ADJ)".
Rp.Earliest:- the format of the header name is
<measure identifier> + <dot> + <time period code>. The measure identifiers are normalized to their case-correct forms, as are the time period codes. E.g. if the requested data is
?timePeriods=earliest&measures=rpthe resulting header name will be
Materials, the last column (header
Wp.1D) is missing its measure value - this is not immediately obvious when looking at the CSV data.
Having requested the whole tree (i.e. all segments and all securities), and having parsed the CSV data into a collection of records within your application:-
To prevent your application from malfunctioning in the future, when new headers / columns are introduced to the CSV representation:-
isSecurity) rather than by position.
Last updated: September 2014