Date breakdown

How to perform a date breakdown query and how it works

Date breakdowns are aggregations that show the frequency of occurrence of a specific date value within a dataset and let you apply a specific operator over a selected field of the records that are present on that date. When performing a date breakdown query on the Metrics API endpoint you get in the response the list by date of the values of the computation (based on the selected operator) on the selected field, over the selected time interval, aggregated by another field.

Request

To perform a date breakdown query send a POST request to the /{{resource_name}}/date_breakdown endpoint specifying the query keys and filter parameters:

{
  "date_breakdown": {
    "by": "...",
    "field": "...",
    "operator": "...",
    "interval": "...",
    "breakdown": { ... }
  },
  "filter": { ... },
  "meta": { ... }
}

Query keys

Key
Type
Required
Description
Values

by

String

The date field you want the results of the query aggragated by.

The available values for this key depend on the resource you're doing statistics on (see orders, returns, or carts for the related lists).

field

String

The field you want the metrics or statistics computed on.

The available values for this key depend on the resource you're doing statistics on (see orders, returns, or carts for the related lists).

operator

String

The computing operator.

The available operators depend on the field key value (see orders, returns, or carts for the related lists).

interval

String

The time interval over which the metrics / stats are computed. The results will be aggregated by date accordingly (read how).

One of hour, day, week, month, or year (default is month).

breakdown

object

The optional breakdown (eventually nested).

The nested breakdown by key available values depend of the parent breakdown by key value (see orders, returns, or carts for the related lists).

Nesting breakdowns

You can nest a breakdown query into a date breakdown one. This means you can request each aggregation by date over the selected time interval to be in turn aggregated by another field. Since the nested breakdown is a full-fledged breakdown query, it supports its own nesting (up to one level), as shown in the following example.

Response

The response of a date breakdown query returns an aggregation by date over the time interval specified in the interval key, containing the value of the computation (based on the operator specified in the operator key) on the field specified in the field key. If the query contains a nested breakdown, it is also detailed for each item of the array:

{
  "data": [
    {
      "date": "...",
      "value": ...,
      "...": [ // breakdown by
        {
          "label": "...",
          "value": ...,
          "...": [ // nested breakdown by
            {
              "label": "...",
              "value": ...
            },
            { ... }
          ]
        },
        { ... }
      ]
    },
    {
      "date": "...",
      "value": ...,
      "...": [ // breakdown by
        {
          "label": "...",
          "value": ...,
          "...": [ // nested breakdown by
            {
              "label": "...",
              "value": ...
            },
            { ... }
          ]
        },
        { ... }
      ]
    },
    { ... } 
  ],
  "meta": { ... }
}

Date intervals

The results of a date breakdown query are aggregated over the specified time intervals. You can identify them in the response by looking at the date keys:

{
  "data": [
    {
      "date": "2021-04-01T00:00:00.000Z",
      "value": { ... }
    },
    {
      "date": "2021-05-01T00:00:00.000Z",
      "value": { ... }
    },
    { ... },
    {
      "date": "2021-09-01T00:00:00.000Z",
      "value": { ... }
    }
  ],
  "meta": { ... }
}
Interval
Date key values

year

YYYY-01-01T00:00:00.000Z

month

YYYY-MM-01T00:00:00.000Z

day

YYYY-MM-DDT00:00:00.000Z

hour

YYYY-MM-DDTHH:00:00.000Z

Examples

Date breakdown

The following request performs a date breakdown query to get the stats about the orders placed by month:

curl -g -X POST \
  'https://{{your_domain}}.commercelayer.io/metrics/orders/date_breakdown' \
  -H 'Accept: application/vnd.api.v1+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Authorization: Bearer {{your_access_token}}' \
  -d '{
    "date_breakdown": {
      "by": "order.placed_at",
      "field": "order.total_amount_with_taxes",
      "operator": "stats",
      "interval": "month"
    }
}'

Date breakdown with nested breakdown

The following request performs a date breakdown query to get the stats about the orders placed by month. Over each time interval, a breakdown of the orders' total amounts to check the maximum by country code is also requested. For each country code, a breakdown of the orders' total amounts to check the maximum by currency code (as long as it's over a specific threshold) is then requested:

curl -g -X POST \
  'https://{{your_domain}}.commercelayer.io/metrics/orders/date_breakdown' \
  -H 'Accept: application/vnd.api.v1+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Authorization: Bearer {{your_access_token}}' \
  -d '{
    "date_breakdown": {
      "by": "order.placed_at",
      "field": "order.total_amount_with_taxes",
      "operator": "stats",
      "interval": "month",
      "breakdown": {
        "by": "order.country_code",
        "field": "order.total_amount_with_taxes",
        "operator": "max",
        "sort": "desc",
        "limit": 3,
        "breakdown": {
          "by": "order.currency_code",
          "field": "order.total_amount_with_taxes",
          "operator": "max",
          "condition": {
            "gt": 100
          }
          "sort": "desc",
          "limit": 2
        }
      }
    }
  }'

Last updated