StatPro Revolution Web API


The Segments Tree Node Resource


Overview

The Segments Tree Node resource represents a node in the Segments Tree, which contains analysis results data in the form of segments, securities and measure values.

A portfolio analysis with results data always exposes a hierarchical collection of segments and securities, known as the Segments Tree. Through this resource, 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 key to understanding the Segments Tree Node resource is knowing what data can be included in any one node, and how to formulate a query for that data. To this end, please see the documentation for the segments-tree-root-node-query link relation, which contains the full details.

See the annotated representations below for details of how the requested information is contained in XML and JSON representations of the resource.


Media types

The Segments Tree Node resource is exposed via XML and JSON representations, which have the following media type names:-

application/vnd.statpro.revolution.api.segments-tree-node+json

application/vnd.statpro.revolution.api.segments-tree-node+xml

When a response is received from the web service with status 200 (= OK), the fact that the response contains a Segments Tree Node resource representation is indicated by the presence of one of these two response headers:-

Content-Type: application/vnd.statpro.revolution.api.segments-tree-node+json; charset=utf-8

Content-Type: application/vnd.statpro.revolution.api.segments-tree-node+xml; charset=utf-8


Related resources

The Segments Tree Node resource links to the Service, Portfolios and Time Series resources (and to itself). To do so, its resource representations use link relations:-

  • self
  • service
  • portfolios-query
  • segments-tree-root-node-query
  • time-series-query
  • next
  • prev
  • first
  • last

The self link relation is used to identify links to a) the current resource representation, and b) other nodes at one level down in the tree that represent the current node's child segments. See the annotated representations below for more details.

The service link relation identifies the Service resource link.

The portfolios-query link relation identifies the link that allows a new query for portfolios to be made.

The segments-tree-root-node-query link relation identifies the link that allows a new query for data from the Segments Tree to be made, starting (again) at the root node.

The time-series-query link relation identifies links that allow a client application to extract time series data for one or more measures for a) the segment that the node represents, and b) this node's child segments, if included. See the annotated representations below for more details.

The next, prev, first and last link relations identify links that target versions of the current resource representation that contain the next, previous, first and last pages of the node's children (either child segments or securities) - if included, and if paged.

All related resources are accessed using the HTTP GET method.


Update history

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

Annotated Representations (JSON)

Legend

Include Child Segments

{
  "segmentsTreeNode": {
    "links": {
      "service": {
        "rel": "service",
        "href": "...",
        "type": "application/vnd.statpro.revolution.api.service+json"
      },
      "portfoliosQuery": {
        "rel": "portfolios-query",
        "href": "...?$filter={filter}&$orderby={orderby}&$skip={skip}&$top={top}&includePublishedPortfolios=false&portfolioClassifierCode=",
        "type": "application/vnd.statpro.revolution.api.portfolios+json"
      },
      "self": {
        "rel": "self",
        "href": "...",
        "type": "application/vnd.statpro.revolution.api.segments-tree-node+json"
      },
      "segmentsTreeRootNodeQuery": {
        "rel": "segments-tree-root-node-query",
        "href": "...?timePeriods={timePeriodsList}&include={dataToInclude}&measures={measuresList}&includeMeasuresFor={measuresFor}&$filter={filter}&$orderby={orderby}&$skip={skip}&$top={top}",
        "type": "application/vnd.statpro.revolution.api.segments-tree-node+json"
      },
      "timeSeriesQuery": {
        "rel": "time-series-query",
        "href": "...?measures={measuresList}&startDate={startDate}&endDate={endDate}&seriesType={seriesType}",
        "type": "application/vnd.statpro.revolution.api.time-series+json"
      }
    },
    "treeLevel": {
      "this": 1,
      "count": 2
    },
    "segment": {
      "timePeriods": [
        "3M",
        "6M"
      ],
      "name": "TOTAL",
      "measures": [
        {
          "tp": "3M",
          "measures": [
            {
              "id": "rp",
              "ty": "r",
              "val": 3.0
            },
            {
              "id": "wp",
              "ty": "r",
              "val": 4.6
            }
          ]
        },
        {
          "tp": "6M",
          "measures": [
            {
              "id": "rp",
              "ty": "r",
              "val": 5.3
            },
            {
              "id": "wp",
              "ty": "r",
              "val": 6.7
            }
          ]
        }
      ]
    },
    "childSegments": {
      "classifier": {
        "name": "GICS Sector"
      },
      "paging": {
        "next": {
          "rel": "next",
          "href": "...",
          "type": "application/vnd.statpro.revolution.api.segments-tree-node+json"
        },
        "prev": {
          "rel": "prev",
          "href": "...",
          "type": "application/vnd.statpro.revolution.api.segments-tree-node+json"
        },
        "first": {
          "rel": "first",
          "href": "...",
          "type": "application/vnd.statpro.revolution.api.segments-tree-node+json"
        },
        "last": {
          "rel": "last",
          "href": "...",
          "type": "application/vnd.statpro.revolution.api.segments-tree-node+json"
        },
        "pageNumber": 2,
        "pageCount": 5
      },
      "segments": [
        {
          "links": {
            "self": {
              "rel": "self",
              "href": "...",
              "type": "application/vnd.statpro.revolution.api.segments-tree-node+json"
            },
            "timeSeriesQuery": {
              "rel": "time-series-query",
              "href": "...?measures={measuresList}&startDate={startDate}&endDate={endDate}&seriesType={seriesType}",
              "type": "application/vnd.statpro.revolution.api.time-series+json"
            }
          },
          "timePeriods": [
            "3M",
            "6M"
          ],
          "name": "Consumer Staples",
          "measures": [
            {
              "tp": "3M",
              "measures": [
                {
                  "id": "rp",
                  "ty": "r",
                  "val": 13.5
                },
                {
                  "id": "wp",
                  "ty": "r",
                  "val": 20.7
                }
              ]
            },
            {
              "tp": "6M",
              "measures": [
                {
                  "id": "rp",
                  "ty": "r",
                  "val": null
                },
                {
                  "id": "wp",
                  "ty": "r",
                  "val": null
                }
              ]
            }
          ]
        },
        {
          "links": {
            "self": {
              "rel": "self",
              "href": "...",
              "type": "application/vnd.statpro.revolution.api.segments-tree-node+json"
            },
            "timeSeriesQuery": {
              "rel": "time-series-query",
              "href": "...?measures={measuresList}&startDate={startDate}&endDate={endDate}&seriesType={seriesType}",
              "type": "application/vnd.statpro.revolution.api.time-series+json"
            }
          },
          "timePeriods": [
            "3M",
            "6M"
          ],
          "name": "Energy",
          "measures": [
            {
              "tp": "3M",
              "measures": [
                {
                  "id": "rp",
                  "ty": "r",
                  "val": 21.9
                },
                {
                  "id": "wp",
                  "ty": "r",
                  "val": 33.58
                }
              ]
            },
            {
              "tp": "6M",
              "measures": [
                {
                  "id": "rp",
                  "ty": "r",
                  "val": 38.69
                },
                {
                  "id": "wp",
                  "ty": "r",
                  "val": 48.91
                }
              ]
            }
          ]
        }
      ]
    }
  }
}

Include Securities

{
  "segmentsTreeNode": {
    "links": {
      "service": {
        "rel": "service",
        "href": "...",
        "type": "application/vnd.statpro.revolution.api.service+json"
      },
      "portfoliosQuery": {
        "rel": "portfolios-query",
        "href": "...?$filter={filter}&$orderby={orderby}&$skip={skip}&$top={top}&includePublishedPortfolios=false&portfolioClassifierCode=",
        "type": "application/vnd.statpro.revolution.api.portfolios+json"
      },
      "self": {
        "rel": "self",
        "href": "...",
        "type": "application/vnd.statpro.revolution.api.segments-tree-node+json"
      },
      "up": {
        "rel": "up",
        "href": "...",
        "type": "application/vnd.statpro.revolution.api.segments-tree-node+json"
      },
      "segmentsTreeRootNodeQuery": {
        "rel": "segments-tree-root-node-query",
        "href": "...?timePeriods={timePeriodsList}&include={dataToInclude}&measures={measuresList}&includeMeasuresFor={measuresFor}&$filter={filter}&$orderby={orderby}&$skip={skip}&$top={top}",
        "type": "application/vnd.statpro.revolution.api.segments-tree-node+json"
      },
      "timeSeriesQuery": {
        "rel": "time-series-query",
        "href": "...?measures={measuresList}&startDate={startDate}&endDate={endDate}&seriesType={seriesType}",
        "type": "application/vnd.statpro.revolution.api.time-series+json"
      }
    },
    "treeLevel": {
      "this": 2,
      "count": 2
    },
    "segment": {
      "timePeriods": [
        "3M",
        "6M"
      ],
      "name": "Consumer Staples",
      "measures": [
        {
          "tp": "3M",
          "measures": [
            {
              "id": "rp",
              "ty": "r",
              "val": 3.0
            },
            {
              "id": "wp",
              "ty": "r",
              "val": 4.6
            }
          ]
        },
        {
          "tp": "6M",
          "measures": [
            {
              "id": "rp",
              "ty": "r",
              "val": 5.3
            },
            {
              "id": "wp",
              "ty": "r",
              "val": 6.7
            }
          ]
        }
      ]
    },
    "securities": {
      "paging": {
        "next": {
          "rel": "next",
          "href": "...",
          "type": "application/vnd.statpro.revolution.api.segments-tree-node+json"
        },
        "prev": {
          "rel": "prev",
          "href": "...",
          "type": "application/vnd.statpro.revolution.api.segments-tree-node+json"
        },
        "first": {
          "rel": "first",
          "href": "...",
          "type": "application/vnd.statpro.revolution.api.segments-tree-node+json"
        },
        "last": {
          "rel": "last",
          "href": "...",
          "type": "application/vnd.statpro.revolution.api.segments-tree-node+json"
        },
        "pageNumber": 2,
        "pageCount": 5
      },
      "securities": [
        {
          "timePeriods": [
            "3M",
            "6M"
          ],
          "name": "Diageo Plc",
          "measures": [
            {
              "tp": "3M",
              "measures": [
                {
                  "id": "rp",
                  "ty": "r",
                  "val": 13.5
                },
                {
                  "id": "wp",
                  "ty": "r",
                  "val": 20.7
                }
              ]
            },
            {
              "tp": "6M",
              "measures": [
                {
                  "id": "rp",
                  "ty": "r",
                  "val": null
                },
                {
                  "id": "wp",
                  "ty": "r",
                  "val": null
                }
              ]
            }
          ]
        },
        {
          "timePeriods": [
            "3M",
            "6M"
          ],
          "name": "Tesco Plc",
          "measures": [
            {
              "tp": "3M",
              "measures": [
                {
                  "id": "rp",
                  "ty": "r",
                  "val": 21.9
                },
                {
                  "id": "wp",
                  "ty": "r",
                  "val": 33.58
                }
              ]
            },
            {
              "tp": "6M",
              "measures": [
                {
                  "id": "rp",
                  "ty": "r",
                  "val": 38.69
                },
                {
                  "id": "wp",
                  "ty": "r",
                  "val": 48.91
                }
              ]
            }
          ]
        }
      ]
    }
  }
}


Annotated Representations (XML)

Legend

Include Child Segments

<?xml version="1.0" encoding="utf-8"?>
<segmentsTreeNode xmlns="http://statpro.com/2012/Revolution">
  <link rel="service"
        href="..."
        type="application/vnd.statpro.revolution.api.service+xml" />
  <link rel="portfolios-query"
        href="...?$filter={filter}&amp;$orderby={orderby}&amp;$skip={skip}&amp;$top={top}&amp;includePublishedPortfolios=false&amp;portfolioClassifierCode="
        type="application/vnd.statpro.revolution.api.portfolios+xml" />
  <link rel="self"
        href="..."
        type="application/vnd.statpro.revolution.api.segments-tree-node+xml" />
  <link rel="segments-tree-root-node-query"
        href="...?timePeriods={timePeriodsList}&amp;include={dataToInclude}&amp;measures={measuresList}&amp;includeMeasuresFor={measuresFor}&amp;$filter={filter}&amp;$orderby={orderby}&amp;$skip={skip}&amp;$top={top}"
        type="application/vnd.statpro.revolution.api.segments-tree-node+xml" />
  <link rel="time-series-query"
        href="...?measures={measuresList}&amp;startDate={startDate}&amp;endDate={endDate}&amp;seriesType={seriesType}"
        type="application/vnd.statpro.revolution.api.time-series+xml" />
  <treeLevel>
    <this>1</this>
    <count>2</count>
  </treeLevel>
  <segment timePeriods="3M,6M">
    <name>TOTAL</name>
    <measures>
      <periodGroup tp="3M">
        <m id="rp" ty="r">3</m>
        <m id="wp" ty="r">4.6</m>
      </periodGroup>
      <periodGroup tp="6M">
        <m id="rp" ty="r">5.3</m>
        <m id="wp" ty="r">6.7</m>
      </periodGroup>
    </measures>
  </segment>
  <childSegments>
    <classifier>
      <name>GICS Sector</name>
    </classifier>
    <paging>
      <link rel="next"
            href="..."
            type="application/vnd.statpro.revolution.api.segments-tree-node+xml" />
      <link rel="prev"
            href="..."
            type="application/vnd.statpro.revolution.api.segments-tree-node+xml" />
      <link rel="first"
            href="..."
            type="application/vnd.statpro.revolution.api.segments-tree-node+xml" />
      <link rel="last"
            href="..."
            type="application/vnd.statpro.revolution.api.segments-tree-node+xml" />
      <pageNumber>2</pageNumber>
      <pageCount>5</pageCount>
    </paging>
    <segment timePeriods="3M,6M">
      <link rel="self"
            href="..."
            type="application/vnd.statpro.revolution.api.segments-tree-node+xml" />
      <link rel="time-series-query"
            href="...?measures={measuresList}&amp;startDate={startDate}&amp;endDate={endDate}&amp;seriesType={seriesType}"
            type="application/vnd.statpro.revolution.api.time-series+xml" />
      <name>Consumer Staples</name>
      <measures>
        <periodGroup tp="3M">
          <m id="rp" ty="r">13.5</m>
          <m id="wp" ty="r">20.7</m>
        </periodGroup>
        <periodGroup tp="6M">
          <m id="rp" ty="r" />
          <m id="wp" ty="r" />
        </periodGroup>
      </measures>
    </segment>
    <segment timePeriods="3M,6M">
      <link rel="self"
            href="..."
            type="application/vnd.statpro.revolution.api.segments-tree-node+xml" />
      <link rel="time-series-query"
            href="...?measures={measuresList}&amp;startDate={startDate}&amp;endDate={endDate}&amp;seriesType={seriesType}"
            type="application/vnd.statpro.revolution.api.time-series+xml" />
      <name>Energy</name>
      <measures>
        <periodGroup tp="3M">
          <m id="rp" ty="r">21.9</m>
          <m id="wp" ty="r">33.58</m>
        </periodGroup>
        <periodGroup tp="6M">
          <m id="rp" ty="r">38.69</m>
          <m id="wp" ty="r">48.91</m>
        </periodGroup>
      </measures>
    </segment>
  </childSegments>
</segmentsTreeNode>

Include Securities

<?xml version="1.0" encoding="utf-8"?>
<segmentsTreeNode xmlns="http://statpro.com/2012/Revolution">
  <link rel="service"
        href="..."
        type="application/vnd.statpro.revolution.api.service+xml" />
  <link rel="portfolios-query"
        href="...?$filter={filter}&amp;$orderby={orderby}&amp;$skip={skip}&amp;$top={top}&amp;includePublishedPortfolios=false&amp;portfolioClassifierCode="
        type="application/vnd.statpro.revolution.api.portfolios+xml" />
  <link rel="self"
        href="..."
        type="application/vnd.statpro.revolution.api.segments-tree-node+xml" />
  <link rel="up"
        href="..."
        type="application/vnd.statpro.revolution.api.segments-tree-node+xml" />
  <link rel="segments-tree-root-node-query"
        href="...?timePeriods={timePeriodsList}&amp;include={dataToInclude}&amp;measures={measuresList}&amp;includeMeasuresFor={measuresFor}&amp;$filter={filter}&amp;$orderby={orderby}&amp;$skip={skip}&amp;$top={top}"
        type="application/vnd.statpro.revolution.api.segments-tree-node+xml" />
  <link rel="time-series-query"
        href="...?measures={measuresList}&amp;startDate={startDate}&amp;endDate={endDate}&amp;seriesType={seriesType}"
        type="application/vnd.statpro.revolution.api.time-series+xml" />
  <treeLevel>
    <this>2</this>
    <count>2</count>
  </treeLevel>
  <segment timePeriods="3M,6M">
    <name>Consumer Staples</name>
    <measures>
      <periodGroup tp="3M">
        <m id="rp" ty="r">3</m>
        <m id="wp" ty="r">4.6</m>
      </periodGroup>
      <periodGroup tp="6M">
        <m id="rp" ty="r">5.3</m>
        <m id="wp" ty="r">6.7</m>
      </periodGroup>
    </measures>
  </segment>
  <securities>
    <paging>
      <link rel="next"
            href="..."
            type="application/vnd.statpro.revolution.api.segments-tree-node+xml" />
      <link rel="prev"
            href="..."
            type="application/vnd.statpro.revolution.api.segments-tree-node+xml" />
      <link rel="first"
            href="..."
            type="application/vnd.statpro.revolution.api.segments-tree-node+xml" />
      <link rel="last"
            href="..."
            type="application/vnd.statpro.revolution.api.segments-tree-node+xml" />
      <pageNumber>2</pageNumber>
      <pageCount>5</pageCount>
    </paging>
    <security timePeriods="3M,6M">
      <name>Diageo Plc</name>
      <measures>
        <periodGroup tp="3M">
          <m id="rp" ty="r">13.5</m>
          <m id="wp" ty="r">20.7</m>
        </periodGroup>
        <periodGroup tp="6M">
          <m id="rp" ty="r" />
          <m id="wp" ty="r" />
        </periodGroup>
      </measures>
    </security>
    <security timePeriods="3M,6M">
      <name>Tesco Plc</name>
      <measures>
        <periodGroup tp="3M">
          <m id="rp" ty="r">21.9</m>
          <m id="wp" ty="r">33.58</m>
        </periodGroup>
        <periodGroup tp="6M">
          <m id="rp" ty="r">38.69</m>
          <m id="wp" ty="r">48.91</m>
        </periodGroup>
      </measures>
    </security>
  </securities>
</segmentsTreeNode>


Last updated: September 2014


To Top