Funnel API

The Data Studio > Funnel page in the navigator uses an API that you can leverage to analyze funnel conversions in your own tools. For more information on the feature, see Funnel.

Retrieve dimensions values autocomplete

POST https://api.mediarithmics.com/v1/datamarts/:datamartId/user_activities_analytics

Use this call to get suggestions or autocomplete values for a dimension

Query Parameters

Name	Type	Description
datamartId	number	The ID of the datamart

Request Body

Name	Type	Description
metrics	array	Empty array
dimension_filter_clauses	object	Dimensions filters clause to apply.
dimensions	array	Names of the dimensions to retrieve. Usually only one dimension.Use multiple dimensions to get possible values of a dimension if the other dimension is set. For example, using the dimensions TYPE and EVENT_TYPE we can ask for the possible values of EVENT_TYPE if TYPE is SITE_VISIT.
date_ranges	array	Periods to analyze. Each date range is an object with a start_date and an end_date.

200

{
    "status": "ok",
    "data": {
        "report_view": {
            "items_per_page": 100,
            "total_items": 7,
            "columns_headers": [
                "type"
            ],
            "rows": [
                [
                    "DISPLAY_AD"
                ],
                [
                    "EMAIL"
                ],
                [
                    "SITE_VISIT"
                ],
                [
                    "USER_SCENARIO_NODE_ENTER"
                ],
                [
                    "USER_SCENARIO_NODE_EXIT"
                ],
                [
                    "USER_SCENARIO_START"
                ],
                [
                    "USER_SCENARIO_STOP"
                ]
            ]
        }
    }
}

Here is a sample body payload

{
  "date_ranges": [
    {
      "start_date": "2021-04-22T00:00:00",
      "end_date": "2021-04-29T23:59:59"
    }
  ],
  "dimensions": [
    {
      "name": "TYPE"
    }
  ],
  "dimension_filter_clauses": {
    "operator": "OR", // OR or AND
    "filters": [
      {
        "dimension_name": "TYPE",
        "operator": "LIKE", // LIKE, EXACT or IN_LIST
        "expressions": [
          ""
        ]
      }
    ]
  },
  "metrics": []
}

Submit a funnel for results

POST https://api.mediarithmics.com/v1/datamarts/:datamartId/user_analytics_funnel

Path Parameters

Name	Type	Description
datamartId	number	The ID of the datamart

Request Body

Name	Type	Description
limit	number	When spliting a step on a specific field, sets the maximum values to be retrieved to optimize the query with what would be displayed.For example, set to 5 if you only show the 5 best channel IDs in the UI when splitting by channel ID to optimize the query.
in	object	Period to query the funnel. Should be in the last 4 months maximum.
for	object	List of steps in the funnel

200

{
    "status": "ok",
    "data": {
        "global": {
            "total": 879879879,
            "steps": [
                {
                    "name": "Step 1",
                    "count": 546546546,
                    "interaction_duration": 0
                },
                {
                    "name": "Step 2",
                    "count": 897987984651,
                    "amount": 1213213.27,
                    "conversion": 11221,
                    "interaction_duration": 515151
                }
            ]
        },
        "grouped_by": []
    }
}

Here is a sample payload:

{
  "for": [
    {
      "name": "Step 1",
      "filter_clause": {
        "operator": "OR",
        "filters": [
          {
            "dimension_name": "TYPE",
            "not": false,
            "operator": "EXACT",
            "expressions": [
              "DISPLAY_AD"
            ]
          }
        ]
      }
    },
    {
      "name": "Step 2",
      "filter_clause": {
        "operator": "AND",
        "filters": [
          {
            "dimension_name": "EVENT_TYPE",
            "not": false,
            "operator": "EXACT",
            "expressions": [
              "$transaction_confirmed"
            ]
          },
          {
            "dimension_name": "CHANNEL_ID",
            "not": false,
            "operator": "IN_LIST",
            "expressions": [
              "8888",
              "6666"
            ]
          }
        ]
      }
    }
  ],
  "in": {
    "type": "DATES",
    "start_date": "2021-04-23",
    "end_date": "2021-05-01"
  },
  "limit": 5
}

Dimensions

You can build queries with the following dimensions:

• Activity Date DATE_TIME

• Activity Type TYPE

• Ad Group Id ORIGIN_SUB_CAMPAIGN_ID

• Brand BRAND

• Channel Id CHANNEL_ID

• Campaign Id ORIGIN_CAMPAIGN_ID

• Category 1 CATEGORY1

• Category 2 CATEGORY2

• Category 3 CATEGORY3

• Category 4 CATEGORY4

• Creative Id ORIGIN_CREATIVE_ID

• Device Brand DEVICE_BRAND

• Device Browser DEVICE_BROWSER_FAMILY

• Device Carrier DEVICE_CARRIER

• Device Form Factor DEVICE_FORM_FACTOR

• Device Model DEVICE_MODEL

• Device OS DEVICE_OS_FAMILY

• Has conversion HAS_CONVERSION

• Has clicked HAS_CLICKED

• Has bounced HAS_BOUNCED

• Event type EVENT_TYPE

• Is in segment SEGMENT_ID

• Campaign Id CAMPAIGN_ID

• Goal Id GOAL_ID

• Product Id PRODUCT_ID

Dimensions filters clause

This object represents a group of filters to apply in a request.

It has:

• An operator field to apply either an AND or an OR between the filters

• A filters array for the list filters to apply. For more information, see Dimensions filters.

"filter_clause": {
  "operator": "OR", // OR or AND
  "filters": [
    ...
  ]
}

Dimensions filter

This object represents a filter in a filters clause.

It has;

• A dimensions_name field to select the dimension it applies on. For more information, see Dimensions.

• A not boolean field to apply boolean logic

• An operator field to select one of the following queries:

  • EXACT will force the dimension to match the first expression set

  • LIKE will allow the dimension to only contain the first expression set

  • IN_LIST will allow the dimension to be one of the expressions set

• A list of expressions representing the keywords to search for.

Examples

 // TYPE should be DISPLAY_AD
 {
    "dimension_name": "TYPE",
    "not": false,
    "operator": "EXACT",
    "expressions": [
      "DISPLAY_AD"
    ]
  }

// TYPE should contain SITE
// SITE_VISIT activities will be used
 {
    "dimension_name": "TYPE",
    "not": false,
    "operator": "LIKE",
    "expressions": [
      "SITE"
    ]
  }

// TYPE should not contain SITE
{
  "dimension_name": "TYPE",
  "not": true,
  "operator": "LIKE",
  "expressions": [
    "SITE"
  ]
}

// CHANNEL_ID should be either 8888 or 6666
{
  "dimension_name": "CHANNEL_ID",
  "not": false,
  "operator": "IN_LIST",
  "expressions": [
    "8888",
    "6666"
  ]
}