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:-
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.)
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.
To be able to query for data, the caller must know:-
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:-
<timePeriods>...</timePeriods>element is not significant.
See the schema document (XSD) for the query for further details.
Last updated: September 2014