Add a list of measures (forecast)

This endpoint allows registering a list of forecast measures for a product or section.

PUT /api/v1/businesses/{businessId}/product/{productId}/forecast

The URL must include the business identifier (businessId) and the product or section identifier (productId).

Below is an explanation of each field in the request body.

All fields in this request are mandatory, which is why they are marked with an asterisk (*).

Request body

JSON Analysis 
[
  {
    "value": 0,
    "from": "string",
    "to": "string",
    "measure": "string"
  }
]
Details

  • value*: numerical value of the measure.

  • from*: start of the time interval in UTC, formatted as yyyy-MM-ddTHH:mm:ss.SSSZ.

  • to*: end of the time interval in UTC, formatted as yyyy-MM-ddTHH:mm:ss.SSSZ.

  • measure*: name configured in Orquest for the measure.

Request example

Once the analysis of the different fields has been completed, an example of the request is shown below:

PUT /api/v1/businesses/BUSINESSID/product/PRODUCTID/forecast
[
  {
    "value": 14.0000,
    "from": "2024-07-18T07:00:00.000Z",
    "to": "2024-07-18T08:00:00.000Z",
    "measure": "TICKETS"
  },
  {
    "value": 15.0000,
    "from": "2024-07-18T08:00:00.000Z",
    "to": "2024-07-18T09:00:00.000Z",
    "measure": "TICKETS"
  },
  {
    "value": 100.0000,
    "from": "2024-07-18T07:00:00.000Z",
    "to": "2024-07-18T08:00:00.000Z",
    "measure": "SALES"
  },
  {
    "value": 120.0000,
    "from": "2024-07-18T08:00:00.000Z",
    "to": "2024-07-18T09:00:00.000Z",
    "measure": "SALES"
  }
]

If the request data is correct, a 200 OK status will be returned.

Considerations

The date format used is UTC, but when inserting data, the service time zone must be considered.

When a set of measures is sent for a day, all previously recorded values for that day are deleted and replaced by those in the request. Therefore, it is essential to send complete days.

For example, if a single value is sent for the day 2024-07-18 from 10:00 to 10:15, all previously recorded values for that day will be lost, and only the value sent in the request will remain.

The date format used is UTC, and measures must be grouped by complete days.
Example of a complete day

If the service time zone is UTC+2, the data transformed to UTC for the day 2024-07-18 must span from 22:00 UTC of the previous day (2024-07-17) to 22:00 UTC of the same day (2024-07-18). This ensures that when inserting the data with the local time, the measures correctly match a full day in the service time zone.

Thus, if there are 5 TICKETS at 00:00 UTC+2 (local time), this value must be included in the request with the time converted to UTC, which in this case is 22:00 UTC of the previous day. Therefore, the body of the request for the entire day would be as follows:

[
  {"value": 5.0000, "from": "2024-07-17T22:00:00.000Z", "to": "2024-07-17T23:00:00.000Z", "measure": "TICKETS"},
  {"value": 3.0000, "from": "2024-07-17T23:00:00.000Z", "to": "2024-07-18T00:00:00.000Z", "measure": "TICKETS"},
  {"value": 4.0000, "from": "2024-07-18T00:00:00.000Z", "to": "2024-07-18T01:00:00.000Z", "measure": "TICKETS"},
  {"value": 2.0000, "from": "2024-07-18T01:00:00.000Z", "to": "2024-07-18T02:00:00.000Z", "measure": "TICKETS"},
  {"value": 6.0000, "from": "2024-07-18T02:00:00.000Z", "to": "2024-07-18T03:00:00.000Z", "measure": "TICKETS"},
  {"value": 5.0000, "from": "2024-07-18T03:00:00.000Z", "to": "2024-07-18T04:00:00.000Z", "measure": "TICKETS"},
  {"value": 3.0000, "from": "2024-07-18T04:00:00.000Z", "to": "2024-07-18T05:00:00.000Z", "measure": "TICKETS"},
  {"value": 4.0000, "from": "2024-07-18T05:00:00.000Z", "to": "2024-07-18T06:00:00.000Z", "measure": "TICKETS"},
  {"value": 3.0000, "from": "2024-07-18T06:00:00.000Z", "to": "2024-07-18T07:00:00.000Z", "measure": "TICKETS"},
  {"value": 2.0000, "from": "2024-07-18T07:00:00.000Z", "to": "2024-07-18T08:00:00.000Z", "measure": "TICKETS"},
  {"value": 6.0000, "from": "2024-07-18T08:00:00.000Z", "to": "2024-07-18T09:00:00.000Z", "measure": "TICKETS"},
  {"value": 5.0000, "from": "2024-07-18T09:00:00.000Z", "to": "2024-07-18T10:00:00.000Z", "measure": "TICKETS"},
  {"value": 3.0000, "from": "2024-07-18T10:00:00.000Z", "to": "2024-07-18T11:00:00.000Z", "measure": "TICKETS"},
  {"value": 4.0000, "from": "2024-07-18T11:00:00.000Z", "to": "2024-07-18T12:00:00.000Z", "measure": "TICKETS"},
  {"value": 2.0000, "from": "2024-07-18T12:00:00.000Z", "to": "2024-07-18T13:00:00.000Z", "measure": "TICKETS"},
  {"value": 6.0000, "from": "2024-07-18T13:00:00.000Z", "to": "2024-07-18T14:00:00.000Z", "measure": "TICKETS"},
  {"value": 5.0000, "from": "2024-07-18T14:00:00.000Z", "to": "2024-07-18T15:00:00.000Z", "measure": "TICKETS"},
  {"value": 3.0000, "from": "2024-07-18T15:00:00.000Z", "to": "2024-07-18T16:00:00.000Z", "measure": "TICKETS"},
  {"value": 4.0000, "from": "2024-07-18T16:00:00.000Z", "to": "2024-07-18T17:00:00.000Z", "measure": "TICKETS"},
  {"value": 2.0000, "from": "2024-07-18T17:00:00.000Z", "to": "2024-07-18T18:00:00.000Z", "measure": "TICKETS"},
  {"value": 6.0000, "from": "2024-07-18T18:00:00.000Z", "to": "2024-07-18T19:00:00.000Z", "measure": "TICKETS"},
  {"value": 5.0000, "from": "2024-07-18T19:00:00.000Z", "to": "2024-07-18T20:00:00.000Z", "measure": "TICKETS"},
  {"value": 3.0000, "from": "2024-07-18T20:00:00.000Z", "to": "2024-07-18T21:00:00.000Z", "measure": "TICKETS"},
  {"value": 4.0000, "from": "2024-07-18T21:00:00.000Z", "to": "2024-07-18T22:00:00.000Z", "measure": "TICKETS"}
]

The insertion of measures from this example will be performed in UTC+2 for the full day of 2024-07-18 (from 00:00 to 00:00).

This request has a limit of 400 elements.

The measure name must match exactly as configured in Orquest at the business level: Business configuration > Measure types > Name. It is necessary to respect case sensitivity, accents, etc.

The value supports decimals, although the application will only display the number of decimals configured for the measure’s precision level: Business configuration > Measure types > Precision.

Unlike other endpoints in this domain, this request does not validate that the interval of each item is a multiple of 15 minutes. An interval that is not a multiple does not return any error: the previous data for that period is deleted and the new data is never saved, so it is silently lost. It is recommended to always send intervals in multiples of 15 minutes.

Error codes

In addition to the common errors, this endpoint can return the following codes:

Code Message Description

400 Bad Request

Bad number of observations

The collection sent is empty or exceeds the limit of 400 items allowed.

Demand type not found

The measure name (measure) of one or more items does not match any type configured in the business.

Value mut be positive or zero

The value field has a negative value in one or more items. This is the literal as returned by the backend, with the typo "mut" instead of "must".

Measure type cannot be null

The measure field is missing in one or more items.

From is required / To is required

The from or to field is missing in one or more items.

Business id is required / Product id is required

The business or product identifier is missing.

Observations are required

The observations collection is missing.

Overlapped measures

Two or more items in the request have overlapping time intervals.

-

The request body is not in a valid JSON format.

Useful links

What is a measure?

What is forecast?

How to integrate measures?