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:

• One segment builder

• One audience feature.

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

200

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

200

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

200

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

200

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

200

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

200

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"

200

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