Banner statistics

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

getBannerDailyStatistics

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

Implementation: URL/bnn/[bannerId]/statistics/daily/[start_date]/[end_date]

Method: GET

Json example

Method: 
    GET http://api.example.com/bnn/12/statistics/daily/2018-06-13/2018-06-14

Response example

{
    "id": 12,
    "start_date": "2018-06-13",
    "end_date": "2018-06-14",
    "days": {
        "data": [
            {
                "impressions": 42,
                "clicks": 0,
                "requests": 59,
                "revenue": 0.0319,
                "day": "2018-06-13"
            },
            {
                "impressions": 55,
                "clicks": 0,
                "requests": 60,
                "revenue": 0.0415,
                "day": "2018-06-14"
            }
        ]
    }
}

getBannerHourlyStatistics

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

Implementation: URL/bnn/[bannerId]/statistics/daily/[start_date]

Method: GET

Json example

Method: 
    GET http://api.example.com/bnn/12/statistics/hourly/2018-10-17

Response example

{
    "id": 12,
    "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 banner IDs.

getBannerPublisherStatistics

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

Implementation: URL/bnn/[bannerId]/statistics/publisher/[start_date]/[end_date]

Method: GET

Json example

Method: 
    GET http://api.example.com/bnn/12/statistics/publisher/2018-06-08/2018-06-14

Response example

{
    "id": 12,
    "start_date": "2018-06-08",
    "end_date": "2018-06-14",
    "publishers": {
        "data": [
            {
                "impressions": "261",
                "clicks": "4",
                "requests": "323",
                "revenue": "0.1978",
                "publisherid": "4",
                "publishername": "Demo Statistics Website"
            }
        ]
    }
}

getBannerZoneStatistics

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

Implementation: URL/bnn/[bannerId]/statistics/daily/[start_date]/[end_date]

Method: GET

Json example

Method: 
    GET http://api.example.com/bnn/1/statistics/daily/2018-06-08/2018-06-14

Response example

{
    "id": 12,
    "start_date": "2018-06-08",
    "end_date": "2018-06-14",
    "zones": {
        "data": [
            {
                "impressions": "261",
                "clicks": "4",
                "requests": "323",
                "revenue": "0.1978",
                "conversions": "0",
                "publisherid": "4",
                "publishername": "Demo Statistics Website",
                "zoneid": "11",
                "zonename": "Demo Statistics Zone"
            }
        ]
    }
}

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 a banner that doesn’t exist results in the following response:

  {
      "error": {
          "type": "Exception",
          "message": "Unknown bannerId Error"
      }
  }