# Audience features {% hint style="success" %} Audience features you create are available in the navigator, in **Audience** > **Builders** > **Standard**. {% endhint %} Let's take the following query as an example: ```sql SELECT @count{} FROM UserPoint WHERE events { nature = "$transaction_confirmed" and date >= $date and products {brand in $brand and name in $name} } ``` It is technically an OTQL query based on your schema in which you registered parameters**.** In this case, it represents a business feature that may be used regularly by your users: selecting UserPoint that perform a transaction in a particular date range and for specific products. Users will see this selector in the builder instead of an OTQL query. ![](https://4196284719-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MMuoqM-5hJ5JY0WnAKL%2F-MXfVmne9jmDfRhS6vaC%2F-MXffizH0-0WAWIV6Xxf%2FCapture%20d%E2%80%99e%CC%81cran%202021-04-07%20a%CC%80%2011.32.10.png?alt=media\&token=185efbec-d929-4c12-b126-e88015ceb111) This audience feature will automatically be combined with other audience features, which the user can select to create segments. ## The process Users will have access to the standard segment builder if at least one audience feature is set up. But you need multiple ones to create value for users. Good knowledge of the schema and the queries that are usually created in your datamart is important for the success of this feature. Here is a sample process to follow to enable audience features and create value for your users: 1. Know your schema. What is it optimized for? Which queries are regularly created? What are your actual segments and what are their queries? You should be able to create a list of useful audience features with these pieces of information. 2. Set up audience features, in the UI and/or by script. 3. Monitor usage and update audience features regularly! ## Folders You can store audience features in folders. Any audience feature without a folder will be assigned to the root folder. Here are some examples. ## List folders `GET` `https://api.mediarithmics.com/v1/datamarts/{datamart_id}/audience_feature_folders` #### Path Parameters | Name | Type | Description | | ------------ | ------- | ---------------------- | | datamart\_id | integer | The ID of the datamart | {% tabs %} {% tab title="200 " %} ```javascript { "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 } ``` {% endtab %} {% endtabs %} ## List one folder `GET` `https://api.mediarithmics.com/v1/datamarts/{datamart_id}/audience_feature_folders/{audience_feature_folders_id}` #### Path Parameters | Name | Type | Description | | ------------------------------ | ------- | ---------------------- | | audience\_feature\_folders\_id | integer | The ID of the folder | | datamart\_id | integer | The ID of the datamart | {% tabs %} {% tab title="200 " %} ```javascript { "status": "ok", "data": { "id": "string", "children_ids": [ "string" ], "audience_features_ids": [ "string" ], "parent_id": "string", "datamart_id": "string", "name": "string" } } ``` {% endtab %} {% endtabs %} ## Create a folder `POST` `https://api.mediarithmics.com/v1/datamarts/{datamart_id}/audience_feature_folders` #### Path Parameters | Name | Type | Description | | ---------------------------------------------- | ------- | ---------------------- | | datamart\_id\* | integer | The ID of the datamart | #### Request Body | Name | Type | Description | | -------------------------------------- | ------ | ----------------------------------------------- | | children\_ids | array | IDs of folder's children | | audience\_features\_ids | array | IDs of audience features attached to the folder | | parent\_id | string | The ID of the folder's parent | | datamart\_id | string | The ID of the datamart | | name\* | string | The name of the folder | {% tabs %} {% tab title="200 " %} ``` ``` {% endtab %} {% endtabs %} ```javascript // Create a folder payload { "children_ids": [ "string" ], "audience_features_ids": [ "string" ], "parent_id": "string", "datamart_id": "string", "name": "string" } ``` ## Edit a folder `PUT` `https://api.mediarithmics.com/v1/datamarts/{datamart_id}/audience_feature_folders/{audience_feature_folders}` #### Path Parameters | Name | Type | Description | | ---------------------------------------------------------------- | ------- | ------------------------------------- | | datamart\_id\* | integer | The ID of the datamart | | audience\_feature\_folders\_id\* | integer | The ID of the audience feature folder | #### Request Body | Name | Type | Description | | -------------------------------------- | ------ | ----------------------------------------------- | | children\_ids | array | IDs of folders's children | | audience\_features\_ids | array | IDs of audience features attached to the folder | | parent\_id | string | The ID of the folder's parent | | datamart\_id | string | The ID of the datamart | | name\* | string | The name of the folder | {% tabs %} {% tab title="200 " %} ``` { "status": "ok", "data": { "id": "string", "children_ids": [ "string" ], "audience_features_ids": [ "string" ], "parent_id": "string", "datamart_id": "string", "name": "string" } } ``` {% endtab %} {% endtabs %} ```javascript // Editing a folder payload { "children_ids": [ "string" ], "audience_features_ids": [ "string" ], "parent_id": "string", "datamart_id": "string", "name": "string" } ``` ## Audience features ## List audience features `GET` `https://api.mediarithmics.com/v1/datamarts/{datamart_id}/audience_features` #### Path Parameters | Name | Type | Description | | ------------ | ------- | ---------------------- | | datamart\_id | integer | The ID of the datamart | {% tabs %} {% tab title="200 " %} ```javascript { "first_result": 0, "total": 0, "count": 0, "data": [ { "object_tree_expression": "string", "description": "string", "id": "string", "variables": [ { "field_name": "string", "data_type": "string", "reference_model_type": "string", "type": "string", "parameter_name": "string", "path": [ "string" ], "reference_type": "string", "directive": "string", "container_type": "string" } ], "token": "string", "datamart_id": "string", "addressable_object": "string", "name": "string", "folder_id": "string", "creation_date": 0 } ], "max_results": 0, "status": "ok" } ``` {% endtab %} {% endtabs %} ## Get an audience feature `GET` `https://api.mediarithmics.com/v1/datamarts/{datamart_id}/audience_features/{audience_feature_id}` #### Path Parameters | Name | Type | Description | | --------------------- | ------- | ------------------------------ | | audience\_feature\_id | integer | The ID of the audience feature | | datamart\_id | integer | The ID of the datamart | {% tabs %} {% tab title="200 " %} ```javascript { "status": "ok", "data": { "object_tree_expression": "string", "description": "string", "id": "string", "variables": [ { "field_name": "string", "data_type": "string", "reference_model_type": "string", "type": "string", "parameter_name": "string", "path": [ "string" ], "reference_type": "string", "directive": "string", "container_type": "string" } ], "token": "string", "datamart_id": "string", "addressable_object": "string", "name": "string", "folder_id": "string", "creation_date": 0 } } ``` {% endtab %} {% endtabs %} ## Create an audience feature `POST` `https://api.mediarithmics.com/v1/datamarts/{datamart_id}/audience_features` #### Path Parameters | Name | Type | Description | | ------------ | ------- | ---------------------- | | datamart\_id | integer | The ID of the datamart | #### Request Body | Name | Type | Description | | ------------------------ | ------ | -------------------------------------------------------------------------------------------------------------- | | object\_tree\_expression | string | The **WHERE** statement of the query associated to the audience feature | | description | string | The description of your audience feature | | datamart\_id | string | The ID of the datamart | | addressable\_object | string | The **SELECT** statement of the query associated to the audience feature. It must always set at **UserPoint**. | | name | string | The name of the audience feature | | folder\_id | string | The ID of folder where the audience feature is stored | {% tabs %} {% tab title="200 " %} ```javascript { "status": "ok", "data": { "object_tree_expression": "string", "description": "string", "id": "string", "variables": [ { "field_name": "string", "data_type": "string", "reference_model_type": "string", "type": "string", "parameter_name": "string", "path": [ "string" ], "reference_type": "string", "directive": "string", "container_type": "string" } ], "token": "string", "datamart_id": "string", "addressable_object": "string", "name": "string", "folder_id": "string", "creation_date": 0 } } ``` {% endtab %} {% endtabs %} ```javascript // Creating an audience feature payload { "object_tree_expression": "string", "description": "string", "datamart_id": "string", "addressable_object": "string", "name": "string", "folder_id": "string" } ``` ## Edit an audience feature `PUT` `https://api.mediarithmics.com/v1/datamarts/{datamart_id}/audience_features/{audience_feature_id}` #### Path Parameters | Name | Type | Description | | --------------------- | ------- | -------------------------------------- | | audience\_feature\_id | integer | The ID of the audience feature to edit | | datamart\_id | integer | The ID of the datamart | #### Request Body | Name | Type | Description | | ------------------------ | ------ | -------------------------------------------------------------------------------------------------------------- | | object\_tree\_expression | string | The **WHERE** statement of the query associated to the audience feature | | description | string | The description of your audience feature | | datamart\_id | string | The ID of the datamart | | addressable\_object | string | The **SELECT** statement of the query associated to the audience feature. It must always set at **UserPoint**. | | name | string | The name of the audience feature | | folder\_id | string | The ID of folder where the audience feature is stored | {% tabs %} {% tab title="200 " %} ```javascript { "status": "ok", "data": { "object_tree_expression": "string", "description": "string", "id": "string", "variables": [ { "field_name": "string", "data_type": "string", "reference_model_type": "string", "type": "string", "parameter_name": "string", "path": [ "string" ], "reference_type": "string", "directive": "string", "container_type": "string" } ], "token": "string", "datamart_id": "string", "addressable_object": "string", "name": "string", "folder_id": "string", "creation_date": 0 } } ``` {% endtab %} {% endtabs %} ```javascript // Editing an audience feature payload { "object_tree_expression": "string", "description": "string", "datamart_id": "string", "addressable_object": "string", "name": "string", "folder_id": "string" } ``` ## OTQL query rules ### Parameters Create query parameters using the `$parameter_name`syntax. Example: ```sql // The gender will be selectable by the user SELECT @count{} FROM UserPoint where profiles {gender in $gender} // The date will be selectable by the user, // but the nature will always be $transaction_confirmed SELECT @count{} FROM UserPoint where events { nature = "$transaction_confirmed" and date >= $date } ``` The field in the audience feature will have the name you enter after the `$` . Spaces in field name are not authorized. The type of selector in the audience feature is automatically chosen based on the field type If you want to be able to select several values in a field, use keyword `in` instead of the classic `==`. ```sql // User will only be able to select one gender SELECT @count{} FROM UserPoint where profiles {gender == $gender} // User will be able to select multiple gender values SELECT @count{} FROM UserPoint where profiles {gender in $gender} ``` You can create parameters for frequency requests with the `@ScoreSum` directive: ```sql // User will be able to select the minimum number of transactions SELECT @count{} FROM UserPoint WHERE events@ScoreSum(min: $frequency) { purchase in $user_purchase } ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://developer.mediarithmics.io/advanced-usages/audiences/audience-features.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.