Ad Performance Requests

Warning: All Performance REST APIs are currently on version 0, which means they have not been finalised yet and may still change significantly.

Use the Ad Performance API to request perfomance metrics from ads.

Getting Started

  • Base URL: https://api.videoplaza.com/v0/ads.
  • Requests: GET requests are used. You pass parameters by using common REST parameters like PATH, QUERY, and MATRIX, as well as HTTP HEADERS. The body of the requests should be provided in JSON format and encoded using UTF-8.
  • Responses: All responses contain an HTTP status code in the header and the body is in JSON format.
  • Swagger documentation: Campaign API v2 - Ads
  • Related user documentation:

Considerations

Take the following considerations into account when using to the Performance REST API endpoints:
  • The Performance endpoints give you quick access to the data collected for your campaigns, goals and ads, with only an ingestion delay of one hour.
  • The Performance endpoints provide totals for the requested metrics. If you need a breakdown of the metrics based on time, like for each month, then use the Custom Reporting API.
  • The Performance endpoints provide the metrics described in the endpoints for the campaigns, goals and ads. If you require other metrics, then use the Custom Reporting API.
Warning: All Performance REST APIs are currently on version 0, which means they have not been finalised yet and may still change significantly.

Date and Time Format

All date and time fields may only contain date strings built up as follows:
  • Start with YYYY-MM-DD, indicating year (YYYY), month (MM) and day (DD),
  • followed by a letter T,
  • followed by hh:mm:ss, indicating hour (hh), minutes (mm), and seconds (ss). Indicating seconds is optional.
  • followed by Z to indicate the UTC time zone.

Response Body Format

The endpoints described here, return response bodies with the complete or a part of the following format:

  • data (object): an array of ad objects, or one ad object, which is composed of the following information:
    • id (string, optional): the ID of the ad
    • name (string, optional): the name of the ad
    • creative (object, optional): the creative associated with the ad. Different fields are returned, depending on the creative type
      • type (string, optional): the type of creative, the possible values are: standard, standardThirdparty, standardPlaceholder, placeholder1 (where you do not specify the type of ad yet), placeholder1Thirdparty, placeholder1Placeholder (only in case no creative was assigned yet), pause, pausePlaceholder, iptv, iptvPlaceholder, overlay, overlayPlaceholder, companionBanner, companionBannerThirdparty, takeover, takeoverPlaceholder, takeoverThirdparty, pixeltracker, rtb, rtbPlaceholder, unknown (only in case the creative does not fit into any of the other values)
      • insertionPoint (string, optional): indicates when the creative should be shown, the possible values are preroll, midroll, postroll
      • vastUri (string, optional): URI to the location of the third party creative
      • vpaidStrict (boolean, optional): indicates the allowed behaviour of VPAID ads. true means only linear ads are allowed, false means non-linear ads are allowed as well
      • vpaidCountdown (boolean, optional): indicates whether the standard Ooyala countdown text is visible on the third party VPAID ad
      • estimatedAdDuration (integer, optional): indicates the duration of the 3rd party or IPTV ad in seconds and is needed if you are using time based breaks
        Note: If the 3rd party or IPTV ad does not have an estimated duration, or exceeds the time based break duration, it will not get selected.
      • asset (object, optional): the actual creative file that you need to associate with your ads
        • id (string, optional): the ID of the asset
        • href (string, optional): the URL to the location of the asset
      • videoCreativeId (string): only present for IPTV ads and indicates the ID of the video creative stored in the IPTV closed network
      • linkText (string, optional): only present for overlay ads and indicates the clickable text that provides a link to the destination page
      • clickDestinationUri (string, optional): the click-through URL of the creative
      • bannerArea (object, optional): only present for companion banner ads and indicates a predefined area (zone) on your site to host the ad
        • id (string, optional): the ID of the banner area the companion banner is assigned to
        • href (string, optional): the URL to the location of the banner area the companion banner is assigned to
      • template (string, optional): only present for companion banner ads and indicates the code injected into your website's zone to trigger the companion banner ad
      • marketplaceId (string, optional): only present for RTB ads and indicates the ID of the marketplace the RTB ad is linked to
      • unknownType (string, optional): in case the type of the creative is unknown, then this field holds whatever string was entered as the type of the creative
    • enabled (boolean, optional): indicates whether the ad is enabled or not
    • campaignId (string, optional): the ID of the campaign the ad is associated with
    • goalId (string, optional): the ID of the goal the ad is associated with
    • description (string, optional): the description of the ad
    • weight (object, optional): the weight of the ad, which indicates in which portion of the cases a certain ad in a goal should be selected over another ad of the same format or insertion point in the same goal
      • proportional (boolean, optional): indicates if this ad's weight is proportionally split between ads of the same format or ads of the same insertion point (true), or if it is manually overridden (false)
      • totalOverridden (number, optional): sum of all overridden weights for ads of the same format and insertion point
      • value (number, optional): the weight of the ad, possible value is between 0.0 and 1
    • customId (string, optional): the custom ID of the ad, if set
    • start (object, optional): the start date and time of the ad. Value is fetched from goal if not set on the ad
      • value (string, optional): an ISO-8601 formatted date and time string
      • origin (object, optional): indicates that the start date and time is inherited from the goal. If the value is not inherited, this object is omitted
        • id: the ID of the object where the value comes from
        • href: a link to the object where the value comes from
      • self (object, optional): indicates that the goal start date and time is overridden on the ad level. If the value is inherited, this object is omitted
        • id: the ID of the object where the value comes from
        • href: a link to the object where the value comes from
    • end (object, optional): the end date and time of the ad. Value is fetched from goal if not set on the ad
      • value (string, optional): an ISO-8601 formatted date and time string
      • origin (object, optional): indicates that the end date and time is inherited from the goal. If the value is not inherited, this object is omitted
        • id: the ID of the object where the value comes from
        • href: a link to the object where the value comes from
      • self (object, optional): indicates that the goal end date and time is overridden on the ad level. If the value is inherited, this object is omitted
        • id: the ID of the object where the value comes from
        • href: a link to the object where the value comes from
    • externalTrackers (object, optional): any external tracker set on the ad
      • id (string, optional): the ID of the external tracker
      • url (string, optional): the URL of the external tracker
      • event (string, optional): the event for which the external tracker should be triggered, possible values are IMPRESSION, CLICK_THROUGH, AD_START, AD_FIRST_QUARTILE, AD_MIDPOINT, AD_THIRD_QUARTILE, AD_COMPLETE, MUTE, UNMUTE, PAUSE, REWIND, RESUME, FULLSCREEN, EXPAND, CLOSE
    • deviceContainers (string, optional): the device groups targeted by the ad
    • created (string, optional): the creation date and time of the ad in ISO-8601 format
    • modified (string, optional): the last date and time the ad was modified in ISO-8601 format
    • metrics (object, optional): indicates the requested metrics and their values:
      • impression (integer, optional): the number of impressions delivered on the object
      • error (string, optional): the number of errors recorded on the object
      • click_through (integer, optional): the number of click-throughs recorded on the associated ad(s) for the object
      • ad_started (integer, optional): the number of times playback started for associated ads of the object. In general this is equal to the amount of impressions
      • ad_25_percent_completed (integer, optional): the number of times the associated ads for the object were viewed for at least 25%
      • ad_50_percent_completed (integer, optional): the number of times the associated ads for the object were viewed for at least 50%
      • ad_75_percent_completed (integer, optional): the number of times the associated ads for the object were viewed for at least 75%
      • ad_completed (integer, optional): the number of times the associated ads for the object were viewed completely
      • delivered (integer, optional): available on goal objects only when requesting all metrics (metrics=all) to indicate the amount of the goal's type that was delivered for the goal. Also available on ad objects to indicate the amount of the goal's type that was delivered for the ad.
      • ctr (number, optional): the number of click-throughs recorded for an object divided by the number of impressions delivered on that object, also known as the click-through rate
      • completion_rate (number, optional): the number of times the associated ads for the object were viewed completely divided by the number of impressions delivered on that object
      • ecpm (number, optional): only available on goal objects, based on the configured pricing for the goal and refers to the calculated effective cost per thousand impression
  • pagination (object): indicates the pagination information, total amount of objects, the amount of objects to show for each page, and the page you are currently on:
    • totalCount (integer, optional): the total amount of data objects that the request yielded
    • pageSize (integer, optional): the size of the page, which indicates the maximum number of data objects the requests retrieves for one page
    • pageNumber (integere, optional): the page you are currently on

Get Performance Metrics for Multiple Ads

Method GET
URL /v0/ads
Header Authentication header (x-o-api-key)
Content type application/json
URL params -
Query params
Note: All query parameters are optional.
  • metrics: enter a metrics=<value> for each metric you want listed in the results in the query string. Possible values are:
    • impression
    • click_through
    • ad_started
    • ad_25_percent_completed
    • ad_50_percent_completed
    • ad_75_percent_completed
    • ad_completed
    • delivered
    • all
  • created.before: filter on ads created before a specific date and time in the results. See Date and Time Format on how to format this field.
  • created.after: filter on ads created after a specific date and time in the results. See Date and Time Format on how to format this field.
  • pageSize: enter the number of campaigns to return for each page. You can use this feature if you want to create pagination in your user interface. The value must be between 1 and 100. The default value is 10.
  • pageNumber: enter the number of the page you want the results from. This parameter works in combination with the pageSize parameter. The default value is 1. Based on the pageSize value you provide and the totalCount value returned (see Response Body Format), you can calculate how many pages there are in total.
Body -
Success response

HTTP status: 200 OK

Header: -

Body: see Response Body Format

Example:

Request header:

GET /v0/ads?metrics=all HTTP/1.1
Host: api.videoplaza.com
Content-type: application/json
x-o-api-key="<your key>"

Request body: -

Success response:

HTTP status:
  200 (OK)

Body:
{
    "data": [
        {
            "id": "2ec96765-f244-4d3e-93c7-a75f34943435",
            "name": "3rd party ad",
            "creative": {
                "insertionPoint": "preroll",
                "vastUri": "http://ad.com",
                "vpaidStrict": true,
                "vpaidCountdown": false,
                "estimatedAdDuration": 0,
                "type": "standardThirdparty"
            },
            "enabled": true,
            "campaignId": "6073ffd1-b386-4589-923e-f97bf1fbceeb",
            "goalId": "8805bcd8-c823-4dd9-a125-570bea65c161",
            "metrics": {
                "impression": 0,
                "click_through": 0,
                "ad_started": 0,
                "ad_25_percent_completed": 0,
                "ad_50_percent_completed": 0,
                "ad_75_percent_completed": 0,
                "ad_completed": 0,
                "delivered": 0
            },
            "description": "",
            "weight": {
                "proportional": true,
                "totalOverridden": 0,
                "value": 0.5
            },
            "customId": "abc123",
            "start": {
                "value": "2018-04-24T19:00:00Z",
                "self": {
                    "id": "2ec96765-f244-4d3e-93c7-a75f34943435",
                    "href": "/v0/ads/2ec96765-f244-4d3e-93c7-a75f34943435"
                }
            },
            "end": {
                "value": "2018-05-10T19:00:00Z",
                "self": {
                    "id": "2ec96765-f244-4d3e-93c7-a75f34943435",
                    "href": "/v0/ads/2ec96765-f244-4d3e-93c7-a75f34943435"
                }
            },
            "externalTrackers": [
                {
                    "id": "45abd6ca-f31c-4a91-b701-50d7cc19315b",
                    "url": "http://tracking.com",
                    "event": "IMPRESSION"
                }
            ],
            "deviceContainers": [
                "5faffabd-fd8f-47f8-9360-49a98b399ea1",
                "6b6535fb-7ca3-4aea-a783-92f99e698d4c"
            ],
            "created": "2018-04-20T14:01:16Z",
            "modified": "2018-04-20T14:01:16Z"
        },
        {
            "id": "3400b1d7-047b-4110-8430-d92953f46905",
            "name": "Ooyala ad",
            "creative": {
                "insertionPoint": "preroll",
                "asset": {
                    "id": "c8ff842c-1b71-48ec-8ad6-f771fe8d751f",
                    "href": "/v1/assets/c8ff842c-1b71-48ec-8ad6-f771fe8d751f"
                },
                "clickDestinationUri": "http://ooyala.com",
                "type": "standard"
            },
            "enabled": true,
            "campaignId": "6073ffd1-b386-4589-923e-f97bf1fbceeb",
            "goalId": "8805bcd8-c823-4dd9-a125-570bea65c161",
            "metrics": {
                "impression": 0,
                "click_through": 0,
                "ad_started": 0,
                "ad_25_percent_completed": 0,
                "ad_50_percent_completed": 0,
                "ad_75_percent_completed": 0,
                "ad_completed": 0,
                "delivered": 0
            },
            "description": "",
            "weight": {
                "proportional": true,
                "totalOverridden": 0,
                "value": 0.5
            },
            "start": {
                "value": "2018-04-20T13:59:16Z",
                "origin": {
                    "id": "8805bcd8-c823-4dd9-a125-570bea65c161",
                    "href": "/v0/goals/8805bcd8-c823-4dd9-a125-570bea65c161"
                }
            },
            "end": {
                "value": "2018-05-19T19:00:00Z",
                "origin": {
                    "id": "8805bcd8-c823-4dd9-a125-570bea65c161",
                    "href": "/v0/goals/8805bcd8-c823-4dd9-a125-570bea65c161"
                }
            },
            "externalTrackers": [
                {
                    "id": "8b12a21e-24c3-407f-ab4c-215ccd59be63",
                    "url": "http://tracking.com",
                    "event": "IMPRESSION"
                }
            ],
            "deviceContainers": [
                "5faffabd-fd8f-47f8-9360-49a98b399ea1",
                "6b6535fb-7ca3-4aea-a783-92f99e698d4c"
            ],
            "created": "2018-04-20T13:59:55Z",
            "modified": "2018-04-20T13:59:55Z"
        }
    ],
    "pagination": {
        "totalCount": 2,
        "pageSize": 10,
        "pageNumber": 1
    }
}

Get Performance Metrics for One Ad

Method GET
URL /v0/ads/{adId}
Header Authentication header (x-o-api-key)
Content type application/json
URL params adId: the ID of the ad
Query params
  • metrics: enter a metrics=<value> for each metric you want listed in the results in the query string. Possible values are:
    • impression
    • click_through
    • ad_started
    • ad_25_percent_completed
    • ad_50_percent_completed
    • ad_75_percent_completed
    • ad_completed
    • delivered
    • all
Body -
Success response

HTTP status: 200 OK

Header: -

Body: see Response Body Format. The response only contains one campaign object, without the data and pagination elements.

Example:

Request header:

GET /v0/ads/3400b1d7-047b-4110-8430-d92953f46905?metrics=all HTTP/1.1
Host: api.videoplaza.com
Content-type: application/json
x-o-api-key="<your key>"

Request body: -

Success response:

HTTP status:
  200 (OK)

Body:
{
    "id": "3400b1d7-047b-4110-8430-d92953f46905",
    "name": "Ooyala ad",
    "creative": {
        "insertionPoint": "preroll",
        "asset": {
            "id": "c8ff842c-1b71-48ec-8ad6-f771fe8d751f",
            "href": "/v1/assets/c8ff842c-1b71-48ec-8ad6-f771fe8d751f"
        },
        "clickDestinationUri": "http://ooyala.com",
        "type": "standard"
    },
    "enabled": true,
    "campaignId": "6073ffd1-b386-4589-923e-f97bf1fbceeb",
    "goalId": "8805bcd8-c823-4dd9-a125-570bea65c161",
    "metrics": {
        "impression": 0,
        "click_through": 0,
        "ad_started": 0,
        "ad_25_percent_completed": 0,
        "ad_50_percent_completed": 0,
        "ad_75_percent_completed": 0,
        "ad_completed": 0,
        "delivered": 0
    },
    "description": "",
    "weight": {
        "proportional": true,
        "totalOverridden": 0,
        "value": 0.5
    },
    "start": {
        "value": "2018-04-20T13:59:16Z",
        "origin": {
            "id": "8805bcd8-c823-4dd9-a125-570bea65c161",
            "href": "/v0/goals/8805bcd8-c823-4dd9-a125-570bea65c161"
        }
    },
    "end": {
        "value": "2018-05-19T19:00:00Z",
        "origin": {
            "id": "8805bcd8-c823-4dd9-a125-570bea65c161",
            "href": "/v0/goals/8805bcd8-c823-4dd9-a125-570bea65c161"
        }
    },
    "externalTrackers": [
        {
            "id": "8b12a21e-24c3-407f-ab4c-215ccd59be63",
            "url": "http://tracking.com",
            "event": "IMPRESSION"
        }
    ],
    "deviceContainers": [
        "5faffabd-fd8f-47f8-9360-49a98b399ea1",
        "6b6535fb-7ca3-4aea-a783-92f99e698d4c"
    ],
    "created": "2018-04-20T13:59:55Z",
    "modified": "2018-04-20T13:59:55Z"
}

Was this article helpful?