Audience segment metrics

Important If you're using the new segment metrics system, please check the dedicated documentation page for up-to-date information: segment metrics documentation

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.

The total number of user points is always calculated and displayed, even if there are no 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

{
    "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

{
    "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
    }
}

{
    "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" }

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

Limitations

Only five custom audience segment metrics per datamart are allowed—one per available technical name.
@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

PreviousSegment builders NextAudience segment feed

Last updated 10 days ago

Was this helpful?