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
}

// 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 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

// 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
  }
}

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'