Walkthrough

This documentation is about an Early Adopter feature and the instructions detailled here are subject to changes. Please contact your usual AB Tasty contact if some instructions are unclear or if something is missing.

Introduction

To help you understand how to use the Data Explorer API, you will find in this page a progressive walkthrough with use cases from the easiest to the most complex.

We will use the documentation about metrics and dimensions and how to build a query as a reference.

Setup your environement

First things first, you need to get a valid token to request the API. Documentation for AB Tasty.

Then, you will create your request on POST https://api-data-explorer.abtasty.com/v2/clients/{{account_identifier}}/query with the account_identifier being the identifier of your account. For example, for AB Tasty, it will be a 5 digits number, eg. 245637.

Two headers must be set: Content-Type and Authorization.

Our first request

A payload must be composed of at last two things: a date range and a metric. For our first request, I am simply going to ask for the number of sessions within two timestamps. I am also adding a limit instruction that will limit the amount of rows at 10. Except for a few use cases, I will keep this limit for all my requests for the readability of the output, but also because I don't need to get more than 10 results.

Request payload

{
  "timeIntervals": [
    {
      "start": "1672621200",
      "end": "1673571600"
    }
  ],
  "metrics": [
    {
      "key": "sessions"
    }
  ],
  "limit": "10"
}

How many sessions do I had between 1672621200 and 1673571600?

Result output

Adding metrics

I can add as many metrics as I want, this help me get data about my audiences between the two dates. Metrics are values that are being computed on the go based on the content of your request.

Request payload

In addition of the sessions, I want to know how many pageviewsPerSession and pageviews I had within the same time range.

{
  "timeIntervals": [
    {
      "start": "1672621200",
      "end": "1673571600"
    }
  ],
  "metrics": [
    {
      "key": "sessions"
    },
    {
        "key": "pageviewsPerSession"
    },
    {
        "key": "pageviews"
    }
  ],
  "limit": "10"
}

Result output

Adding dimensions

Dimensions are your solution to ventilate your data using information that was used to enrich each hit sent to the collect. Each hit comes with a set of parameters. Some are automatically sent (if you are using our JS tag or a SDK), some must be manually specified. But all of them are used to add more information about the hit you are sending. These dimensions are unstackable values such as device, browser name, geolocation or transaction revenue.

Using the city dimension, I am to see the number of sessions I have per city.

Request payload

This will give me a list of cities and their corresponding number of sessions.

{
  "timeIntervals": [
    {
      "start": "1672621200",
      "end": "1673571600"
    }
  ],
  "dimensions": [
      "city"
  ],
  "metrics": [
    {
      "key": "sessions"
    }
  ],
  "limit": "10"
}

Result output

Ordering the results

I am not very happy with the previous result as it seems I got the result in a random order and since I only ask for the first 10, it doesn't bring much value to me. I could increase the limit value until I see I get all the possible values and then process it in a third party tool, but that would be cumbersome. Also, I'm only interested into the top 10 cities.

What I can do, is to add an orderBy instruction to order the list.

Request payload

Here, I am ordering my result using the sessions field and on the descendant direction (to get the top 10 cities).

{
  "timeIntervals": [
    {
      "start": "1672621200",
      "end": "1673571600"
    }
  ],
  "dimensions": [
      "city"
  ],
  "metrics": [
    {
      "key": "sessions"
    }
  ],
  "orderBy": [
      {
          "field": "sessions",
          "direction": "DESC"
      }
  ],
  "limit": "10"
}

Result output

Adding several dimensions and metrics

Of course, you can add as many dimensions and metrics you want. But the more you will ask for, the more ventilated your result will be and it might start to be complicated to analyze. However, in conjonction with a third party analytics tool, this will help you having a very granular view of your data.

Request payload

I am adding device, campaignId, eventAction as dimensions and users as new metric to the previous request.

{
  "timeIntervals": [
    {
      "start": "1672621200",
      "end": "1673571600"
    }
  ],
  "dimensions": [
      "city",
      "device",
      "campaignId",
      "eventAction"
  ],
  "metrics": [
    {
      "key": "sessions"
    },
    {
        "key": "users"
    }
  ],
  "orderBy": [
      {
          "field": "sessions",
          "direction": "DESC"
      }
  ],
  "limit": "10"
}

Result output

Introduction to transactions

Let's switch to another type of request and go get some transactionnal data. Using the transaction tag or simply a transaction hit, you are able to send data about the transactions that occur during your experiments.

Request payload

On this request, I am simply getting the amount of users and transactions per affiliation. The affiliation is your way to gather your transaction hits into one single transaction goal in the reporting.

{
  "timeIntervals": [
    {
      "start": "1672621200",
      "end": "1673571600"
    }
  ],
  "dimensions": [
      "affiliation"
  ],
  "metrics": [
    {
        "key": "users"
    },
    {
        "key": "transactions"
    }
  ],
  "limit": "10"
}

Result output

Our first filter

and introduction to session-scope and hit-scope

Of course, filters can be added to the payload allowing you to select exactly the population or the data you are interested in. There are three levels of filters within Data Explorer and you can find the raw definition here. We will start with a first layer of filter allowing us to select the population we want to grab data from.

We are only interested in transactional data of visitors that have made a "transaction_site_com" purchase.

Request payload

In this payload, I'm adding a single filter that let me select the affiliation I want to select my population on.

{
  "timeIntervals": [
    {
      "start": "1672621200",
      "end": "1673571600"
    }
  ],
  "filters": {
      "single": {
          "field": "affiliation",
          "operator": "EQUAL",
          "value": "transaction_site_com"
      }
  },
  "dimensions": [
      "affiliation"
  ],
  "metrics": [
    {
        "key": "users"
    },
    {
        "key": "transactions"
    }
  ],
  "limit": "10"
}

Result output

If I'm only interested in the "transaction_site_com" data I can either ignore the second value or transform the filters parameter to a campaignFilter parameter. This new layer of filter will only return the data from the specific transaction hit when the filters parameter looks for the entire session where the filtering condition occured.

Request payload

The same but with campaignFilter.

{
  "timeIntervals": [
    {
      "start": "1672621200",
      "end": "1673571600"
    }
  ],
  "campaignFilter": {
      "single": {
          "field": "affiliation",
          "operator": "EQUAL",
          "value": "transaction_site_com"
      }
  },
  "dimensions": [
      "affiliation"
  ],
  "metrics": [
    {
        "key": "users"
    },
    {
        "key": "transactions"
    }
  ],
  "limit": "10"
}

Result output

Introduction to hits incompatibility

Our data is gathered as sessions composed of grapes of hits. Each hit is a row and is a description of a specific set of data that happened during the session. Hits are described here. Each hit contains several columns. Most column are common arguments while some other are specific arguments that are linked to only one type of hit. Device, geolocation, document URL and campaign is a common argument as it can be attached to any type of hit. Transaction revenue, event action or NPS Feedback are specific and can only be attached to their specific type of hit.

You obviously can't get specific argument data for a type of hit that doesn't host it. You can't ask for the number of transactions per event. This is what we are going to illustrate in this section.

Request payload

With this payload, I'm asking for the number of total events ventilated by eventAction and filtered by a named event action. Nothing too fancy here, that's very similar to what we have done before.

{
  "timeIntervals": [
    {
      "start": "1672621200",
      "end": "1673571600"
    }
  ],
    "filters": {
        "single": {
            "field": "eventAction",
            "operator": "EQUAL",
            "value": "Creation compte"
        },
        "filteringStrategy": "PER_SESSION"
    },
    "dimensions": [
        "eventAction"
    ],
  "metrics": [
    {
        "key": "totalEvents"
    }
  ],
  "limit": "5"
}

Result output

Let's now try something a bit different that you might want to do.

Request payload

I'm now asking for the amount of transactions ventilated by event action and with the same filter.

{
  "timeIntervals": [
    {
      "start": "1672621200",
      "end": "1673571600"
    }
  ],
    "filters": {
        "single": {
            "field": "eventAction",
            "operator": "EQUAL",
            "value": "Creation compte"
        },
        "filteringStrategy": "PER_SESSION"
    },
    "dimensions": [
        "eventAction"
    ],
  "metrics": [
    {
        "key": "transactions"
    }
  ],
  "limit": "5"
}

Result output

What you wanted to do is to get the amount of generated transactions depending on a specific event. "Does successfully creating an account generates a lot of transactions?". While the question is interesting, it can't be asked like that to the API as you are trying to force the API to draw a conclusion and correlate two sets of information when it can only give you raw data.

However, you can do otherwise and still get the type of information you were looking for.

Request payload

Using this request, I'm asking the amount of total events ventilated by event action after selecting the population that have made a "transaction" purchase. Notice that I have removed the filteringStrategy parameter to force it to its default value: user level.

{
  "timeIntervals": [
    {
      "start": "1672621200",
      "end": "1673571600"
    }
  ],
    "filters": {
        "single": {
            "field": "affiliation",
            "operator": "CONTAINS",
            "value": "transaction"
        }
    },
    "dimensions": [
        "eventAction"
    ],
  "metrics": [
    {
        "key": "totalEvents"
    }
  ],
  "limit": "5"
}

Result output

Composite filters

We have seen how to do one filter on the selected population, why shouldn't we do two filters? The way to structure the payload is a bit different and brings new parameters, but the logic is the same.

Request payload

This composite filter allows me to select my population over two criteria: has made a "transaction" purchase AND has made a transaction greater than 500 currency. Moreover, the singleHitCondition set to true is to force the two filters on the same transaction. If a visitor would have made two transactions but if both unique transaction doesn't validate the two filters, the visitor won't be selected.

{
  "timeIntervals": [
    {
      "start": "1672621200",
      "end": "1673571600"
    }
  ],
    "filters": {
            "composite": {
                "singleHitCondition":true,
                "operator": "AND",
                "filters": [
                    {
                        "single": {
                            "field": "affiliation",
                            "operator": "CONTAINS",
                            "value": "transaction"
                        },
                        "filteringStrategy": "PER_USER"
                    },
                    {
                        "single": {
                            "field": "transactionRevenue",
                            "operator": "GREATER",
                            "value": "500"
                        },
                        "filteringStrategy": "PER_USER"
                    }
                ]
            }
        },
    "dimensions": [
        "eventAction"
    ],
  "metrics": [
    {
        "key": "totalEvents"
    }
  ],
  "limit": "5"
}

Result output

Super composite filters

Two filters at once was to easy. Let's go for three!

The logic is still the same, we are simply nesting a composite filter into a first composite filter. In this example, my first composite is made of one single filter and one other composite made of two single filters, but I could also have two secondary composite within the first composite.

Request payload

With this payload, I am selecting

• visitors that have made a "transaction" purchase,

AND

(

• visitors that have made a transaction lower than 5 currency

OR

• visitors that havae made a transaction greater than 500 currency

)

Both level of filter with the singleHitCondition set to true and a filteringStrategy set user wide (the first level of single filter using the default value).

While the payload doesn't make a lot of sense at first, it is useful to illustrate this type of complex filters.

{
  "timeIntervals": [
    {
      "start": "1672621200",
      "end": "1673571600"
    }
  ],
    "filters": {
        "composite": {
            "singleHitCondition":true,
            "operator": "AND",
            "filters": [
                {
                    "single": {
                        "field": "affiliation",
                        "operator": "CONTAINS",
                        "value": "transaction"
                    }
                },
                {
                    "composite": {
                        "singleHitCondition":true,
                        "operator": "OR",
                        "filters": [
                            {
                                "single": {
                                    "field": "transactionRevenue",
                                    "operator": "LESS",
                                    "value": "5"
                                },
                                "filteringStrategy": "PER_USER"
                            },
                            {
                                "single": {
                                    "field": "transactionRevenue",
                                    "operator": "GREATER",
                                    "value": "500"
                                },
                                "filteringStrategy": "PER_USER"
                            }
                        ]
                    }
                }
            ]
        }
        },
    "dimensions": [
        "eventAction"
    ],
  "metrics": [
    {
        "key": "totalEvents"
    }
  ],
  "limit": "10"
}

Result output