I want to integrate measures

What are measures?

As detailed here, business measures are quantitative indicators used to evaluate various performance aspects, such as sales, ticket numbers, orders, footfall, etc.

How to integrate measures?

There are two options to integrate measures into the system: via SFTP and via API.

  • Via SFTP. CSV files are placed in an SFTP directory for processing as detailed here.

  • Via API. The Orquest API provides various endpoints to send and retrieve the measures configured in a business.

Below is a breakdown of different scenarios and the endpoints that are useful in each case.

What operations can be performed when integrating measures via API?

Add a list of measures

To register measures via API, the following endpoints can be used:

The choice of one endpoint or another depends on the information you want to integrate into Orquest: whether it concerns real measures (past data) or the forecast (future data).

Add a list of measures of a single type

Considering the limitations of the endpoints in the previous scenario —400 items per request— the Orquest API provides an alternative: adding measures of a single type (e.g., "TICKETS"). For this, requests should be made to the following endpoints:

In these requests, the demandType parameter, which specifies the type of measure for which the data is being inserted, is included in the URL.

As in the previous scenario, the choice of one endpoint or another depends on whether the data is for real measures (past data) or forecast (future data).

Update measures

As detailed in the documentation for each endpoint, measures must be grouped by day. When a request includes measures for a specific day, all previously recorded values for that day are deleted and replaced with the values included in the request.

Therefore, for this operation, it is necessary to make a request with the updated data for a complete day to the following endpoints:

The choice of endpoint depends on whether they are real measures or forecast, as well as whether the measures are sent by type or not.

Delete measures

Following the logic of measure updates mentioned above, if the request includes a single measure with a value of 0, all previously recorded values for that day for that measure will be lost.

Example

If the following request is made, all "TICKETS" values for the day 2024/07/18 will be deleted:

POST /api/v1/import/business/BUSINESSID/product/PRODUCTID/measures
[
  {
    "value": 0,
    "from": "2024-07-18T07:00:00.000Z",
    "to": "2024-07-18T08:00:00.000Z",
    "measure": "TICKETS"
  }
]

As in the previous scenario, the following endpoints allow deleting measures from the system:

Get measures

The Orquest API allows querying the three types of measures in the system: projection, forecast and real measures.

  • Get projections. Returns the projection of measures, that is, the forecast approved by the user.

  • Get forecast. Returns the forecast of measures, that is, the estimate made by Orquest or an external system based on real measures.

  • Get measures (real). Returns the real measures, that is, the existing data obtained from the respective indicators.

In any of the requests, the query range must not exceed 30 days, and the measurements will always be returned in UTC and in 15-minute intervals.

Additionally, it is possible to filter the results by measure type by adding the demandTypeNames parameter to the URL, as detailed in the documentation for each of the endpoints listed above.

Example

Below is an example of querying real measures filtered by the measure type SALES.

GET /api/v1/business/BUSINESSID/product/PRODUCTID/demand/from/2024-07-15/to/2024-07-31?demandTypeNames=SALES

Response snippet:

[
    {
        "value": 1.25,
        "from": "2024-07-17T22:00:00.000Z",
        "to": "2024-07-17T22:15:00.000Z",
        "measure": "SALES"
    },
    {
        "value": 1.25,
        "from": "2024-07-17T22:15:00.000Z",
        "to": "2024-07-17T22:30:00.000Z",
        "measure": "SALES"
    },
    {
        "value": 1.25,
        "from": "2024-07-17T22:30:00.000Z",
        "to": "2024-07-17T22:45:00.000Z",
        "measure": "SALES"
    },
    {
        "value": 1.25,
        "from": "2024-07-17T22:45:00.000Z",
        "to": "2024-07-17T23:00:00.000Z",
        "measure": "SALES"
    }
]

If the demandTypeNames parameter is not specified, the response will include all product measures within the specified date range.

FAQ

What time zone is considered for integration?

In SFTP integration, the TIME column considers the local time, that is, the time zone configured in Orquest for the service. For example, if the service time zone is UTC+2, the data included for 10:00 (1000 in HHmm format) will be inserted at 10:00 UTC+2.

In API integration, however, the measures are sent in UTC. Therefore, it is necessary to consider the time zone for which the data will be inserted. For example, if the service time zone is UTC+2, the data included in the request for 08:00 UTC will be inserted at 10:00 UTC+2.

Thus, to send measures for the day 2024/07/18, the data should be sent from 22:00 UTC the previous day (2024/07/17) until 22:00 UTC on the same day (2024/07/18).

Example 
[
  {"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"}
]

Is it possible to add measure data for a specific time slot via API?

As detailed in the previous operations, API integration requires requests to contain data for complete days. If only data for a specific time slot within the day is included, the rest of the previously integrated values for that day will be removed from the system.

Which is more recommended, SFTP or API?

While the choice between SFTP and API depends on the client’s needs and preferences, API integration offers a significant advantage: it provides more detailed feedback in the response. In case of an error, the API returns information that helps identify what went wrong with the submitted data, enabling faster and more accurate resolution. SFTP integration, however, does not provide direct feedback, making it harder to detect and resolve issues with the transferred data.