Important

This Lokad API version has been replaced by Lokad API Version 2. Please migrate to the newer version.

This page is not intended to be an introduction to web-services technologies but a technical reference documentation. For an introduction, please refer to SOAP article on Wikipedia. For the API documentation and tutorials, you can check the Lokad API product page.

Overview

Summary

First, the TimeSeries web-service is a time-serie data provider associated your LOKAD account. The API provides method that are equivalent to the Check Data panel of your Lokad account. This web service can be used in particular to create and populate time-series. Second, this web-service is also a forecasting provider that can be used to define forecasting tasks and to retrieve the forecasted time-series. The API provides methods that are equivalent to the Check Tasks panel of your Lokad account.

Authentication

Lokad WebServices are relying on Soap headers to perform the caller authentication. You need to populate the field TimeSeries.Authentication in order to get your call authenticated. You can use the method IsAuthenticated to check that your Soap headers are correct.

Thread-safety

All the provided WebMethods are thread-safe.

Naming

Time-series and forecasting tasks have names (i.e. strings used as identifiers). Those names could not include more than 64 characters. Additionally, the following list of characters ; [ ] < > \ / " ' are prohibited.

Methods

The following operations are supported. For a formal definition, please review the Service Description.

• AddSerie
  

  Imports a time-serie with the specified values.

  serie: Time-serie to import. The serie name should be distinct from any other time-serie names existing in your account and should be less than 64 characters. The unit name is provided for user convenience only. It has no impact on the time-serie semantic and must be less than 64 characters. The UTC offset expresses the number of hours of difference between the local time and the UTC time. The simple equation local time = UTC time + offset expresses the relationship between local time and UTC time. The UTC offset must be lower or equal to 12 in absolute terms.

  Limitations: The time-serie could not include more than 25000 time-values. If you need to upload a time-serie with more than 25000 time-values; then, you should use UpdateTimeValues.

• AddSeries
  

  Imports a set of time-series with the specified values.

  series: Time-series to import. The serie names should be distinct from any other time-serie names existing in your account and should be less than 64 characters. The unit names are provided for user convenience only. They have no impact on the time-serie semantic and must be less than 64 characters. The UTC offsets express the number of hours of difference between the local time and the UTC time. The simple equation local time = UTC time + offset expresses the relationship between local time and UTC time. The UTC offsets must be lower or equal to 12 in absolute terms.

  Limitations: no more than 500 time-series must be added at once. The total number of time-values must lower or equal to 25000 time-values. If you have more than 500 time-series, then you should split your call into several calls to AddSeries.

• AddTask
  

  Create a new forecasting task associated to a specified time-serie.

  serieName: the name that identifies the time-serie that should be associated with the created task.

  task: the forecasting task definition.

  Limitations: for performance reasons, Task.FuturePeriods is upper-bounded; the actual upper-bound depends from Task.Period. For Period.Hour, Period.HalfHour and Period.QuarterHour, the limit is set to six weeks, e.g. 1008, 2016 and 4032 respectively. For all all the other periods, the limit is set to 64.

  An ArgumentException is thrown if the task has not been created. A task creation failure usually indicates that the task name is already taken.

• AddTasks
  

  Create a list of new forecasting tasks, each task being associated to a specified time-serie.

  serieNames: the names that identifies the time-series.

  tasks: the forecasting task definitions.

  Limitations: See AddTask for more details about Task.FuturePeriods limits. No more than 500 tasks should be created at once. If you need to create more than 500 tasks, then you should call AddTasks several times with smaller arguments.

  An ArgumentException is thrown if the task has not been created. A task creation failure usually indicates that the task name is already taken.

• DeleteSerie
  

  Delete a time-serie all the associated data (tasks, forecasts) from the Lokad account.

  serieName: identifies the time-serie to be deleted.

  return value: indicates whether the deletion call has been successful or not. An failed deletion usually indicates that the time-serie does not exists.

• DeleteSeries
  

  Delete a set of time-series with all the associated data (tasks, forecasts) from the Lokad account.

  serieNames: identifies the time-series to be deleted.

  Limitations: No more than 500 serie names to be deleted at once. If you have more than 500 series to delete, then you should be split your call into several smaller call to DeleteSeries.

• DeleteTask
  

  Delete a forecasting task and all the associated forecast results.

  serieName: name of the time-serie defining the scope of the task to be deleted..

  taskName: name of the task to be deleted.

  An ArgumentException is thrown if the task has not been deleted. A task deletion failure usually indicates that there is no corresponding task associated to the specified task name.

• DeleteTasks
  

  Delete a list of forecasting tasks (and all the associated forecast results.

  serieNames: names of the time-serie defining the scope of the task to be deleted..

  taskNames: names of the task to be deleted.

  Limitations: no more than 500 tasks could be deleted at once. If you need to delete more than 500 tasks, then you should call DeleteTasks several times with smaller arguments.

  An ArgumentException is thrown if the task has not been deleted. A task deletion failure usually indicates that there is no corresponding task associated to the specified task name.

• GetAllSerieNames
  

  Gets the names of all the time-series existing in your Lokad account.

  DEPRECATED: Because of its potential scalability issues, this method should be considered as deprecated. The exact same return will be obtained with GetSerieNames(0, 5000).

  Limitations: Only the first 5000 serie names will be returned. if you need to retrieve more than 5000 names; then consider using GetSerieNames.

• GetAllTaskNames
  

  Gets the names of all the tasks existing in your Lokad account. Each returned string is the concatenation of the serie name, the delimiter and the task name: serieName + delimiter + taskName.

  delimiter: put in between the serie name and the task name. Must be less than 16 characters.

  DEPRECATED: Because of its potential scalability issues, this method should be considered as deprecated. The exact same return will be obtained with GetTaskNames(0, 5000).

  Limitations: Only the first 5000 task names will be returned. if you need to retrieve more than 5000 names; then consider using GetTaskNames.

• GetForecast
  

  Gets the forecast results associated to the specified forecasting task.

  serieName: name of the time-serie defining the scope of the forecasting task.

  taskName: name of the forecasting task defined with the scope of the time-serie.

  return value: forecast results expressed as a time-series. The time-value pairs are sorted in increasing order against the Time property. An ArgumentException can be thrown if no matching forecasting task can be found.

• GetForecasts
  

  Gets the forecast results associated to an array of forecasting tasks.

  serieNames: array of time-serie names.

  taskNames: array of task names.

  Remark: the length of the two arrays serieNames and taskNames must match.

  Limitations: No more than 500 forecasts could be retrieved at once. If you need to retrieve more than 500 forecasts, then you should call GetForecasts multiple times with smaller arguments. No more than 25000 time-values could be retrieved at once. If the sum of the future periods for the considered tasks is greater than 25000, then you should call GetForecasts multiple time with smaller arguments.

  return value: a list of time-series. The order of the time-series matches the order of the tasks as defined by taskNames.

• GetMape
  

  Gets the MAPE (Mean Absolute Percentage Error) associated with a forecasting task.

  serieName: name of the time-serie defining the scope of the forecasting task.

  taskName: name of the forecasting task defined with the scope of the time-serie.

  return value: MAPE value comprised between 0 and 1.

• GetMapes
  

  Gets the MAPEs (Mean Absolute Percentage Errors) associated with the specified forecasting tasks.

  serieNames: array of time-serie names.

  taskNames: array of task names.

  Remark: the length of the two arrays serieNames and taskNames must match.

  Limitations: No more than 500 errors could be retrieved at once. If you need to retrieve more than 500 errors, then you should call GetMapes multiple times with smaller arguments.

  return value: MAPE values comprised between 0 and 1.

• GetSerie
  

  Gets a time serie including all its time-values (within limits, see below).

  serieName: identifies the time-serie to be retrieved.

  Limitations: only the first 25000 time-values are retrieved. If the time-serie includes more than 25000 time-values, then you should use GetSerieSegment to retrieve all the time-values.

  return value: A time serie instance where the timeValues are sorted in increasing order against their Time values. The DateTime values are expressed as local times. The UTC time offset has already been applied.

• GetSerieNames
  

  Gets the names of the time-series in your Lokad account.

  index: position of the first time-serie name to be retrieved.

  pageSize: maximal number of time-series names to be retrieved. The maximal value for this argument is 5000.

• GetSerieSegment
  

  Gets a page of time-values associated to a time-serie.

  serieName: identifies the time-serie whose values will be retrieved.

  index: position of the first time-value to be retrieved.

  pageSize: maximal number of time-values to be retrieved. The maximal value for this argument is 25000.

• GetTask
  

  Gets an existing task.

  serieName: name of the time-serie associated to the retrieved task.

  taskName: name of the task to be retrieved.

  An ArgumentException is thrown if no corresponding task can be found.

• GetTaskNames
  

  Gets the names of all the tasks existing in your Lokad account. Each returned string is the concatenation of the serie name, the delimiter and the task name: serieName + delimiter + taskName.

  delimiter: put in between the serie name and the task name. Must be less than 16 characters.

  Limitations: Only the first 5000 task names will be returned. if you need to retrieve more than 5000 names; then consider using GetTaskNames.

• GetTasks
  

  Gets all the tasks associated to a specified time-serie.

  serieName: name of the time-serie defining the scope of the forecasting tasks.

  return value: returns an empty array if there are no tasks associated to the specified time-serie. An ArgumentException is thrown if the time-serie does not exists.

• IsAuthenticated
  

  Indicates whether the caller is authenticated or not. This method can be used to validate the authentication Soap Headers.

• RenameSerie
  

  Rename an existing time-serie.

  oldSerieName: The current name of the time-serie to be renamed.

  newSerieName: The new name for the time-serie to be renamed.

• RenameTask
  

  Rename a forecasting task.

  serieName: identifies the time-serie defining the scope of the forecasting task.

  oldTaskName: current name of the task.

  newTaskName: new name for the task.

• SetPartner
  

  This method is used to track affiliation. It associates the authenticated call to a partner account. This method is typically called only once, during the first data upload.

  partnerId: identifier of the partner account.

  Remark: in case of incorrect partnerId value, this method will simply have no effect, but no exception will be thrown.

• UpdateSerie
  

  Update a time-serie with the specified values.

  serie: Time-series to update. The serie name should be distinct from any other time-serie names existing in your account and should be less than 64 characters. The unit name is provided for user convenience only. It has no impact on the time-serie semantic and must be less than 64 characters. The UTC offset expresses the number of hours of difference between the local time and the UTC time. The simple equation local time = UTC time + offset expresses the relationship between local time and UTC time. The UTC offset must be lower or equal to 12 in absolute terms.

  Limitations: The time-serie could not include more than 25000 time-values. If you need to upload a time-serie with more than 25000 time-values; then, you should use UpdateTimeValues.

• UpdateSerieSegment
  

  Incremental time-serie update. The inclusive segment defined by timeValues gets overwritten by the timeValues items.

  serieName: The name of the time-serie to be updated.

  timeValues: Time-values segment that get inserted into the time-serie.

  Limitations: The call could not include more than 25000 time-values. If you need to update more than 25000 time-values; then, you should call UpdateSerieSegment several times with smaller segments.

• UpdateSerieSegments
  

  Incremental time-serie update. The inclusive segments defined by timeValues gets overwritten by the timeValues items.

  serieNames: The names of the time-series to be updated.

  timeValues: Time-values segments that get inserted into the time-series.

  Limitations: The call could not include more than 25000 time-values. If you need to update more than 25000 time-values; then, you should call UpdateSerieSegment several times with smaller segments.

• UpdateSeries
  

  Update a set of time-series with the specified values.

  series: Time-series to update. The serie names should be distinct from any other time-serie names existing in your account and should be less than 64 characters. The unit names are provided for user convenience only. They have no impact on the time-serie semantic and must be less than 64 characters. The UTC offsets express the number of hours of difference between the local time and the UTC time. The simple equation local time = UTC time + offset expresses the relationship between local time and UTC time. The UTC offsets must be lower or equal to 12 in absolute terms.

  Limitations: no more than 500 time-series must be updated at once. The total number of time-values must lower or equal to 25000 time-values. If you have more than 500 time-series, then you should split your call into several calls to UpdateSeries.

• UpdateTask
  

  Update the settings of a forecasting task (all settings except its name).

  serieName: name of the time-serie defining the scope of the forecasting task.

  task: settings of the forecasting task. The task to be updated in specified through the property task.Name.

• UpdateTasks
  

  Updates the settings of a list of forecasting tasks (all settings except the task names).

  serieName: name of the time-serie defining the scope of the forecasting task.

  Limitations: no more than 500 tasks could be updated at once. If you need to update more than 500 tasks; then you should call UpdateTasks several times with smaller arguments.

  task: settings of the forecasting task. The task to be updated in specified through the property task.Name.