Developers »
Time Series API » Here
Programmer's guide for the Time Series API
Important: This API version has been replaced by
API version 2. Please migrate to the newer version. It offers better integration with the Lokad services and provides access to new features that improve forecasting results.
API version 1 will still be kept for the backward compatibility.
This document contains programmer's insights about the
TimeSeries API. It focuses on
Why? questions as opposed to
How to? questions. This document should help you to understand how this API is organized and why we did it that way. In particular, this document is not specific of client-side technology used to call our API.
Deprecated elements and future evolutions
Maintaining backward compatibility is the number one priority when the Lokad team is improving the
TimeSeries API. Yet, this comes at a cost: a few less-than-useful features have not been removed, precisely to avoid breaking 3rd party applications that rely on our API.
Accounts and SOAP headers
All calls to our API are authenticated through a SOAP Header. This header contains the same username and the password than the one used to log into the
Lokad Web Application. Each method carries its own authentication tokens, as a consequence there is no notion of
authenticated session.
Important: UserName and
Password must have the same namespace as
AuthHeader due to the special handling by ASP.NET Web Services.
SOAP request might fail if it has authentication header like the one below:
<ns:AuthHeader>
<UserName>foo@example.com</UserName>
<Password>password</Password>
</ns:AuthHeader>
Where
ns is some namespace.
You can correct this XML to make it work:
<ns:AuthHeader>
<ns:UserName>foo@example.com</ns:UserName>
<ns:Password>password</ns:Password>
</ns:AuthHeader>
Tip: The API provides a web method named
IsAuthenticated to check whether the SOAP header is correctly setup.
It is possible to check that the web method call had the intended effect directly from the Lokad Web Application (through the panels
Check Data and
Check Forecasts).
Revenue sharing
We propose a
revenue sharing program for partners. In order to track affiliate customers, you need to call once the web method
SetPartner with your Partner ID identifier and the authentication tokens of your customers.
Affiliate customers appear in the dashboard of the
Partner Web Application.
Time-series
The basic piece of data manipulated by the API is time-series, i.e. a list of time-value pairs. Time-series are used to represent the past, i.e. historical data, but also the forecasts.
We suggest to maintain the list sorted according to
datetime values because, it's the
canonical representation of time-series. When returned by Lokad, time-series will always be sorted that way.
Deprecated elements: the
TimeSerie object contains two meta-data, namely
UnitName and
UtcOffset. Those two elements are deprecated. Basically, both fields are only used for reporting within the Lokad Web Application. You suggest to leave the
UnitName empty and to set
UtcOffset to zero.
Key web methods to manipulate time-series:
AddSerie(s)DeleteSerie(s)UpdateSerie(s)
Forecasting tasks
Each time-series can be associated to a
forecasting task, simply named
Task in our API. Those tasks represent the definition of the expected forecast. The most important settings are
Period: the frequency in the forecasted time-series i.e. 1 point per month, per day, per hour, ...FuturePeriods: the number of points to be returned in the forecasted time-series.PeriodStart: a poorly named settings, more details can be found on this blog post. Unless you know what you are doing, we suggest you use 2001-01-01 as value for PeriodStart.
Elements not used yet: the
Aggregator field must be set to the value
Sum. Although we have started to work a little bit with other aggregators, the
Sum is the only aggregator that could be used in production for now. This situation might evolve in the future, but we strongly suggest to stick with
Sum for now.
Deprecated elements: PastPeriods, contrary to its counterpart
FuturePeriods, has not effect on the forecasts. This parameters only impact reporting settings within the Lokad Web Application. We suggest to set
PastPeriods at zero.
Key web methods to manipulate forecasting tasks:
AddTask(s)DeleteTask(s)UpdateTask(s)
Compound calls and performance
The main performance issue with web services is
latency: each round trip to our web services takes usually more than 100ms even if there is very little data transmitted. Thus, in order to improve performance, we have introduced
compound calls that can create/update/delete multiple items within a single call.
| Standard call | Compound call |
|---|
AddSerie | AddSeries |
AddTask | AddTasks |
DeleteSerie | DeleteSeries |
DeleteTask | DeleteTasks |
| ... | ... |
Whenever you manipulate a large number of time-series (let's say more than 50), we strongly suggest to use compound calls to reduce the overall latency.
Call capacity limitations
The amount of data transferred to our web services should not exceed certain limits for each web method call. For example, through
AddSeries, you cannot add more than 500 time-series at once, and no call should transmit more than 25000 time-values at once. Each web method in our API documents its limitations.
The
refence documentation includes capacity limitations for each web methods.
Make sure your code is compliant with those limitations, because without some extra logic, it will work on small datasets, typically the ones that you are using for testing, but fails once in production because the datasets will be much larger.
In particular, if you have
long time-series which happens if you are handling high-frequency time-series (i.e. hourly or shorter periods), then you might need to upload each time-series through multiple calls to
UpdateSerieSegment.
Flat forecasts
It is normal to observe
flat (i.e. constant) forecasted time-series if input data are limited. Indeed, the time-series mean is a very robust forecasting model that tends to be the less inaccurate one when no significant statistical pattern can be detected. Thus don't be surprised, if you get flat time-series out of Lokad on toy datasets, this is the expected behavior.
Then, even with large datasets, you might observe that if you try to forecasts very far in the future the forecasted time-series become flat after a while. Again, this situation simply reflects that sometimes it is not possible to accurately forecast very far in the future. For example, it's not because you've been observing a consistent sales growth of 2% per month for the last 10 months, that it makes sense to predict a 2% growth per month for the next 10 years.
Forecast retrieval delay
In order to improve forecast accuracy it is best to introduce a delay between upload and retrieval. This is the consequence of the
Upload Early - Download Late principle of Lokad.
Basically, when data are uploaded to Lokad, our analytics computing grid starts to analyzing the data. The more time is given, the deeper is the analysis and the more accurate the forecasts become.
For typical usages, a few thousands time-series or less, we suggest
to wait 1 hour between upload and download. In practice, the accuracy improvement brought be the extra delay follows a law of diminishing returns. Thus, waiting for 1 week before retrieving the forecasts should not bring much improvement.
Also, when playing with small datasets, do not be surprised if, contrary to what we are saying here, forecasts do not change over time. Indeed, when the dataset is very limited, then the most simple forecasting models tend to be the best one because more complex models get penalized due to the risk of
overfitting.