View as Markdown

Big Data Analytics

The Big Data Analytics (BDA) API lets your server pull the same reports and analytics data you see in your Ezoic dashboard. There are two kinds of reports: predefined reports that ship with your account, and custom reports you build yourself.

See API for how to enable the service, your base URL, and authentication. All examples below use your developerKey.

Getting Started

The easiest way to start is to pull the list of predefined reports with getreports:

curl -X GET "https://api-gateway.ezoic.com/bdaservices/getreports/?developerKey=YOUR_API_KEY"
import requests

url = "https://api-gateway.ezoic.com/bdaservices/getreports/?developerKey=YOUR_API_KEY"

response = requests.get(url)
print(response.json())
<?php
$ch = curl_init("https://api-gateway.ezoic.com/bdaservices/getreports/?developerKey=YOUR_API_KEY");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

This returns a list of report names. We'll use the revenueDaily report. Look at its definition with getreport:

curl -X GET "https://api-gateway.ezoic.com/bdaservices/getreport/?reportName=revenueDaily&developerKey=YOUR_API_KEY"
import requests

url = "https://api-gateway.ezoic.com/bdaservices/getreport/?reportName=revenueDaily&developerKey=YOUR_API_KEY"

response = requests.get(url)
print(response.json())
<?php
$ch = curl_init("https://api-gateway.ezoic.com/bdaservices/getreport/?reportName=revenueDaily&developerKey=YOUR_API_KEY");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Getting Data

Now pull the data with getdata. Because revenueDaily (like most predefined reports) has the DateBaseSelectId of BASE_NOT_SELECTED (no built-in date range), you must include a date range in the request.

getdata requires a MaxItems value; some reports (for example when using URL as a dimension) return thousands of rows, so paginate by incrementing StartItem. DateGrouping controls whether data is grouped by day, week, or month. Platform chooses between Ezoic, Orig, or ALL (combined). SegmentIds is optional and splits a single row into multiple segments.

curl -X POST "https://api-gateway.ezoic.com/bdaservices/getdata/?reportName=revenueDaily&developerKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "StartItem": 0,
  "MaxItems": 10,
  "Platform": "ALL",
  "DomainId": 9999,
  "DateGrouping": "DAILY",
  "SegmentIds": [1],
  "StartDate": "2018-10-01",
  "EndDate": "2018-10-01"
}'
import requests

url = "https://api-gateway.ezoic.com/bdaservices/getdata/?reportName=revenueDaily&developerKey=YOUR_API_KEY"
headers = {"Content-Type": "application/json"}
payload = """{
  "StartItem": 0,
  "MaxItems": 10,
  "Platform": "ALL",
  "DomainId": 9999,
  "DateGrouping": "DAILY",
  "SegmentIds": [1],
  "StartDate": "2018-10-01",
  "EndDate": "2018-10-01"
}"""

response = requests.post(url, headers=headers, data=payload)
print(response.json())
<?php
$ch = curl_init("https://api-gateway.ezoic.com/bdaservices/getdata/?reportName=revenueDaily&developerKey=YOUR_API_KEY");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json"]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{
  "StartItem": 0,
  "MaxItems": 10,
  "Platform": "ALL",
  "DomainId": 9999,
  "DateGrouping": "DAILY",
  "SegmentIds": [1],
  "StartDate": "2018-10-01",
  "EndDate": "2018-10-01"
}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Custom Reports

To change which columns you get back, build a custom report. You can base it on a predefined report's definition. Get the list of available columns with getcolumns:

curl -X GET "https://api-gateway.ezoic.com/bdaservices/getcolumns/?developerKey=YOUR_API_KEY"
import requests

url = "https://api-gateway.ezoic.com/bdaservices/getcolumns/?developerKey=YOUR_API_KEY"

response = requests.get(url)
print(response.json())
<?php
$ch = curl_init("https://api-gateway.ezoic.com/bdaservices/getcolumns/?developerKey=YOUR_API_KEY");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

This example adds a copy_paste_per_pageview column to a revenue report. You can also embed segments directly in the report: if a custom report has segments, getdata defaults to those when no segments are specified; otherwise the getdata request's segments take precedence. Setting the date range BaseSelectId to BASE_LAST_7 means a getdata request with no dates defaults to the last seven days.

curl -X POST "https://api-gateway.ezoic.com/bdaservices/createcustomreport/?developerKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "ReportTitle": "My Custom Revenue Report",
  "ReportDateRange": { "BaseSelectId": "BASE_LAST_7" },
  "Charts": [
    {
      "Name": "My Custom Revenue Report Chart",
      "DimensionColumns": [
        { "Data": "report_day", "Type": "string" }
      ],
      "MetricColumns": [
        { "Data": "visits", "Type": "number" },
        { "Data": "pageviews", "Type": "number" },
        { "Data": "engaged_page_pageviews", "Type": "number" },
        { "Data": "engaged_pageviews_per_visit", "Type": "number" },
        { "Data": "engaged_time", "Type": "number" },
        { "Data": "bounce_rate", "Type": "number" },
        { "Data": "revenue", "Type": "number" },
        { "Data": "epmv", "Type": "number" },
        { "Data": "copy_paste_per_pageview", "Type": "number" }
      ],
      "Segments": [],
      "Order": { "ColumnNumber": 0, "Direction": "DESC" }
    }
  ]
}'
import requests

url = "https://api-gateway.ezoic.com/bdaservices/createcustomreport/?developerKey=YOUR_API_KEY"
headers = {"Content-Type": "application/json"}
payload = """{
  "ReportTitle": "My Custom Revenue Report",
  "ReportDateRange": { "BaseSelectId": "BASE_LAST_7" },
  "Charts": [
    {
      "Name": "My Custom Revenue Report Chart",
      "DimensionColumns": [
        { "Data": "report_day", "Type": "string" }
      ],
      "MetricColumns": [
        { "Data": "visits", "Type": "number" },
        { "Data": "pageviews", "Type": "number" },
        { "Data": "engaged_page_pageviews", "Type": "number" },
        { "Data": "engaged_pageviews_per_visit", "Type": "number" },
        { "Data": "engaged_time", "Type": "number" },
        { "Data": "bounce_rate", "Type": "number" },
        { "Data": "revenue", "Type": "number" },
        { "Data": "epmv", "Type": "number" },
        { "Data": "copy_paste_per_pageview", "Type": "number" }
      ],
      "Segments": [],
      "Order": { "ColumnNumber": 0, "Direction": "DESC" }
    }
  ]
}"""

response = requests.post(url, headers=headers, data=payload)
print(response.json())
<?php
$ch = curl_init("https://api-gateway.ezoic.com/bdaservices/createcustomreport/?developerKey=YOUR_API_KEY");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json"]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{
  "ReportTitle": "My Custom Revenue Report",
  "ReportDateRange": { "BaseSelectId": "BASE_LAST_7" },
  "Charts": [
    {
      "Name": "My Custom Revenue Report Chart",
      "DimensionColumns": [
        { "Data": "report_day", "Type": "string" }
      ],
      "MetricColumns": [
        { "Data": "visits", "Type": "number" },
        { "Data": "pageviews", "Type": "number" },
        { "Data": "engaged_page_pageviews", "Type": "number" },
        { "Data": "engaged_pageviews_per_visit", "Type": "number" },
        { "Data": "engaged_time", "Type": "number" },
        { "Data": "bounce_rate", "Type": "number" },
        { "Data": "revenue", "Type": "number" },
        { "Data": "epmv", "Type": "number" },
        { "Data": "copy_paste_per_pageview", "Type": "number" }
      ],
      "Segments": [],
      "Order": { "ColumnNumber": 0, "Direction": "DESC" }
    }
  ]
}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

This returns the custom report's id. If you forget it, list all your custom reports (with ids and names) using getcustomreports. Then call getdata with the custom report id. You don't need to include dates when the custom report carries a default range:

curl -X POST "https://api-gateway.ezoic.com/bdaservices/getdata/?customReportId=CUSTOM_REPORT_ID&developerKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "StartItem": 0,
  "MaxItems": 10,
  "Platform": "ALL",
  "DomainId": 9999,
  "DateGrouping": "DAILY"
}'
import requests

url = "https://api-gateway.ezoic.com/bdaservices/getdata/?customReportId=CUSTOM_REPORT_ID&developerKey=YOUR_API_KEY"
headers = {"Content-Type": "application/json"}
payload = """{
  "StartItem": 0,
  "MaxItems": 10,
  "Platform": "ALL",
  "DomainId": 9999,
  "DateGrouping": "DAILY"
}"""

response = requests.post(url, headers=headers, data=payload)
print(response.json())
<?php
$ch = curl_init("https://api-gateway.ezoic.com/bdaservices/getdata/?customReportId=CUSTOM_REPORT_ID&developerKey=YOUR_API_KEY");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json"]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{
  "StartItem": 0,
  "MaxItems": 10,
  "Platform": "ALL",
  "DomainId": 9999,
  "DateGrouping": "DAILY"
}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Segments

Segments split data into categories using filters, for example only desktop traffic or only new visitors. List available segments with getsegments:

curl -X GET "https://api-gateway.ezoic.com/bdaservices/getsegments/?developerKey=YOUR_API_KEY"
import requests

url = "https://api-gateway.ezoic.com/bdaservices/getsegments/?developerKey=YOUR_API_KEY"

response = requests.get(url)
print(response.json())
<?php
$ch = curl_init("https://api-gateway.ezoic.com/bdaservices/getsegments/?developerKey=YOUR_API_KEY");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

This returns both custom segments you created and premade ones, such as "All Users" (no filter) and "Desktop Traffic". To build a segment that filters, say, US and Canada traffic, first find the available filters.

There are two filter types: multifilters that filter on preset groups (device, country, gender, site) and filters that use an operation (greater than, contains, matches exactly, and so on). List multifilters with getmultifilters:

curl -X GET "https://api-gateway.ezoic.com/bdaservices/getmultifilters/?developerKey=YOUR_API_KEY"
import requests

url = "https://api-gateway.ezoic.com/bdaservices/getmultifilters/?developerKey=YOUR_API_KEY"

response = requests.get(url)
print(response.json())
<?php
$ch = curl_init("https://api-gateway.ezoic.com/bdaservices/getmultifilters/?developerKey=YOUR_API_KEY");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

The one we want is the "Country" multifilter:

{ "FilterName": "Country", "MultiFilterId": 1, "MultiFilterTypeId": 1 }

That doesn't tell us the available options. Get those with getmultifiltertypes:

curl -X GET "https://api-gateway.ezoic.com/bdaservices/getmultifiltertypes/?developerKey=YOUR_API_KEY"
import requests

url = "https://api-gateway.ezoic.com/bdaservices/getmultifiltertypes/?developerKey=YOUR_API_KEY"

response = requests.get(url)
print(response.json())
<?php
$ch = curl_init("https://api-gateway.ezoic.com/bdaservices/getmultifiltertypes/?developerKey=YOUR_API_KEY");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

The multifilter type with id 1 maps to the Country filter, and its option keys are two-character country codes. With that, create the segment. Since we aren't using regular filters, we can omit that attribute:

curl -X POST "https://api-gateway.ezoic.com/bdaservices/createsegment/?developerKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "SegmentName": "US and Canada",
  "SegmentMultiFilters": {
    "1": { "FilterValues": ["US", "CA"] }
  }
}'
import requests

url = "https://api-gateway.ezoic.com/bdaservices/createsegment/?developerKey=YOUR_API_KEY"
headers = {"Content-Type": "application/json"}
payload = """{
  "SegmentName": "US and Canada",
  "SegmentMultiFilters": {
    "1": { "FilterValues": ["US", "CA"] }
  }
}"""

response = requests.post(url, headers=headers, data=payload)
print(response.json())
<?php
$ch = curl_init("https://api-gateway.ezoic.com/bdaservices/createsegment/?developerKey=YOUR_API_KEY");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json"]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{
  "SegmentName": "US and Canada",
  "SegmentMultiFilters": {
    "1": { "FilterValues": ["US", "CA"] }
  }
}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

You get back a segment object with its id filled in. Use that id in a getdata request. If the id were 99999:

curl -X POST "https://api-gateway.ezoic.com/bdaservices/getdata/?customReportId=CUSTOM_REPORT_ID&developerKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "StartItem": 0,
  "MaxItems": 10,
  "Platform": "ALL",
  "DomainId": 9999,
  "SegmentIds": [99999],
  "DateGrouping": "DAILY"
}'
import requests

url = "https://api-gateway.ezoic.com/bdaservices/getdata/?customReportId=CUSTOM_REPORT_ID&developerKey=YOUR_API_KEY"
headers = {"Content-Type": "application/json"}
payload = """{
  "StartItem": 0,
  "MaxItems": 10,
  "Platform": "ALL",
  "DomainId": 9999,
  "SegmentIds": [99999],
  "DateGrouping": "DAILY"
}"""

response = requests.post(url, headers=headers, data=payload)
print(response.json())
<?php
$ch = curl_init("https://api-gateway.ezoic.com/bdaservices/getdata/?customReportId=CUSTOM_REPORT_ID&developerKey=YOUR_API_KEY");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json"]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{
  "StartItem": 0,
  "MaxItems": 10,
  "Platform": "ALL",
  "DomainId": 9999,
  "SegmentIds": [99999],
  "DateGrouping": "DAILY"
}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;