StatPro Revolution Web API
The multiple-ocp-time-series-query Link Relation
multiple-ocp-time-series-query link relation identifies a link that targets the Multiple OCP Time Series resource, which is accessed using the HTTP POST method. The Multiple OCP Time Series resource is able to provide Overall Custom Period (OCP) compounded time series data for multiple segments, multiple time periods and (potentially) a large number of measures. (The Time Series resource, by contrast, provides data for only one segment, one time period and a limited number of measures - in any one request.) When retrieving multiple OCP data, a client application must formulate a query for the data that the web service is to provide. This is done by specifying an XML document in the entity body of the POSTed request.
Compared to the normal time series link relation + resource, the Multiple OCP variants allow a caller to:-
- get only Overall Custom Period time series; the other series types aren't supported
- get time series for one or more segments
- get time series for one or more time periods (i.e. start/end date pairs), per segment
- vary the number of time periods that are requested per segment
- vary the order in which time periods are requested per segment
- get values for any number of time series measures.
Thus the Multiple OCP Time Series resource can be seen as an optimized, high-performance version of the normal Time Series resource, in which the series type is constrained to be Overall Custom Period, but which allows the caller to greatly reduce the number of requests it has to make to get the same data. (Batching-up requests for multiple time periods for any one segment in just one request also allows the web service to operate more efficiently, in that there will be fewer calls made to the underlying database to get the raw time series data that is needed for compounding.)
Fair Usage Policy Implications
Despite the relatively small size of its output resource representations (in XML or JSON), a very large amount of data extraction and data processing may be performed by the server to produce multiple Overall Custom Period numbers. For this reason, the Multiple OCP Time Series resource is considered to be an exceptional case with respect to the Web API's Fair Usage Policy.
Whereas a request for most resources is counted as being just one request by the Fair Usage Policy, a single request for the Multiple OCP Time Series resource may be counted as being more than one request. The actual number depends on the requested numbers of measures and segments (but not time periods), and is given by this formula:-
num_requests = ceiling((num_measures + num_segments) / 100)
For example, if the number of requested measures is 147, and the number of requested segments is 275, the result is:-
ceiling((147 + 275) / 100) = ceiling(4.22) = 5
which means that the single request for Multiple OCP Time Series data would be counted as 5 requests by the Fair Usage Policy.
This is far more efficient - and has far less impact on Fair Usage - than requesting the Time Series resource multiple times to get the same data.
Querying for Data
To be able to query for data, the caller must know:-
- the start date and end date of the analysis's results data
- the segments that exist in the analysis's results data, and their identifiers
- the list of supported time series measures (and knowledge of which of those are compoundable).
The start date and end date of the analysis's results data is given by the start and end dates of its
Earliest time period. Note that an analysis that has finished and thus has results data always has an
Earliest time period. See the Portfolio Analysis resource for more details. Armed with the date range of the results data, the calling application can formulate the number of time periods that it wishes to query for, and the date range of each. Note that, unlike querying for data from the normal Time Series resource, the start/end dates for each time period must be stated (i.e. neither can be omitted).
Segments and their identifiers are exposed the Whole Segments Tree resource, which is another optimized, high-performance resource that works hand-in-hand with the Multiple OCP Time Series resource. (The Segments Tree Node resource exposes segments, but not their identifiers.) The Multiple OCP Time Series resource also exposes segments and their identifiers, but only for those segments that were requested in the first place.
See the list of supported time series measures for details of what measures can be requested. This is the exact same list that is provided for the normal Time Series resource. Overall Custom Period data is compounded, and so it only makes sense to specify those measures that are compoundable in the query (but it's not an error if a non-compoundable measure is specified; the returned value for the measure will simply be null).
A query is expressed in XML form, and must be included in the entity body of the POSTed request to this link relation's identified URI. A query's XML looks like this:-
<multipleOcpRequest> <measures>Rp,RelR,Wp</measures> <timePeriods> <timePeriod> <name>2008</name> <start>2008-01-01</start> <end>2008-12-31</end> </timePeriod> <timePeriod> <name>2009</name> <start>2009-01-01</start> <end>2009-12-31</end> </timePeriod> </timePeriods> <segments> <segment> <id>1</id> <periods>2008,2009</periods> </segment> <segment> <id>2</id> <periods>2008,2009</periods> </segment> </segments> </multipleOcpRequest>
In the example above, there is a query for three measures:
Relative Return ([CUR]) and
Weight Mean. Two time periods have been defined, with names
2009; their date ranges encompass the whole of years 2008 and 2009. (The assumption is that the calling application has ascertained that the analysis's results data contains data for those years.) Two segments are requested, with identifiers 1 and 2, which have presumably been read from a previously-obtained representation of the Whole Segments Tree resource for the same analysis. Both segments require OCP time series for both of the previously-defined time periods. Thus we expect the returned resource representation to contain four separate OCP time series, each containing three measure values.
The details and requirements of the query's XML are as follows:-
- The entity body of the request must be set to the XML document in string form. It is a bad request is the entity body is empty, doesn't contain XML, or contains invalid XML.
- Calling applications must ensure that the specified XML a) conforms to the published schema document (XSD) and b) is semantically valid.
- There must be at least one measure id, one time period and one segment in the query.
- Measure identifiers must be comma, semicolon or space delimited.
- Measure identifiers must be valid - i.e. supported for resources that return time series; ideally they should also compoundable. See the list of supported time series measures for details.
- Measure identifiers don't have to be case-correct; e.g. "rp" and "Rp" refer to the same measure. Note that only the case-correct versions will be included in the returned resource representation for a successful request.
- Time period names can only include the following characters: alphanumeric, minus sign, underscore.
- Time periods names cannot be empty, and cannot exceed 20 characters.
- Time period names are treated case-sensitively.
- Time period names must be unique (i.e. no repeats).
- Time period names, as defined by the query, are utilized in the returned resource representation for a successful request.
- A time period must have explicitly-stated start and end dates, both in ISO 8601 date format. The end date must come after the start date.
- A defined time period doesn't have to be referenced by any segment in the query.
- Time periods can have overlapping date ranges.
- A time period's start date can come before the start of any data in the analysis's results; similarly the end date can come after the end of the analysis's results data. Note that, as long as Overall Custom Period measure values are returned for a particular segment and time period, the returned resource representation will convey the real start/end dates for that time period (in the context of that segment).
- The returned start/end dates for a particular time period may not be exactly as requested, and may also vary from segment to segment.
- For any one segment in the query, its identifier and one or more time period names must be specified.
- Segment identifiers must be positive (greater than or equal to zero).
- Segment identifiers must be unique (no repeats).
- Segment identifiers must be valid (i.e. they must refer to existing segments), and are typically provided by a previous request for the Whole Segments Tree resource for the same analysis.
- A segment must reference at least one previously-defined time period by its name (which is treated case-sensitively).
- A segment doesn't have to reference all of the defined time periods.
- Different segments can reference different time periods, or in a different order, etc. For any one segment, the order in which time periods' data is returned is dependent on that segment's time periods request order.
- The order in which time periods are defined in the
<timePeriods>...</timePeriods>element is not significant.
See the schema document (XSD) for the query for further details.
- Initial Version - September 2014
Last updated: September 2014