Statistics REST API | Documentation

This API allows the Advertising and Publishing statistics collected by the Cxense Advertising platform to be accessed. These statistics can be retrieved in summary or detailed format across a specified date range, and for multiple statistics objects.

Retrieving summary statistics

GET

Retrieves statistics totals for specified objects.

https://{cxadbaseurl}/api/secure/stats/totals/{type}?refs={ref1,ref2,...}&start={YYYYmmDDHHMM}&end={YYYYmmDDHHMM}&tz={timezone}

Parameters:

cxadbaseurl - the base URL of the Cxense Advertising system.
type - the #type of statistics to retrieve.
refs - a comma-separated list of object #refs to retrieve statistics for.
start - the start #date of the range (inclusive) to retrieve statistics for.
end - the end #date of the range (exclusive) to retrieve statistics for.
tz - (optional) the timezone of start date and end date. Default: UTC.

Example command:

curl -s -H "Content-type: text/xml" -u jsmith:password1 -X GET "https://cxad.cxense.com/api/secure/stats/totals/publisher?refs=0000000000004779&start=201101290000&end=201201290000&tz=Europe/Oslo"

The following XML example shows the contents returned from a typical GET call:

<?xml version="1.0" ?>
<cx:statsTotals xmlns:cx="http://cxense.com/cxad/api/cxad"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                xsi:type="cx:publishingPerformanceTotals"
                startTime="2011-01-29T00:00:00.000Z"
                endTime="2012-01-29T00:00:00.000Z">
    <cx:stats ref="0000000000004779">
        <cx:impressionRequests>11</cx:impressionRequests>
        <cx:positiveImpressionRequests>10</cx:positiveImpressionRequests>
        <cx:filteredImpressionRequests>
            <cx:count type="OVERAGE">1</cx:count>
            <cx:count type="EXACT_DUPLICATE">2</cx:count>
        </cx:filteredImpressionRequests>
        <cx:adImpressions>25</cx:adImpressions>
        <cx:clicks>2</cx:clicks>
        <cx:filteredClicks>
            <cx:count type="TOO_QUICK">1</cx:count>
        </cx:filteredClicks>
        <cx:actions>
            <cx:count type="VIDEO_START">5</cx:count>
            <cx:count type="VIDEO_END">2</cx:count>
        </cx:actions>
        <cx:filteredActions>
            <cx:reason type="TOO_QUICK">
                <cx:count type="VIDEO_START">1</cx:count>
            </cx:reason>
            <cx:reason type="TOO_QUICK">
                <cx:count type="VIDEO_START">1</cx:count>
            </cx:reason>
        </cx:filteredActions> 
        <cx:uniqueUserStats>
            <cx:count>5.00</cx:count>
            <cx:stdev>1.00</cx:stdev>
            <cx:uncookied>0</cx:uncookied>
        </cx:uniqueUserStats>
 
 
    </cx:stats>
</cx:statsTotals>

Retrieving detailed statistics

GET

Retrieves detailed statistics for specified objects.

https://{cxadbaseurl}/api/secure/stats/data/{type}/{chunk}?refs={ref1,ref2,...}&start={YYYYmmDDHHMM}&end={YYYYmmDDHHMM}

Parameters:

cxadbaseurl - the base URL of the Cxense Advertising system.
type - the #type of statistics to retrieve.
chunk - the granularity of each #chunk of data retrieved.
refs - a comma-separated list of object #refs to retrieve statistics for.
start - the start #date of the range (inclusive) to retrieve statistics for.
end - the end #date of the range (exclusive) to retrieve statistics for.
tz - (optional) the timezone of start date and end date. Default: UTC.

Example command:

curl -s -H "Content-type: text/xml" -u jsmith:password1 -X GET "https://cxad.cxense.com/api/secure/stats/data/advertiser/day?refs=000000000000476a,0000000000004779&start=201101290000&end=201201290000&tz=Europe/Oslo"

The following XML example shows the contents returned from a typical GET call:

<?xml version="1.0" ?>
<cx:statsData xmlns:cx="http://cxense.com/cxad/api/cxad"
              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
              xsi:type="cx:advertisingPerformanceData"
              startTime="2011-01-29T00:00:00.000Z"
              endTime="2012-01-29T00:00:00.000Z"
              chunkSize="DAY">
    <cx:stats ref="0000000000004779">
        <cx:statsChunk startTime="2011-08-19T00:00:00.000Z">
            <cx:adImpressions>5</cx:adImpressions>
            <cx:filteredAdImpressions>
                <cx:count type="EXACT_DUPLICATE">1</cx:count>
                <cx:count type="OVERAGE">1</cx:count>
            </cx:filteredAdImpressions>
            <cx:clicks>3</cx:clicks>
            <cx:filteredClicks>
                <cx:count type="TOO_QUICK">4</cx:count>
            </cx:filteredClicks>
            <cx:auctionRankSum>2</cx:auctionRankSum>
            <cx:cost currencyCode="AUD" value="-5.000000"></cx:cost>
            <cx:uniqueUserStats>
                <cx:count>3</cx:count>
                <cx:stdev>0.1</cx:stdev>
                <cx:uncookied>0</cx:uncookied>
            </cx:uniqueUserStats>
        </cx:statsChunk>
        <cx:statsChunk startTime="2011-08-20T00:00:00.000Z">
            <cx:adImpressions>10</cx:adImpressions>
            <cx:filteredAdImpressions>
                <cx:count type="OVERAGE">1</cx:count>
            </cx:filteredAdImpressions>
            <cx:clicks>6</cx:clicks>
            <cx:filteredClicks></cx:filteredClicks>
            <cx:auctionRankSum>4</cx:auctionRankSum>
            <cx:uniqueUserStats>
                <cx:count>6</cx:count>
                <cx:stdev>0.1</cx:stdev>
                <cx:uncookied>2</cx:uncookied>
            </cx:uniqueUserStats>
        </cx:statsChunk>
    </cx:stats>
    <cx:stats ref="000000000000476a">
        <cx:statsChunk startTime="2011-08-19T00:00:00.000Z">
            <cx:adImpressions>1</cx:adImpressions>
            <cx:filteredAdImpressions></cx:filteredAdImpressions>
            <cx:clicks>0</cx:clicks>
            <cx:filteredClicks></cx:filteredClicks>
            <cx:auctionRankSum>1</cx:auctionRankSum>
            <cx:uniqueUserStats>
                <cx:count>1</cx:count>
                <cx:stdev>0</cx:stdev>
                <cx:uncookied>0</cx:uncookied>
            </cx:uniqueUserStats>
        </cx:statsChunk>
    </cx:stats>
</cx:statsData>

Retrieving keyword statistics

GET

Retrieves detailed statistics for all keywords on specified Campaigns or Advertisements.

https://{cxadbaseurl}/api/secure/stats/keywords/{chunk}?refs={ref1,ref2,...}&start={YYYYmmDDHHMM}&end={YYYYmmDDHHMM}&tz={timezone}

Parameters:

cxadbaseurl - the base URL of the Cxense Advertising system.
chunk - the granularity of each #chunk of data retrieved.
refs¹ - a comma-separated list of Campaign or Advertisement #refs to retrieve keyword statistics for.
start - the start #date of the range (inclusive) to retrieve keyword statistics for.
end - the end #date of the range (exclusive) to retrieve keyword statistics for.
tz - (optional) the timezone of start date and end date. Default: UTC.
includeDeleted - (optional) whether to include stats for deleted keywords. Default: false

¹ The stats/keywords/{chunk} method does not cascade to child container objects of a specified refs=objectId. For example, if you wish to GET total keyword stats for a Campaign, you must list all child Ad adId values in the refs= parameter.

To obtain a list of child Ad adId values for a Campaign, use the respective campaignId value in an Advertisement REST API - GET request.

The example below illustrates specifying multiple objectId values in the refs= parameter.

Example command:

curl -s -H "Content-type: text/xml" -u jsmith:password1 -X GET "https://cxad.cxense.com/api/secure/stats/keywords/day?refs=000000000000476a,0000000000004779&start=201101290000&end=201201290000&tz=Europe/Oslo"

The following XML example shows the contents returned from a typical GET call:

<?xml version="1.0" ?>
<cx:statsKeywords xmlns:cx="http://cxense.com/cxad/api/cxad"
                  startTime="2011-01-29T00:00:00.000Z"
                  endTime="2012-01-29T00:00:00.000Z"
                  chunkSize="DAY">
    <cx:stats ref="0000000000004779">
        <cx:keyword text="Honda" matchType="BROAD" language="EN">
            <cx:statsChunk startTime="2011-08-19T00:00:00.000Z">
                <cx:adImpressions>5</cx:adImpressions>
                <cx:filteredAdImpressions>
                    <cx:count type="EXACT_DUPLICATE">1</cx:count>
                    <cx:count type="OVERAGE">1</cx:count>
                </cx:filteredAdImpressions>
                <cx:clicks>3</cx:clicks>
                <cx:filteredClicks>
                    <cx:count type="TOO_QUICK">4</cx:count>
                </cx:filteredClicks>
                <cx:auctionRankSum>2</cx:auctionRankSum>
                <cx:cost currencyCode="AUD" value="5.000000"></cx:cost>
                <cx:uniqueUserStats>
                    <cx:count>3</cx:count>
                    <cx:stdev>0.1</cx:stdev>
                    <cx:uncookied>0</cx:uncookied>
                </cx:uniqueUserStats>
            </cx:statsChunk>
            <cx:statsChunk startTime="2011-08-20T00:00:00.000Z">
                <cx:adImpressions>10</cx:adImpressions>
                <cx:filteredAdImpressions>
                    <cx:count type="OVERAGE">1</cx:count>
                </cx:filteredAdImpressions>
                <cx:clicks>6</cx:clicks>
                <cx:filteredClicks></cx:filteredClicks>
                <cx:auctionRankSum>4</cx:auctionRankSum>
                <cx:uniqueUserStats>
                    <cx:count>6</cx:count>
                    <cx:stdev>0.1</cx:stdev>
                    <cx:uncookied>2</cx:uncookied>
                </cx:uniqueUserStats>
            </cx:statsChunk>
        </cx:keyword>
        <cx:keyword text="Subaru" matchType="BROAD" language="EN">
            <cx:statsChunk startTime="2011-08-19T00:00:00.000Z">
                <cx:adImpressions>1</cx:adImpressions>
                <cx:filteredAdImpressions></cx:filteredAdImpressions>
                <cx:clicks>0</cx:clicks>
                <cx:filteredClicks></cx:filteredClicks>
                <cx:auctionRankSum>1</cx:auctionRankSum>
                <cx:uniqueUserStats>
                    <cx:count>1</cx:count>
                    <cx:stdev>0</cx:stdev>
                    <cx:uncookied>0</cx:uncookied>
                </cx:uniqueUserStats>
            </cx:statsChunk>
        </cx:keyword>
    </cx:stats>
    <cx:stats ref="000000000000476a">
        <cx:keyword text="Honda" matchType="EXACT" language="JA">
            <cx:statsChunk startTime="2011-08-19T00:00:00.000Z">
                <cx:adImpressions>1</cx:adImpressions>
                <cx:filteredAdImpressions></cx:filteredAdImpressions>
                <cx:clicks>0</cx:clicks>
                <cx:filteredClicks></cx:filteredClicks>
                <cx:auctionRankSum>1</cx:auctionRankSum>
                <cx:uniqueUserStats>
                    <cx:count>1</cx:count>
                    <cx:stdev>0</cx:stdev>
                    <cx:uncookied>0</cx:uncookied>
                </cx:uniqueUserStats>
            </cx:statsChunk>
        </cx:keyword>
        <cx:keyword text="Subaru" matchType="BROAD" language="EN">
            <cx:statsChunk startTime="2011-08-19T00:00:00.000Z">
                <cx:adImpressions>1</cx:adImpressions>
                <cx:filteredAdImpressions></cx:filteredAdImpressions>
                <cx:clicks>0</cx:clicks>
                <cx:filteredClicks></cx:filteredClicks>
                <cx:auctionRankSum>1</cx:auctionRankSum>
                <cx:uniqueUserStats>
                    <cx:count>1</cx:count>
                    <cx:stdev>0</cx:stdev>
                    <cx:uncookied>0</cx:uncookied>
                </cx:uniqueUserStats>
            </cx:statsChunk>
        </cx:keyword>
    </cx:stats>
</cx:statsKeywords>

Parameter details

type

Specifies the type of statistics to retrieve. It must be one of:

"advertiser"
"publisher"

Each type returns a different set of data. Objects will not necessarily have statistics for every type.

chunk

Specifies the granularity of the detailed data to retrieve. It must be one of:

"year"
"month"
"week"
"day"
"hour"

refs

References specify a comma-separated list of statistics objects to retrieve.
A statistics object is generally an object id (e.g. 0000000000004a94) or and object id plus expression id (eg 0000000000004a94:a123cf045669a456).

date

Specifies a date-time in the format YYYYmmDDHHMM. e.g. "201101290930" for 29 January 2010 at 9:30 am.
The specified value must fall on a boundary of the chunk size.

tz

Specifies a timezone of start date and end date.

Timezone ID. e.g. "Asia/Tokyo", "Australia/Melbourne" ...etc.
Offset from UTC. e.g. "+09:00" or "+0900" (URL encode is required. e.g. +09:00 -> %2B09%3A00)

Output details

All values below are computed for the specified refs and the specified period.

adImpressions

Impression count, exclusive of filteredAdImpressions.

filteredAdImpressions

Map from impression filter type to impression filter counts

clicks

Click count, exclusive of filteredClicks

filteredClicks

Map from click filter type to click filter counts

actions

Map of action counts, exclusive of filteredActions

filteredActions

Map of maps from action filter type to action filter count

auctionRankSum

The sum of ad auction ranks for all impressions. Useful for computing the average position for reports.

averagePosition = auctionRankSum / adImpressions

cost

Total cost of all events, exclusive of overage

overage

Total overage of all events, that is the total costs incurred above a requested set of budgets

uniqueUserCount

Approximate count of how many unique users have received an ad impression.
count: Estimated Count, usually accurate to within about 5%. An exact user count is retained for low impression counts.
stdev: Confidence in our estimate.
uncookied: Our Unique User count approach relies on cookies, if no cookie is sent then an uncookied user is recorded

Note: a single user who has registered an impression on two different browsers or devices will be counted as two unique users.

Last updated: January 19, 2022