Audience segment metrics

Audience segment metrics are a way to offer custom metrics on segments to users. They are visible on the segment listing and segment details pages.

The value of each metric is calculated regularly for each segment and saved to offer a historic view of its values.

Segment details page on a datamart with 2 custom audience segment metrics

The total number of user points is always calculated and displayed, even if there are no custom metrics.

A segment view without custom metrics

How to configure metrics

Audience segment metrics are configured per datamart and built on top of OTQL queries.

Each metric has:

• An associated OTQL Query
• A technical name, possible values being emails, user_accounts, desktop_cookie_ids, mobile_cookie_ids or mobile_ad_ids. You can't use a custom value, and each of these values can only be used once per datamart.

• A display name shown in the UI

• A status: DRAFT, LIVE or ARCHIVED.

• An icon, from a set of possible icons.

The metrics calculate how many user points in the segment have at least one record. It doesn't count the number of records in the segment.

If you add a metric that counts the number of cookies and a user point is associated with multiple cookies in the platform, it will be counted as only a +1 and not a +2.

The metrics values will always be lower or equal to the number of user points in the segment.

A metric goes from DRAFT status to LIVE and from LIVE status to ARCHIVED. You cannot republish an ARCHIVED metric. You can only remove it.

Listing existing metrics

GET https://api.mediarithmics.com/v1/datamarts/:datamartId/audience_segment_metrics

Path Parameters

Name	Type	Description
datamartId	string	The ID of the datamart

200

{
    "status": "ok",
    "data": [
        {
            "id": "1555",
            "datafarm_key": "DF_EU_2020_02",
            "datamart_id": "1509",
            "query_id": "50659",
            "technical_name": "user_accounts",
            "display_name": "User Profiles",
            "icon": "users",
            "status": "LIVE",
            "creation_date": 1613125152462,
            "last_modified_date": 1613125152462,
            "last_published_date": null
        },
        {
            "id": "1558",
            "datafarm_key": "DF_EU_2020_02",
            "datamart_id": "1509",
            "query_id": "50659",
            "technical_name": "mobile_cookie_ids",
            "display_name": "User Profiles",
            "icon": "users",
            "status": "LIVE",
            "creation_date": 1613125314757,
            "last_modified_date": 1613125314757,
            "last_published_date": null
        },
        {
            "id": "1566",
            "datafarm_key": "DF_EU_2020_02",
            "datamart_id": "1509",
            "query_id": "50659",
            "technical_name": "mobile_ad_ids",
            "display_name": "User Profiles 7",
            "icon": "users",
            "status": "ARCHIVED",
            "creation_date": 1613128930707,
            "last_modified_date": 1613128930707,
            "last_published_date": null
        },
        {
            "id": "1569",
            "datafarm_key": "DF_EU_2020_02",
            "datamart_id": "1509",
            "query_id": "50659",
            "technical_name": "desktop_cookie_ids",
            "display_name": "User Profiles 4",
            "icon": "gears",
            "status": "LIVE",
            "creation_date": 1613129103522,
            "last_modified_date": 1613129103522,
            "last_published_date": null
        },
        {
            "id": "1570",
            "datafarm_key": "DF_EU_2020_02",
            "datamart_id": "1509",
            "query_id": "50659",
            "technical_name": "desktop_cookie_ids",
            "display_name": "User Profiles 4",
            "icon": "gears",
            "status": "DRAFT",
            "creation_date": 1613129261878,
            "last_modified_date": 1613129261878,
            "last_published_date": null
        }
    ],
    "count": 5,
    "total": 5,
    "first_result": 0,
    "max_result": 50,
    "max_results": 50
}

Create an audience metric

POST https://api.mediarithmics.com/v1/datamarts/:datamartId/audience_segment_metrics

This creates a DRAFT metric.

Path Parameters

Name	Type	Description
datamartId	integer	The ID of the datamart

Request Body

Name	Type	Description
Body	object	The metric you wish to create

200

{
    "status": "ok",
    "data": {
        "id": "1571",
        "datafarm_key": "DF_EU_2020_02",
        "datamart_id": "1509",
        "query_id": "50659",
        "technical_name": "emails",
        "display_name": "User Profiles 7",
        "icon": "users",
        "status": "DRAFT",
        "creation_date": 1613130322659,
        "last_modified_date": 1613130322659,
        "last_published_date": null
    }
}

400 If values are not valid

{
    "status": "error",
    "error": "Json object is not structured as expected",
    "error_code": "BAD_REQUEST_FORMAT",
    "error_id": "e18c26a1-7497-470d-8480-2bcb66fc8f16"
}

You must first create an OTQL query, returning a number corresponding to your metric. As each datamart can have its very own schema, those queries should be tested for each datamart (by API or in the Data Studio) and should return a number. The configured query will be "merged" with the query of each segment to calculate the proper metric.

Here are some common query examples:

• SELECT @count{id} FROM UserPoint WHERE agents{} counts the number of user points having at least 1 cookie or mobile ID (user agent)

• SELECT @count{id} FROM UserPoint WHERE profiles{} counts the number of user points having at least 1 profile

• SELECT @count{id} FROM UserPoint WHERE emails{} counts the number of user points having at least 1 email

Here is a sample body payload:

{
    "datamart_id": "<<DATAMART ID>>",
    "query_id": "<OTQL QUERY ID>", 
    "technical_name": "<TECHNICAL_NAME>", 
    "display_name": "User Profiles",
    "icon": "users"
}

Activate the audience metric

POST https://api.mediarithmics.com/v1/datamarts/:datamartId/audience_segment_metrics/:metricId/action

This action transitions the metric go from DRAFT to LIVE.status. Any existing metric in LIVE status with the same technical name is ARCHIVED.

Path Parameters

Name	Type	Description
datamartId	integer	The ID of the datamart
metricId	integer	The ID of the metric to publish

Request Body

Name	Type	Description
Body	object	{ "action": "PUBLISH" }

200

Remove an audience metric

DELETE https://api.mediarithmics.com/v1/datamarts/:datamartId/audience_segment_metrics/:metricId

Path Parameters

Name	Type	Description
datamartId	integer	The ID of the datamart
metricId	integer	The ID of the metric to remove

200

Limitations

1. Only five custom audience segment metrics per datamart are allowed—one per available technical name.

2. @cardinality aggregations are not supported in the queries.

Available icons

Each metric is associated with an icon taken from the following catalogue.

Most used icons

• display

• users

• email-inverted

• phone

Other icons

• adGroups

• ads

• automation

• bell

• bolt

• check-rounded-inverted

• check-rounded

• check

• chevron-right

• chevron

• close-big

• close-rounded

• close

• code

• creative

• data

• delete

• display

• dots

• download

• email-inverted

• email

• extend

• filters

• full-users

• file

• gears

• goals-rounded

• goals

• image

• info

• laptop

• library

• magnifier

• menu-close

• minus

• optimization

• options

• partitions

• pause

• pen

• phone

• play

• plus

• query

• question

• refresh

• settings

• smartphone

• status

• tablet

• user

• users

• user-query

• user-pixel

• user-list

• video

• warning