REST API

Create a forecasting task and get predicted future values.

Endpoint

POST https://ai.timecho.com/ai/api/v1/forecast

Supports univariate forecasting and forecasting with covariates.

Request header parameters

Name	Required	Description
Content-Type	Yes	Fixed value: application/json
Authorization	Yes	Bearer {API-Key}. Replace {API-Key} with your API key.

Univariate request example

{
  "targets": [
    {
      "columns": ["time", "temperature"],
      "data": [
        ["2024-01-01T00:00:00", 36.2],
        ["2024-01-01T01:00:00", 36.5],
        ["2024-01-01T02:00:00", 36.8],
        ["2024-01-01T03:00:00", 37.1],
        ["2024-01-01T04:00:00", 37.4],
        ["2024-01-01T05:00:00", 37.7],
        ["2024-01-01T06:00:00", 38.0],
        ["2024-01-01T07:00:00", 38.3],
        ["2024-01-01T08:00:00", 38.6],
        ["2024-01-01T09:00:00", 38.9],
        ["2024-01-01T10:00:00", 39.2],
        ["2024-01-01T11:00:00", 39.5],
        ["2024-01-01T12:00:00", 39.8],
        ["2024-01-01T13:00:00", 40.1],
        ["2024-01-01T14:00:00", 40.4],
        ["2024-01-01T15:00:00", 40.7]
      ]
    }
  ],
  "output_length": [8],
  "time_col": ["time"]
}

Covariate request example

{
  "targets": [
    {
      "columns": ["time", "sales"],
      "data": [
        ["2024-01-01T00:00:00", 120],
        ["2024-01-01T01:00:00", 135],
        ["2024-01-01T02:00:00", 142],
        ["2024-01-01T03:00:00", 168],
        ["2024-01-01T04:00:00", 195],
        ["2024-01-01T05:00:00", 220],
        ["2024-01-01T06:00:00", 285],
        ["2024-01-01T07:00:00", 310],
        ["2024-01-01T08:00:00", 345],
        ["2024-01-01T09:00:00", 380],
        ["2024-01-01T10:00:00", 420],
        ["2024-01-01T11:00:00", 468],
        ["2024-01-01T12:00:00", 505],
        ["2024-01-01T13:00:00", 540],
        ["2024-01-01T14:00:00", 575],
        ["2024-01-01T15:00:00", 610]
      ]
    }
  ],
  "history_covs": [
    {
      "columns": ["time", "temperature"],
      "data": [
        ["2024-01-01T00:00:00", 25],
        ["2024-01-01T01:00:00", 26],
        ["2024-01-01T02:00:00", 24],
        ["2024-01-01T03:00:00", 28],
        ["2024-01-01T04:00:00", 30],
        ["2024-01-01T05:00:00", 32],
        ["2024-01-01T06:00:00", 35],
        ["2024-01-01T07:00:00", 33],
        ["2024-01-01T08:00:00", 31],
        ["2024-01-01T09:00:00", 29],
        ["2024-01-01T10:00:00", 27],
        ["2024-01-01T11:00:00", 25],
        ["2024-01-01T12:00:00", 24],
        ["2024-01-01T13:00:00", 26],
        ["2024-01-01T14:00:00", 28],
        ["2024-01-01T15:00:00", 30]
      ]
    }
  ],
  "output_length": [8],
  "time_col": ["time"]
}

Response parameters

Parameter	Type	Description
code	integer	Status code. 200 indicates success.
message	string	Status message.
data	array	Forecast result array.
data[].time	string	Forecast timestamp.
data[].columns	array	Column names.
data[].data	array	Forecast values.

Univariate response example

{
  "code": 200,
  "message": "Forecast tasks completed successfully",
  "data": {
    "results": [
      {
        "data": [
          ["2024-01-02T08:00:00", 45.767513275146484],
          ["2024-01-02T09:00:00", 45.90715789794922],
          ["2024-01-02T10:00:00", 46.05409622192383],
          ["2024-01-02T11:00:00", 46.18025207519531],
          ["2024-01-02T12:00:00", 46.245948791503906],
          ["2024-01-02T13:00:00", 46.29782485961914],
          ["2024-01-02T14:00:00", 46.313785552978516],
          ["2024-01-02T15:00:00", 46.29523849487305]
        ],
        "columns": ["time", "temperature"]
      }
    ]
  }
}

Covariate response example

{
  "code": 200,
  "message": "Forecast tasks completed successfully",
  "data": {
    "results": [
      {
        "data": [
          ["2024-01-01T16:00:00", 631.1929931640625],
          ["2024-01-01T17:00:00", 672.871826171875],
          ["2024-01-01T18:00:00", 711.1798706054688],
          ["2024-01-01T19:00:00", 744.8341064453125],
          ["2024-01-01T20:00:00", 777.4623413085938],
          ["2024-01-01T21:00:00", 810.2813720703125],
          ["2024-01-01T22:00:00", 842.3271484375],
          ["2024-01-01T23:00:00", 873.8246459960938]
        ],
        "columns": ["time", "sales"]
      }
    ]
  }
}