[Internal] Analytics¶

Analytics KPIs and Metrics¶

Work-in-progress refactoring. The current paradigm for analytics is “store data aggregations every [small periods, as of May 2024, fixed at 5 minutes] and compute the actual business KPIs in real-time using these stored aggregations.

Vocabulary:

Metric: Concept internal to Analytics. Details of Metrics should not be known outside of the Applied Machine Learning team. Metrics are aggregations of data that is strictly additive: If t2 is between t1 and t3, then Metric(t1, t3) = Metric(t1, t2) + Metric(t2, t3). This data is what is computed by analytics scripts and get stored in the database tables. Metrics are only useful as a computational trick for obtaining real-time KPIs.
KPI: Key Performance Indicator. Each KPI holds relevant data to show customers and that can be used to make decisions with. KPIs are typically computed from the aggregation of several metrics.
- Exemple 1: Total revenue is a relevant KPI for our customers to follow. It also verifies total_revenue(t1, t3) = total_revenue(t1, t2) + total_revenue(t2, t3), so it can be stored as a metric and then returned as-is as a KPI.
- Exemple 2: AOV, Average Order Value, is also a relevant KPI for our customers. It is computed using total_revenue / count_orders. AOV could not be stored a Metric directly because AOV(January) is NOT average (AOV(each day of January)). So, the AOV KPI uses the data stored in the metrics total_revenue` and count_orders to be computed.

This is disconnected from the deprecated Analytics Segmentation.

[DEPRECATED] Analytics Segmentation¶

These endpoints are to create, read, update, delete analytics segmentation parameters.

To segment analytics, please refer to Analytics Segmentation.

To trigger the analytics calculation background task, please refer to POST tasks/private/analytics_report_export/.

[Internal] Get Many Analytics KPI Statuses¶

GET analytics/kpis/status/¶

Note

Authorized Roles: root, manager

Get KPI status, along with the KPI config.

For this endpoint, order matters: when displaying KPIs, the order returned should be respected as much as possible.

As of May 2024, the only available status is ok. This will later be extended to other statuses such as missing_data, missing_config.

Units

We currently support usd, count, percentage. Details:

percentage: when the response gives a value of 1, it means 1% (not 100%)

Query Parameters

kpis (list-of-string) – Optional. KPI names

EXAMPLE QUERY PARAMS¶

  ?kpis=direct_revenue&kpis=total_revenue

Response JSON Object

warnings (list-of-string) – Optional. List of warnings
kpis (list-of-object) –
KPI configs
Inner fields
- name (string) – KPI name
- metadata (object) – KPI metadata. Typically hold display names, descriptions, units, etc.
- metrics (list-of-string) – Names of metrics used by KPI

EXAMPLE RESPONSE¶

  {
      "statuses": [
          {
              "status": "ok",
              "kpi": {
                  "name": "direct_revenue",
                  "metadata": {
                      "display_name": "Direct Revenue",
                      "unit": "usd",
                      "description": "Direct Revenue is revenue derived from users who purchased a recommended item within 48 hours of clicking on that recommended item."
                  },
                  "metrics": ["direct_revenue"]
              }
          },
          {
              "status": "ok",
              "kpi": {
                  "name": "total_revenue",
                  "metadata": {
                      "display_name": "Total Revenue",
                      "unit": "usd",
                      "description": "Total revenue generated: sum of the latest item price for purchases made available to Crossing Minds."
                  },
                  "metrics": ["total_revenue"]
              }
          }
      ]
  }

[Internal] Get Many Analytics KPI Configs¶

GET analytics/kpis/configs/¶

Note

Authorized Roles: root, manager

Get KPI configs.

Query Parameters

kpis (list-of-string) – Optional. KPI names

EXAMPLE QUERY PARAMS¶

  ?kpis=direct_revenue&kpis=total_revenue

Response JSON Object

warnings (list-of-string) – Optional. List of warnings
kpis (list-of-object) –
KPI configs
Inner fields
- name (string) – KPI name
- metadata (object) – KPI metadata. Typically hold display names, descriptions, units, etc.
- metrics (list-of-string) – Names of metrics used by KPI

EXAMPLE RESPONSE¶

  {
      "kpis": [
          {
              "name": "direct_revenue",
              "metadata": {
                  "display_name": "Direct Revenue",
                  "unit": "usd",
                  "description": "Direct Revenue is revenue derived from users who purchased a recommended item within 48 hours of clicking on that recommended item."
              },
              "metrics": ["direct_revenue"]
          },
          {
              "name": "total_revenue",
              "metadata": {
                  "display_name": "Total Revenue",
                  "unit": "usd",
                  "description": "Total revenue generated: sum of the latest item price for purchases made available to Crossing Minds."
              },
              "metrics": ["total_revenue"]
          }
      ]
  }

[Internal] Get Many Analytics KPI Values¶

GET analytics/kpis/values/¶

Note

Authorized Roles: root, manager

Returns historical data by KPI.

Optionally give a time range.

The values in start_timestamp and end_timestamp might be changed to be better aligned with the bounds of the stored data, but the requested time range will always be included. Please note that the buckets are not guaranteed to always have the same size. The current output might indeed always return buckets of same sizes, but that is not part of the contract and might change in the future.

Query Parameters

start_timestamp (float) – Optional. Start timestamp. Default: start of available data. Note that the response will return buckets that start at or before this requested timestamp.
end_timestamp (float) – Optional. End timestamp. Default: current timestamp. Note that the response will return buckets that end at or after this requested timestamp.
kpis (list-of-string) – Optional. KPI names

EXAMPLE QUERY PARAMS¶

  ?start_timestamp=1616962929.0&end_timestamp=1617400199&kpis=direct_revenue&kpis=conversion_rate

Response JSON Object

warnings (list-of-string) – Optional. List of warnings
start_timestamps (list-of-float) – Start timestamps of buckets
kpis (list-of-object) –
Aligned KPIs
Inner fields
- kpi (string) – KPI name
- values (list-of-float) – Values
- aggregate (float) – Aggregated values over the entire time range

EXAMPLE RESPONSE¶

  {
      "start_timestamps": [
          1616889600.0, 1616976000.0, 1617062400.0, 1617148800.0, 1617235200.0,
          1617321600.0, 1617408000.0
      ],
      "kpis": [
          {
              "kpi": "direct_revenue",
              "aggregate": 18050,
              "values": [4500, 0, 1200, 3200, 3500, 2650, 3000]
          },
          {
              "kpi": "conversion_rate",
              "aggregate": 1.55,
              "values": [1.2, 2.5, 2., 2.3, 3.4, 3., 3.]
          }
      ]
  }

[Internal] Get Many Analytics Metrics Values¶

GET analytics/metrics/values/¶

Note

Authorized Roles: root, manager

Returns historical values for many analytics metrics.

Query Parameters

start_timestamp (float) – Optional. Start timestamp. Default: start of available data. Note that the response will return buckets that start at or before this requested timestamp.
end_timestamp (float) – Optional. End timestamp. Default: current timestamp. Note that the response will return buckets that end at or after this requested timestamp.
names (list-of-string) – Metric names

EXAMPLE QUERY PARAMS¶

  ?start_timestamp=1616962929.0&end_timestamp=1617400199

Response JSON Object

warnings (list-of-string) – Optional. List of warnings
start_timestamps (list-of-float) – Start timestamps of buckets
metrics (list-of-object) –
Metrics aggregate values and values aligned on start_timestamps
Inner fields
- name (string) – Metric name
- values (list-of-float) – Values

EXAMPLE RESPONSE¶

  {
      "start_timestamps": [
          1616889600.0, 1616976000.0, 1617062400.0, 1617148800.0, 1617235200.0,
          1617321600.0, 1617408000.0
      ],
      "metrics": [
          {
              "name": "direct_revenue",
              "values": [4500, 0, 1200, 3200, 3500, 2650, 3000]
          },
          {
              "name": "count_sessions_w_purchases",
              "values": [30, 0, 20, 25, 20, 15, 20]
          }
      ]
  }

[Internal] [DEPRECATED] List All Segmentation Params¶

GET analytics/segmentations/params/¶

Note

Authorized Roles: root, manager, backend

List all segmentations params

Response JSON Object

warnings (list-of-string) – Optional. List of warnings
segmentations (list-of-object) –
All segmentations
Inner fields
- warnings (list-of-string) – List of warnings
- id (string) – Analytics Segmentation unique ID
- name (string) – Segmentation name
- segmentation (object) – Segmentation

EXAMPLE RESPONSE¶

  {
      "segmentations": [
          {
              "id": "reg34te",
              "name": "my_seg1",
              "segmentation": {
                  "type": "ab_test",
                  "split": {
                      "ab_test_id": "my_ab_test1",
                      "group_a": {"type": "analytics"},
                      "group_b": {"type": "analytics"}
                  },
                  "skip": {"type": "analytics"}
              }
          }
      ]
  }

[Internal] [DEPRECATED] Create a Segmentation¶

POST analytics/segmentations/params/¶

Note

Authorized Roles: root, manager, backend

Create a segmentation.

Request JSON Object

name (string) – Segmentation name
segmentation (object) – Segmentation

EXAMPLE QUERY BODY¶

  {
      "name": "my_segm",
      "segmentation": {
          "type": "ab_test",
          "split": {
              "ab_test_id": "my_ab_test1",
              "group_a": {"type": "analytics"},
              "group_b": {"type": "analytics"}
          },
          "skip": {"type": "analytics"}
      }
  }

Response JSON Object

warnings (list-of-string) – Optional. List of warnings
id (string) – Analytics Segmentation unique ID

EXAMPLE RESPONSE¶

  {
      "id": "m4re346e"
  }

Errors:

DuplicatedError if name already used

[Internal] [DEPRECATED] Rename a Segmentation¶

PATCH analytics/segmentations/params/<str:segmentation_id>/¶

Note

Authorized Roles: root, manager, backend

Rename a segmentation.

Request JSON Object

name (string) – Segmentation new name

EXAMPLE QUERY BODY¶

  {
      "name": "my_segm24"
  }

Errors:

NotFoundError if segmentation ID is not found
DuplicatedError if name already used

[Internal] [DEPRECATED] Get Params of a Segmentation¶

GET analytics/segmentations/params/<str:segmentation_id>/¶

Note

Authorized Roles: root, manager, backend

Get a segmentation params

Response JSON Object

warnings (list-of-string) – Optional. List of warnings
id (string) – Analytics Segmentation unique ID
name (string) – Segmentation name
segmentation (object) – Segmentation

EXAMPLE RESPONSE¶

  {
      "id": "gwrt45i7",
      "name": "seg14",
      "segmentation": {
          "type": "ab_test",
          "split": {
              "ab_test_id": "my_ab_test1",
              "group_a": {"type": "analytics"},
              "group_b": {"type": "analytics"}
          },
          "skip": {"type": "analytics"}
      }
  }

Errors:

NotFoundError if segmentation is not found

[Internal] Delete a Segmentation¶

DELETE analytics/segmentations/params/<str:segmentation_id>/¶: Note

Authorized Roles: root, manager, backend

Delete an segmentation. Does not delete the A/B tests it points towards, if any.