Zone statistics

Documentation for all functionality to retrieve zone statistics using the Revive Adserver REST API, with breakdowns by day, by hour, by advertiser, by campaign, or by banner. There are also a number of helpful notes about date ranges.

Note: in versions of Revive Adserver and OpenX Source prior to version 2.8, the term Publisher was used where we now see the word Website. For backward compatibility, we have decided to retain the word ‘publisher’ in the API.

getZoneDailyStatistics

Description: Returns a zone’s statistics grouped by day, for a specified date range

Implementation: URL/zon/[zoneId]/statistics/daily/[start_date]/[end_date]

Method: GET

Json example

Method:

GET http://api.example.com/zon/11/statistics/daily/2018-06-17/2018-06-18

Response example

{
    "id": 11,
    "start_date": "2018-06-17",
    "end_date": "2018-06-18",
    "days": {
        "data": [
            {
                "impressions": 11,
                "clicks": 4,
                "requests": 13,
                "revenue": 0.0083,
                "day": "2018-06-17"
            },
            {
                "impressions": 57,
                "clicks": 0,
                "requests": 61,
                "revenue": 0.0432,
                "day": "2018-06-18"
            }
        ]
    }
}

Notes

See the notes at the end of the page with regard to date ranges and invalid website IDs.

getZoneHourlyStatistics

Description: Returns a zone’s statistics grouped by hour, for a specified date

Implementation: URL/zon/[zoneId]/statistics/hourly/[start_date]

Method: GET

Json example

Method:

GET http://api.example.com/zon/11/statistics/hourly/2018-10-17/

Response example

{
    "id": 11,
    "start_date": "2018-10-17",
    "end_date": "2018-10-17",
    "hours": {
        "data": [
            {
                "impressions": "9",
                "clicks": "0",
                "requests": "10",
                "revenue": "0.0068",
                "day": "2018-10-17",
                "hour": "1"
            },
            {
                "impressions": "11",
                "clicks": "0",
                "requests": "13",
                "revenue": "0.0083",
                "day": "2018-10-17",
                "hour": "2"
            },
            {
                "impressions": "0",
                "clicks": "0",
                "requests": "1",
                "revenue": "0.0000",
                "day": "2018-10-17",
                "hour": "3"
            },
(truncated for clarity)
        ]
    }
}

Notes

  • Hourly statistics is supported starting with version 4.4.0 of the Revive Adserver REST API. It also requires the use of the core Revive Adserver software with version 5.0 or higher.
  • The current version supports retrieval of hourly statistics for a single day. If hourly statistics are needed for a range of days, retrieve them for each day separately.
  • If there are no statistics for a specific hour, that hour will be skipped in the results.
  • See the notes at the end of the page with regard to date ranges and invalid website IDs.

getZoneAdvertiserStatistics

Description: Returns a zone’s statistics grouped by advertiser, for a specified date range

Implementation: URL/zon/[zoneId]/statistics/advertiser/[start_date]/[end_date]

Method: GET

Json example

Method:

GET http://api.example.com/zon/11/statistics/advertiser/2018-06-12/2018-06-18

Response example

{
    "id": 11,
    "start_date": "2018-06-12",
    "end_date": "2018-06-18",
    "advertisers": {
        "data": [
            {
                "impressions": "281",
                "clicks": "4",
                "requests": "336",
                "revenue": "0.2131",
                "advertiserid": "2",
                "advertisername": "Statistics Demo Advertiser"
            }
        ]
    }
}

Notes

See the notes at the end of the page with regard to date ranges and invalid zone IDs.

getZoneCampaignStatistics

Description: Returns a zone’s statistics grouped by campaign, for a specified date range

Implementation: URL/zon/[zoneId]/statistics/campaign/[start_date]/[end_date]

Method: GET

Json example

Method:

GET http://api.example.com/zon/11/campaign/advertiser/2018-06-12/2018-06-18

Response example

{
    "id": 11,
    "start_date": "2018-06-12",
    "end_date": "2018-06-18",
    "campaigns": {
        "data": [
            {
                "impressions": "281",
                "clicks": "4",
                "requests": "336",
                "revenue": "0.2131",
                "campaignid": "4",
                "campaignname": "Statistics Demo Campaign",
                "advertiserid": "2",
                "advertisername": "Statistics Demo Advertiser"
            }
        ]
    }
}

Notes

See the notes at the end of the page with regard to date ranges and invalid zone IDs.

getZoneBannerStatistics

Description: Returns a zone’s statistics grouped by banner, for a specified date range

Implementation: URL/zon/[zoneId]/statistics/banner/[start_date]/[end_date]

Method: GET

Json example

Method:

GET http://api.example.com/zon/11/banner/advertiser/2018-06-12/2018-06-18

Response example

{
    "id": 11,
    "start_date": "2018-06-12",
    "end_date": "2018-06-18",
    "banners": {
        "data": [
            {
                "impressions": "281",
                "clicks": "4",
                "requests": "336",
                "revenue": "0.2131",
                "campaignid": "4",
                "campaignname": "Statistics Demo Campaign",
                "advertiserid": "2",
                "advertisername": "Statistics Demo Advertiser",
                "bannerid": "12",
                "bannername": "Statistics Demo Banner"
            }
        ]
    }
}

Notes

See the notes at the end of the page with regard to date ranges and invalid zone IDs.

Notes

  • The end date in the request is optional. If omitted, the response will consist of just one day (the start date)
  • If you omit both the start date and the end date, or use a invalid date notation for the start date, the end date, or perhaps even both, there will be a response indicating the problem, as follows, for example:
    {
        "error": {
            "type": "DateException",
            "message": "Start date is not valid"
        }
    }
  • Requesting statistics for a date range where the end date is earlier than the start date, results in the following response, for example:
    {
        "error": {
            "type": "Exception",
            "message": "The start date is after the end date"
        }
    }
  • Requesting statistics for a date range that does not have any data, results in the following response, for example:
    {
        "id": 1,
        "start_date": "2017-05-21",
        "end_date": "2017-05-27",
        "days": {
            "data": []
        }
    }
  • Requesting statistics for an publisher that doesn’t exist results in the following response:
    {
        "error": {
            "type": "Exception",
            "message": "Unknown zoneId Error"
        }
    }

Current version

The most recently released version of the Revive Adserver REST API is v5.1.0 (publication date April 15, 2022).

See Release Notes

Compatibility

Revive Adserver REST API is compatible with all versions of Revive Adserver v4.x, and v5.x. It may also be compatible with Revive Adserver v3.x (and also with OpenX Source v2.8 and higher), but this can not be guaranteed.

Revive Adserver REST API is compatible with all supported versions of PHP, including PHP 7 and PHP  8.

Also see Technical Requirements, Product Content, and Installation Instructions.