Segment builders

You have access to three tools to segment your audience using queries:

  • Leverage audience features to build your queries in the standard segment builder (Audience > Builders > Standard). Once set up, this is the preferred solution for fast queries building and visualising the segment in a dashboard before saving it.

  • Drag and drop fields from your schema into a visual OTQL query builder with the advanced segment builder (Audience > Builders > Advanced). It doesn't require any setup but requires knowledge about the schema. May not be the best option for casual users.

  • Build OTQL queries directly in Data Studio > Query tool. This requires a solid knowledge of your schema and OTQL.

Standard segment builder set up

You enable this feature when you set up at least:

You can set up multiple segment builder to create templates once you identify common segment queries that you often use.

Each segment builder has a list of default audience features that are automatically used in it.

You can create and edit segment builders through the UI by going to Settings > Datamart > Your datamart > Segment builders. You can also manage them by API.

List standard segment builders

GET https://api.mediarithmics.com/v1/datamarts/{datamart_id}/audience_builders

Path Parameters

Name
Type
Description

datamart_id

integer

The ID of the datamart

{
  "first_result": 0,
  "count": 0,
  "max_results": 0,
  "status": "ok",
  "data": [
    {
      "id": "string",
      "children_ids": [
        "string"
      ],
      "audience_features_ids": [
        "string"
      ],
      "parent_id": "string",
      "datamart_id": "string",
      "name": "string"
    }
  ],
  "total": 0
}

Get a standard segment builder

GET https://api.mediarithmics.com/v1/datamarts/{datamart_id}/audience_builders/{audience_builders_id}

Path Parameters

Name
Type
Description

datamart_id

integer

The ID of the datamart

audience_builders_id

integer

The ID of standard segment builder you want to get

Create a standard segment builder

POST https://api.mediarithmics.com/v1/datamarts/{datamart_id}/audience_builders

Path Parameters

Name
Type
Description

datamart_id

integer

The ID of the datamart

Request Body

Name
Type
Description

datamart_id

string

The ID of the datamart

demographics_features_ids

array

Array of string: the IDs of audience features you want to link to your standard segment builder. These audience features will always be selected in the builder.

name

string

Name of the standard segment builder

{
  "first_result": 0,
  "count": 0,
  "max_results": 0,
  "status": "ok",
  "data": [
    {
      "id": "string",
      "children_ids": [
        "string"
      ],
      "audience_features_ids": [
        "string"
      ],
      "parent_id": "string",
      "datamart_id": "string",
      "name": "string"
    }
  ],
  "total": 0
}

List standard segment builders

GET https://api.mediarithmics.com/v1/datamarts/{datamart_id}/audience_builders

Path Parameters

Name
Type
Description

datamart_id

integer

GLLBBPYmcMbn

Get a standard segment builder

GET https://api.mediarithmics.com/v1/datamarts/{datamart_id}/audience_builders/{audience_builders_id}

Path Parameters

Name
Type
Description

datamart_id

integer

EACXzNpxesGA

audience_builders_id

integer

y1iztafbxNOl

Create a standard segment builder

POST https://api.mediarithmics.com/v1/datamarts/{datamart_id}/audience_builders

Path Parameters

Name
Type
Description

datamart_id

integer

UpWZubSJk7SC

Request Body

Name
Type
Description

datamart_id

string

ZdvK39oPj25k

demographics_features_ids

array

Zu89g8D3qu6m

name

string

bpFIx0HWRbci

// Create a standard segment builder payload
{
  "datamart_id": "string",
  "demographics_features_ids": [
    "string"
  ],
  "name": "string"
}

You cannot create more than 20 standard segment builder instances per datamart.

Edit a standard segment builder

PUT https://api.mediarithmics.com/v1/datamarts/{datamart_id}/audience_builders/{audience_builders_id}

Path Parameters

Name
Type
Description

audience_builders_id

integer

The ID of the standard segment builder to edit

datamart_id

integer

The ID of the datamart

Request Body

Name
Type
Description

datamart_id

string

The ID of the datamart

demographics_features_ids

string

Array of string: The IDs of audience features you want to link to your standard segment builder. These audience features will always be selected in the builder.

name

string

The name of the standard segment builder

Edit a standard segment builder

PUT https://api.mediarithmics.com/v1/datamarts/{datamart_id}/audience_builders/{audience_builders_id}

Path Parameters

Name
Type
Description

audience_builders_id

integer

aIhsvJpgK6ny

datamart_id

integer

TTSN6yxr96WI

Request Body

Name
Type
Description

datamart_id

string

N2N4Y3WHqATi

demographics_features_ids

string

1EsZV25xtbUt

name

string

xsAiWSvKY437

// Edit a standard segment builder payload
{
  "datamart_id": "string",
  "demographics_features_ids": [
    "string"
  ],
  "name": "string"
}

Dashboards API

This API helps you upload dashboards.

List dashboards for standard segment builder

GET https://api.mediarithmics.com/v1/data_file/data?uri=mics://data_file/tenants/{organisation_id}/dashboards/{datamart_id}/AUDIENCE_BUILDER-{audience_builder_id}.json

Path Parameters

Name
Type
Description

organisation_id

integer

The ID of the organisation

datamart_id

integer

The ID of the datamart

audience_builder_id

integer

The ID of the standard segment builder on which you want to upload dashboards

Create & edit dashboards for standard segment builder

PUT https://api.mediarithmics.com/v1/data_file/data?uri=mics://data_file/tenants/{organisation_id}/dashboards/{datamart_id}/AUDIENCE_BUILDER-{audience_builder_id}.json

Path Parameters

Name
Type
Description

organisation_id

integer

The ID of the organization

datamart_id

integer

The ID of the datamart

audience_builder_id

integer

The ID of the standard segment builder on which you want to upload dashboards

List dashboards for standard segment builder

GET https://api.mediarithmics.com/v1/data_file/data?uri=mics://data_file/tenants/{organisation_id}/dashboards/{datamart_id}/AUDIENCE_BUILDER-{audience_builder_id}.json

Path Parameters

Name
Type
Description

organisation_id

integer

xpvJF5g4SpwP

datamart_id

integer

uqK1nIMmTAn6

audience_builder_id

integer

cZe7evLowSbp

Create & edit dashboards for standard segment builder

PUT https://api.mediarithmics.com/v1/data_file/data?uri=mics://data_file/tenants/{organisation_id}/dashboards/{datamart_id}/AUDIENCE_BUILDER-{audience_builder_id}.json

Path Parameters

Name
Type
Description

organisation_id

integer

UFX1xf9M0BWy

datamart_id

integer

uhpUbCPUJ0Gm

audience_builder_id

integer

5Rm1gDwXgxFe

// Create a dashboard payload example
[
  {
      "id": "1",
      "name": "Standard segment builder",
      "type": "AUDIENCE_BUILDER",
      "datamart_id": "xxxx",
      "components": [
        {
          "layout": {
            "h": 1,
            "static": false,
            "w": 6,
            "x": 0,
            "y": 0
          },
          "component": {
            "id": 2,
            "component_type": "COUNT",
            "title": "User Profiles",
            "query_id": "22252"
          }
        },
        {
          "layout": {
            "h": 1,
            "static": false,
            "w": 6,
            "x": 6,
            "y": 0
          },
          "component": {
            "id": 2,
            "component_type": "COUNT",
            "title": "User Cookies",
            "query_id": "22264"
          }
        },
        {
          "layout": {
            "h": 3,
            "static": false,
            "w": 12,
            "x": 0,
            "y": 1
          },
          "component": {
            "id": 5,
            "component_type": "MAP_BAR_CHART",
            "title": "Genre",
            "show_legend": true,
            "query_id": "47031",
            "sortKey": "A-Z",
            "percentage": true,
            "labels": {
              "enable": true,
              "filterValue": "",
              "format": "{point.y}%"
            },
            "tooltip": {
              "formatter": "{point.y}% ({point.count})"
            }
          }
        },
        {
          "layout": {
            "h": 3,
            "static": false,
            "w": 12,
            "x": 0,
            "y": 4
          },
          "component": {
            "id": 5,
            "component_type": "COUNT_BAR_CHART",
            "labels_enabled": true,
            "plot_labels": [
              "Email",
              "Print",
              "Sms",
              "Tel",
              "Web",
              "App"
            ],
            "title": "Contactabilité",
            "show_legend": false,
            "query_ids": [
              "47033",
              "47034",
              "47035",
              "47036",
              "47037",
              "47038"
            ]
          }
        }
      ]
    }
]

Final values import

In ordre to be able to select audience features thanks to final values, you should first import your final values thanks to a csv file. For more information about the search by final feature, please read the search by final value feature guider.

Requirements

Your csv file should have:

  • The following format: 1 level min and 8 levels max, final_value,

level1,level2, ... ,final_value

Example

level1,level2,level3,level4,final_value
activities,channel_id,,,my channel id1
segments,creation_ts,,,123
...

Don't need to specify UserPoint for the level1, it's implicit.

  • A maximum of 100 000 lines, each line should match your schema,

  • Final values' field of type String or [String].

API

Upload final values csv file

POST https://api.mediarithmics.com/v1/datamarts/{datamart_id}/reference_table_job_executions

Path Parameters

Name
Type
Description

datamart_id

integer

The ID of the datamart

Request Body

Name
Type
Description

file

string

The name of the file you want to import. Ex: "@final_value_file.csv"

{
  "status": "ok",
  "data": {
    "parameters": null,
    "result": null,
    "error": null,
    "id": "xxxxxx",
    "status": "PENDING",
    "creation_date": 1634134417792,
    "start_date": null,
    "duration": null,
    "organisation_id": "xxxx",
    "user_id": "xxxx",
    "cancel_status": null,
    "debug": null,
    "is_retryable": false,
    "num_tasks": null,
    "completed_tasks": null,
    "erroneous_tasks": null,
    "retry_count": 0,
    "permalink_uri": null,
    "job_type": "REFERENCE_TABLE",
    "import_mode": "MANUAL_FILE",
    "import_type": null
  }
}

Upload final values csv file

POST https://api.mediarithmics.com/v1/datamarts/{datamart_id}/reference_table_job_executions

Path Parameters

Name
Type
Description

datamart_id

integer

Od2HfDMVLPel

Request Body

Name
Type
Description

file

string

kUYOfU4QZxF3

Example

curl -k --location --request POST 'https://api.mediarithmics.com/v1/datamarts/{datamart_id}/reference_table_job_executions' \
-H 'Content-Type: text/csv' \
-H 'Authorization: TOKEN' \
--data-binary '@./final_value_file.csv'

Last updated

Was this helpful?