Walkthrough
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.
{
"timeIntervals": [
{
"start": "1672621200",
"end": "1673571600"
}
],
"metrics": [
{
"key": "sessions"
}
],
"limit": "10"
}How many sessions do I had between 1672621200 and 1673571600?
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.
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"
}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.
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"
}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.
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"
}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.
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"
}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.
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"
}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.
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"
}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.
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"
}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.
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"
}Let's now try something a bit different that you might want to do.
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"
}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.
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"
}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.
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"
}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.
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"
}Last updated
Was this helpful?