StatPro Revolution Web API


The Interactive Statistics Analysis Resource


Overview

The Interactive Statistics Analysis resource is identical to the Interactive Risk Analysis resource except for the set of error messages that may be returned. The resource represents a set of ex-post risk, performance and raw data measures that have been calculated interactively on-the-fly given a user provided query. A single Interactive Statistics Analysis query comprises a request for one or more tables of statistics results and each table representing a collection of measures calculated at total level.

The key to understanding the Interactive Statistics Analysis 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 interactive-statistics-analysis-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.


Calculation notes

Pre-calculated statistics may in certain circumstances exhibit differences with respect to calculated statistics:

  • The set of unit prices used under pre-calculated statistics is limited to the set of holdings dates. If there are fewer holdings dates than unit prices dates, this might result in the two approaches using slightly different sets of dates, and thus unit prices, in the calculation.


Media types

The Interactive Statistics Analysis resource is exposed via XML and JSON representations, which have the following media type names:-

application/vnd.statpro.revolution.api.interactive-statistics-analysis+json

application/vnd.statpro.revolution.api.interactive-statistics-analysis+xml

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

Content-Type: application/vnd.statpro.revolution.api.interactive-statistics-analysis+json; charset=utf-8

Content-Type: application/vnd.statpro.revolution.api.interactive-statistics-analysis+xml; charset=utf-8


Related resources

The Interactive Statistics Analysis resource always links to the Service and Porfolios resources (and to itself). These resources are exposed via the following link relations :-

  • self
  • service
  • portfolios-query

The self link relation identifies the Interactive Statistics Analysis resource link for the same analysis. Note that, unlike almost all other self links, the original query data is not contained in the link's URI. For a new request, the query data must be included in the POSTed entity body.

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.


Processing Errors/Messages

Within a single Interactive Statistics Analysis resource there can exist zero or more informational messages or errors relating to issues that have occurred in the processing of the interactive statistics query. Most issues with the query are picked up by the validation of the well-formedness of the Xml and by the schema validation that takes place when pre-processing the request. In such circumstances we have the following error response codes that can be returned:

895 - InteractiveStatisticsQueryRequestDataMissing: Occurs when no interactive statistics query is submitted,

896 - InteractiveStatisticsQueryRequestDataNotXml: Occurs when the interactive statistics query submitted is not well-formed Xml.

897 - InteractiveStatisticsQueryRequestFailedSchemaValidation: Occurs when the interactive statistics query submitted doesn't conform to the published schema document (XSD).

839 - PortfolioNotFound: Occurs when an attempt is made to access a portfolio that cannot be found.

840 - AnalysisNotFound: Occurs when an invalid analysis code is specified for the portfolio.

Assuming the interactive statistics query has passed all of these validations then it is still possible for messages or errors to be produced. These will be evident by the existence of messages returned in the resource representation. Messages can exist at the top-level underneath the interactiveStatisticsAnalysis element/property or under a specific table element/property. The ones at the top-level affect all tables in the query, whereas the ones under a specific table relate just to the associated table. Associated with any message or error will be a unique identifier and the message text.

Message 'class' Attribute

The class attribute of a message is related to the client action that is recommended in response to the message. This is of particular value in responding appropriately to the large and growing number of possible messages, as it means that specific responses don't need to be developed for each new specific message (see id attribute).

'class' Attribute Meaning Client Action
ReasonValueIsNotApplicableThe result is benignly null. As the issue is benign, it does not need to be solved and is not an error. Example: When the measure 'Maximum Loss' is null, the reason provided is 'The value is N/A because there is no loss.').No client action is expected. As a result, it is appropriate to hide such exceptions from the user until the user requires greater understanding of the result set.
BusinessWarningThe result is not null, however a functional warning is applicable for this result.Administrative awareness is required so as to determine whether further steps need to be taken.
QueryValidationErrorThe query is invalid, due to a schema validation error of the XML query, or due to invalidity of one of the values within the query.Client developer input is required to fix the query.
BusinessCriticalExceptionThe result is null due to an unexpected error of functional rather than technical origin. This is often related to configuration or data.Client administrative input is required to fix the issue.
TechnicalExceptionThe result is null due to an unexpected error of technical rather than functional origin.StatPro technical support is required to resolve the issue.

Message 'id' Attribute

The value of the id attribute is unique to each message. Here is a list of the possible messages:

'id' Attribute Message 'dataCsv' Attribute Fields
BadCalendarThe value is N/A because the Calendar has no dates.
Benchmark1UndefinedThe value is N/A because Benchmark1 is not specified for {performerName}.performerId
Benchmark2UndefinedThe value is N/A because Benchmark2 is not specified for {performerName}.performerId
Benchmark3UndefinedThe value is N/A because Benchmark3 is not specified for {performerName}.performerId
Benchmark4UndefinedThe value is N/A because Benchmark4 is not specified for {performerName}.performerId
CalendarMaxDateExceededThe period was N/A as a date later than the calendar's latest date was requested.calendarMaxDate
CalendarMinDateExceededThe period was N/A as a date earlier than the calendar's earliest date was requested.calendarMinDate
CurrencyNotFoundCurrency not found.currencyId
DailyFrequencyNotSupportedThe value is N/A because Daily frequency is not supported by the this statistic
DuplicateColumnNameThe columnNode name '{0}' is duplicated.columnName
DuplicateTableNameA duplicate table name has been specified.
EndNotCalendarAlignedThe value is N/A because the statistic requires a {frequencyAdjective} History, and the end date is not a {frequencyAdjective} date.frequencyAdjective
IllegalPartialPeriodThe value is N/A because the date range is a partial period and partial periods are not allowed
InsufficientGainsThe Bull Statistic is N/A because there are too few gains during the period. (Ex-Post Risk Statistics require a minimum of {minResultsForStdDev} {frequencyAdjective} samples).minResultsForStdDev, frequencyAdjective
InsufficientLossesThe Bear Statistic is N/A because there are too few losses during the period. (Ex-Post Risk Statistics require a minimum of {minResultsForStdDev} {frequencyAdjective} samples).minResultsForStdDev, frequencyAdjective
InsufficientSamplesThe Risk Statistic is N/A because the calculation period is too short (Ex-Post Risk Statistics require a minimum of {minResultsForStdDev} {frequencyAdjective} samples).minResultsForStdDev, frequencyAdjective
InvalidColumnNameThe table filter / orderBy / skip / top could not be applied, as the name of columnNode '{0}' does not comply with the OData field name specification for TSimpleIdentifier, which is based on the regular expression: "[\p{L}\p{Nl}_][\p{L}\p{Nl}\p{Nd}\p{Mn}\p{Mc}\p{Pc}\p{Cf}]{0,}".columnName
InvalidMeasureIdThe measureId provided is invalid.measureId
InvalidPeriodBaseIdThe period baseId '{baseId}' is not recognised. For a list of recognised period baseIds, see the Web API resource for 'Periods for use with Interactive Statistics;.baseId
LessThanYearThe annualised statistic is N/A because the requested period is < 1 year.
MeasureScopeNaThe measure '{seedMeasure}' cannot be interpreted and is not valid at levels higher than Table level.seedMeasure
MissingBenchmarkPerfSeriesThe value is N/A as benchmark '{performerName}' has no performance series.performerId
MissingPortfolioInternalMvSeriesThe value of the 'Internal Market Value' measure is N / A as the portfolio has no internal Market Value series.performerId
MissingPortfolioPerfSeriesThe value is N/A as portfolio '{performerName}' has no performance series for share class '{shareType}' with return type '{returnType}'.performerId, shareClass, returnType
MissingPortfolioQuantitySeriesThe value of the 'Units' measure is N/A as the portfolio has no portfolio-level 'Quantity' time series.performerId
MissingPortfolioTotalAssetsSeriesThe value of the 'External Market Value' measure is N/A as the portfolio has no 'Total Assets' series.performerId
MissingValuationsThe value is N/A because the benchmark does not have valuations for all dates of the main entity.
MultipleParametersInThisNodeCreateChildrenOnly one parameter in a node may create children.
NaForRiskFreeThe measure is N/A as it never applies to risk free rates.
NoBenchmarkGainsThe Bull Return is N/A because there are no benchmark gains during the period.
NoBenchmarkLossesThe Bear Return is N/A because there are no benchmark losses during the period.
NoBmarkThe value is N/A because no benchmark is set for {performerName}.performerId
NoDateThe value is N/A because the start or end date is not specified.
NoHighestFrequencyThe value is N/A because a contiguous set of quarterly, monthly or weekly returns does not exist for the period.
NoHistoryThe value is N/A because no performance history is available for {performerName}.performerId
NoLossThe value is N/A because there is no loss.
NoPerfThisDateThe value is N/A because no performance history is present for the date requested for {performerName}. A calendar, if applied, may also cause certain dates to be ignored.performerId
NoPerfCalendarClosedThisDateThe value is N/A because the calendar is closed for the requested date and with the requested date tolerance.
NoRiskFreeThe value is N/A because no risk free series is specified for {performerName}.performerId
NoValueThisDateThe value was N/A as no history is present for the requested date.performerId
NotANumberThe value is N/A as it is infinite or not a number.
NotRecoveredThe value is N/A because a full recovery did not occur following the maximum loss.
OutsideThisBlockThe value is N/A because the request date is outside of the current Performance Block.
PartialPeriodicDataThe Performance Statistic is N/A because the Performance History is not a complete {frequencyAdjective} series for the specified period for {performerName}.frequencyAdjective, performerId
PerformerNotFoundThe value is N/A because {performerName} was not found.performerId
PeriodHiddenUponRuleThe period is configured to be not applicable for this overall reporting period.
ReturnTypeNotFoundThe value is N/A as {performerName} doesn't support return type '{returnType}'.performerId, returnType
RiskFreeUndefinedThe value is N/A because a Risk Free rate was not specified.
ShareClassNotFoundThe value is N/A as {performerName} doesn't support share class '{shareType}'.performerId, shareClass
StartAfterEndThe period is N/A as the Start Date is after the End Date.
StartNotBeforeEndThe value is N/A because the Start Date is not before the End Date.
TestedStatNotSignificantThe value is N/A because the Tested Statistic is outside its range of significance.
TimeoutThe result could not be obtained due to a Timeout. Please wait a moment and try again.
TotalMeasureInTableWithoutTotalTotal-Level measure requested in table not displaying Total Level. Please delete the measure, or add total-level.
UnchainablePeriodThe value is N/A because the Peformance History for {performerName} forms two or more unchainable blocks for the specified period.performerId
UnexpectedErrorAn unexpected error occurred processing the request (Code: {0}, Class: {1}).errorCode, errorClass
UnitPriceNaForInternalReturnThe value is N/A as the Unit Price is always N/A when Return Type is 'Internal'.
UnitPriceNaForSystemBenchmarksThe value is N/A as the Unit Price for System Benchmarks may not be publicly distributed.
UnlicensedBenchmarkThe associated benchmark is unlicensed for the portfolio owner.
UnsupportedFeatureMultiRowNodeFilterThe rowNode Filter, Orderby, Skip and Top feature does not yet support tables with more than one rowNode. Please contact StatPro Support to register your interest in extending this feature if you require it. Internal ref: SAAS-18219.
UnsupportedFilterOrderbyTableTypeThe rowfilter is not yet supported for table type '{0}'. Please contact StatPro Support to request its addition.
UnsupportedMeasureDataTypeThe rowfilter could not be applied to column {0} as it has an unsupported data type.

Message 'dataCsv' Attribute

The dataCsv attribute contains a CSV encoded and escaped array of data items. The selection of data items returned depends on the message id.

Message 'columns' Attribute

The columns attribute contains a comma-delimited list of output column positions (as opposed to column node positions) to which the message applies.


Update history

  • Added rowNode attributes filter, orderby, skip and top. Added message ids "DuplicateColumnName", "DuplicateTableName" and "InvalidColumnName" - August 2017
  • Added message ids "NoPerfCalendarClosedThisDate" and "UnitPriceNaForInternalReturn" - March 2017
  • Initial Version - December 2016

Annotated Representation (JSON)

Legend

{
  "interactiveStatisticsAnalysis": {
    "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.interactive-statistics-analysis+json"
      }
    },
    "messages": [
      {
        "class": "QueryValidationError",
        "id": "DuplicateTableName",
        "message": "A duplicate table name has been specified.  Ensure all table names are unique."
      }
    ],
    "tables": [
      {
        "name": "StandardPeriods",
        "messages": [],
        "resultsCsv": [
          "Portfolio,Benchmark,Relative",
          "1 Day,-0.6678746615784,-0.5327020591042,-0.1351726024742",
          "1 Week,0.40589866635,0.525088035798,-0.119189369448",
          "1 Month,-3.515129080366,-3.0849610298809,-0.4301680504851",
          "3 Months,-5.2508857969226,-5.7262166087696,0.475330811847",
          "6 Months,-1.2055363970878,-0.182654201516,-1.0228821955718",
          "1 Year,-1.2343105001277,0.253985715552,-1.4882962156797",
          "2 Years,23.137847726655,26.079725072551,-2.941877345896",
          "3 Years,7.61807983509,8.685458718934,-1.067378883844"
        ]
      },
      {
        "name": "TriangleMatrix",
        "messages": [
          {
            "class": "ReasonValueIsNotApplicable",
            "id": "NoPerfThisDate",
            "columns": "C3,C4",
            "dataCsv": "eef04358-5f84-4fe0-973a-2a27bafd15de",
            "message": "The value is N/A because no performance history is present for the date requested for performer 'European  Equity'."
          }
        ],
        "resultsCsv": [
          ",1 Year,2 Years,3 Years,4 Years,5 Years,6 Years,7 Years,8 Years,9 Years,10 Years",
          "2017,5.534545061244,17.536121640866,27.324186334399,47.462570408414,67.406726781046,88.388594599421,86.080921254075,122.880483513992,170.666770360442,22.667536192764",
          "2016,11.372178249934,20.646927752908,39.729195139694,58.627420702763,78.508937040563,76.322284941,111.191968833191,156.472200835631,16.234486178509,144.76103525784",
          "2015,8.327707735194,25.461490773865,42.430024441815,60.281445371361,58.318071633033,89.627223020858,130.283904710988,4.3658191884,119.768562583524,",
          "2014,15.816621062964,31.480696323773,47.959786764036,46.147347657388,75.04960363825,112.580797217564,-3.6573178087351,102.873823491904,,",
          "2013,13.524894023883,27.753499805176,26.188578388877,51.143766785497,83.549472663335,-16.814459524866,75.168142214761,,,",
          "2012,12.533467574345,11.154984529058,33.137113304593,61.682135219364,-26.724846395687,54.299322382903,,,,",
          "2011,-1.2249538515072,18.3089050523,43.674711803001,-34.885900893524,37.114163198575,,,,,",
          "2010,19.776107089276,45.456486638345,-34.0783916126072,38.814577714746,,,,,,",
          "2009,21.440319086283,-44.9626390526637,15.895048760668,,,,,,,",
          "2008,-54.679499064695,-4.5662514454328,,,,,,,,"
        ]
      },
      {
        "name": "CalendarQuarterMatrix",
        "messages": [],
        "resultsCsv": [
          ",Q1,Q2,Q3,Q4",
          "2017,2.652630252557,-1.9048027295008,1.898438375553,2.851182057208",
          "2016,-6.6537885857309,4.520655546473,2.665599294036,11.186726987058",
          "2015,11.277607555598,-2.3874900826403,-7.5391180403604,7.861948592685",
          "2014,0.486868016429,4.5671583433,6.694089823461,3.306086819795",
          "2013,6.337978107696,-0.2384797372276,1.400323816027,5.535921377642",
          "2012,7.498160477342,-0.0089177473119,5.943004575824,-1.1794846962352",
          "2011,-1.3255054015782,-2.6705017036103,-6.731453334844,10.271336004747",
          "2010,13.293664994639,-1.7914098903928,-0.19233571781,7.857710907296",
          "2009,-7.1439859049119,9.269052678321,13.331498849849,5.610002251899",
          "2008,-33.1552118799571,17.34945373932,-23.8600648097478,-24.1189074337894",
          "2007,8.483663454987,29.466100742149,19.422609237729,25.545258342656"
        ]
      }
    ]
  }
}


Annotated Representation (XML)

Legend

<?xml version="1.0" encoding="utf-8"?>
<interactiveStatisticsAnalysis 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.interactive-statistics-analysis+xml" />
  <messages>
    <message class="QueryValidationError" id="DuplicateTableName">A duplicate table name has been specified.  Ensure all table names are unique.</message>
  </messages>
  <tables>
    <table name="StandardPeriods">
      <messages />
      <resultsCsv>Portfolio,Benchmark,Relative
1 Day,-0.6678746615784,-0.5327020591042,-0.1351726024742
1 Week,0.40589866635,0.525088035798,-0.119189369448
1 Month,-3.515129080366,-3.0849610298809,-0.4301680504851
3 Months,-5.2508857969226,-5.7262166087696,0.475330811847
6 Months,-1.2055363970878,-0.182654201516,-1.0228821955718
1 Year,-1.2343105001277,0.253985715552,-1.4882962156797
2 Years,23.137847726655,26.079725072551,-2.941877345896
3 Years,7.61807983509,8.685458718934,-1.067378883844</resultsCsv>
    </table>
    <table name="TriangleMatrix">
      <messages>
        <message class="ReasonValueIsNotApplicable" id="NoPerfThisDate" columns="C3,C4" dataCsv="eef04358-5f84-4fe0-973a-2a27bafd15de">The value is N/A because no performance history is present for the date requested for performer 'European  Equity'.</message>
      </messages>
      <resultsCsv>,1 Year,2 Years,3 Years,4 Years,5 Years,6 Years,7 Years,8 Years,9 Years,10 Years
2017,5.534545061244,17.536121640866,27.324186334399,47.462570408414,67.406726781046,88.388594599421,86.080921254075,122.880483513992,170.666770360442,22.667536192764
2016,11.372178249934,20.646927752908,39.729195139694,58.627420702763,78.508937040563,76.322284941,111.191968833191,156.472200835631,16.234486178509,144.76103525784
2015,8.327707735194,25.461490773865,42.430024441815,60.281445371361,58.318071633033,89.627223020858,130.283904710988,4.3658191884,119.768562583524,
2014,15.816621062964,31.480696323773,47.959786764036,46.147347657388,75.04960363825,112.580797217564,-3.6573178087351,102.873823491904,,
2013,13.524894023883,27.753499805176,26.188578388877,51.143766785497,83.549472663335,-16.814459524866,75.168142214761,,,
2012,12.533467574345,11.154984529058,33.137113304593,61.682135219364,-26.724846395687,54.299322382903,,,,
2011,-1.2249538515072,18.3089050523,43.674711803001,-34.885900893524,37.114163198575,,,,,
2010,19.776107089276,45.456486638345,-34.0783916126072,38.814577714746,,,,,,
2009,21.440319086283,-44.9626390526637,15.895048760668,,,,,,,
2008,-54.679499064695,-4.5662514454328,,,,,,,,</resultsCsv>
    </table>
    <table name="CalendarQuarterMatrix">
      <messages />
      <resultsCsv>,Q1,Q2,Q3,Q4
2017,2.652630252557,-1.9048027295008,1.898438375553,2.851182057208
2016,-6.6537885857309,4.520655546473,2.665599294036,11.186726987058
2015,11.277607555598,-2.3874900826403,-7.5391180403604,7.861948592685
2014,0.486868016429,4.5671583433,6.694089823461,3.306086819795
2013,6.337978107696,-0.2384797372276,1.400323816027,5.535921377642
2012,7.498160477342,-0.0089177473119,5.943004575824,-1.1794846962352
2011,-1.3255054015782,-2.6705017036103,-6.731453334844,10.271336004747
2010,13.293664994639,-1.7914098903928,-0.19233571781,7.857710907296
2009,-7.1439859049119,9.269052678321,13.331498849849,5.610002251899
2008,-33.1552118799571,17.34945373932,-23.8600648097478,-24.1189074337894
2007,8.483663454987,29.466100742149,19.422609237729,25.545258342656</resultsCsv>
    </table>
  </tables>
</interactiveStatisticsAnalysis>


Last updated: August 2017


To Top