Add a list of measures by type (real)

This endpoint allows registering a list of real measures for a product or section, limiting the registration to measures of a single type (e.g., "TICKETS").

POST /api/v1/import/business/{businessId}/product/{productId}/demandtype/{demandType}/measures

The URL must contain the following parameters:

Business external identifier (businessId).
Product or section external identifier (productId).
Name of the measure type configured in Orquest (demandType).

Below is an explanation of each of the fields that make up the body of the request.

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

Request body

JSON Analysis

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 format `yyyy-MM-ddTHH:mm:ss.SSSZ`. to: end of the time interval in UTC format `yyyy-MM-ddTHH:mm:ss.SSSZ`. measure*: name configured in Orquest for the measure.

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

Details

value*: numerical value of the measure.
from*: start of the time interval in UTC format yyyy-MM-ddTHH:mm:ss.SSSZ.
to*: end of the time interval in UTC format yyyy-MM-ddTHH:mm:ss.SSSZ.
measure*: name configured in Orquest for the measure.

Request example

After analyzing the different fields, here is an example request:

POST /api/v1/import/business/BUSINESSID/product/PRODUCTID/demandtype/TICKETS/measures

[
  {
    "value": 3.0000,
    "from": "2024-07-18T09:00:00.000Z",
    "to": "2024-07-18T09:15:00.000Z",
    "measure": "TICKETS"
  },
  {
    "value": 4.0000,
    "from": "2024-07-18T09:15:00.000Z",
    "to": "2024-07-18T09:30:00.000Z",
    "measure": "TICKETS"
  },
  {
    "value": 1.0000,
    "from": "2024-07-18T09:30:00.000Z",
    "to": "2024-07-18T09:45:00.000Z",
    "measure": "TICKETS"
  },
  {
    "value": 3.0000,
    "from": "2024-07-18T09:45:00.000Z",
    "to": "2024-07-18T10:00:00.000Z",
    "measure": "TICKETS"
  }
]

If the request data is correct, the process will return the values of the days involved in the operation with the data broken down into 15-minute intervals.

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 items. If more than 400 items are sent, the request will return a 406 Not Acceptable error.

The name of the measure must be exactly the same as configured in Orquest at the business level: Business configuration > Measure types > Name. It is necessary to respect case sensitivity, accents, etc. If the measure name does not match the one configured in Orquest or the one specified in the demandType parameter of the URL, the request will ignore that value.

If the data provided does not correspond to the measure specified in the demandType parameter of the URL, the values will be ignored. For example, if measures for type "SALES" are included in a "TICKETS" request, the "SALES" values will be ignored.

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

Values must be positive: if negative values are sent, the request will return a 406 Not Acceptable error indicating Value must be positive or zero.

Orquest always stores measure values in 15-minute intervals: if a value is sent for a one-hour period, for example, Orquest will divide this value equally into four 15-minute intervals.

If the time period for which the measure is sent is invalid, the request will return a 406 Not Acceptable error indicating Measure time range is invalid.

If duplicate or overlapping intervals are submitted, the request will return a 406 Not Acceptable error indicating Overlapped measures.

Useful links

What is a measure?

What are real measures?

How to integrate measures?