Ad Performance Requests

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: https://api.videoplaza.com/v1/swagger
  • 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.

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 goal objects, or one goal object, which is composed of the following information:
    • id (string): the ID of the ad
    • name (string): the name of the ad
    • creative (object): the creative associated with the ad
      • type (string): the type of creative, the possible values are: standard, thirdparty, placeholder (only in case no creative was assigned yet), spotPlaceholder, pause, pausePlaceholder, 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
      • assetId (string, optional): the ID of the creative
      • clickDestinationUri (string, optional): the click-through URL of the creative
      • 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): indicates whether the ad is enabled or not
    • campaignId (string): the ID of the campaign the ad is associated with
    • goalId (string): the ID of the goal the ad is associated with
    • zone (string, optional): only present for companion banner ads and indicates the ID of the zone the companion is assigned to
    • description (string, optional): the description of the ad
    • weight (number, 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 in the same goal. The value is between 0.0001 and 1
    • customId (string, optional): the custom ID of the ad, if set
    • start (string, optional): the start date and time of the ad
    • end (string, optional): the end date and time of the ad
    • externalTrackers (object): 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
    • deviceContainers (string array): the device groups targeted by the ad
    • created (string): the creation date and time of the ad
    • modified (string): the last date and time the ad was modified
    • metrics (object, optional): indicates the requested metrics and their values:
      • impression (integer, optional): the number of impressions delivered on the object
      • error (integer, optional): the number of errors recorded on the object
      • click_through (integer, optional): the number of click-throughs recorded for the object
      • ad_started (integer, optional): the number of times playback started for an ad associated with the object. In general this is equal to the amount of impressions
      • ad_25_percent_completed (integer, optional): the number of times an ad associated with the object was viewed for at least 25%
      • ad_50_percent_completed (integer, optional): the number of times an ad associated with the object was viewed for at least 50%
      • ad_75_percent_completed (integer, optional): the number of times an ad associated with the object was viewed for at least 75%
      • ad_completed (integer, optional): the number of times an ad associated with the object was viewed completely
      • delivered (integer, optional): only available on goal objects, and only when requesting all metrics (metrics=all). It indicates the amount of the goal's type that was delivered
  • 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
    • 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/xml
x-o-api-key="<your key>"

Request body: -

Success response:

HTTP status:
  200 (OK)

Body:
{
  "data": [
    {
      "id": "4f566196-e883-4850-bd87-9b60012b109e",
      "name": "3rd party",
      "creative": {
        "type": "thirdparty",
        "insertionPoint": "preroll",
        "vastUri": "http://ya.ru",
        "vpaidStrict": true,
        "vpaidCountdown": false
      },
      "enabled": true,
      "campaignId": "14c35309-e670-46f4-b762-535bc206273f",
      "goalId": "3ac370be-6d73-4b09-b2cb-e993a9840a9a",
      "metrics": {
        "impression": 60,
        "click_through": 0,
        "ad_started": 0,
        "ad_25_percent_completed": 0,
        "ad_50_percent_completed": 0,
        "ad_75_percent_completed": 0,
        "ad_completed": 0
      },
      "description": "",
      "externalTrackers": [],
      "deviceContainers": [
        "5faffabd-fd8f-47f8-9360-49a98b399ea1",
        "6b6535fb-7ca3-4aea-a783-92f99e698d4c"
      ],
      "created": "2017-07-18T12:08:47Z",
      "modified": "2017-07-18T12:08:47Z"
    },
    {
      "id": "51e40681-1cae-49b0-991e-1e607a86b798",
      "name": "ad",
      "creative": {
        "type": "standard",
        "insertionPoint": "preroll",
        "assetId": "0b8281b2-05cb-4a74-8367-74d52cb54d3b"
      },
      "enabled": true,
      "campaignId": "fe13f08e-8cb6-4262-a55c-f14db76910c0",
      "goalId": "3cebb198-e672-4b82-9520-a1b4434064a6",
      "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
      },
      "description": "",
      "externalTrackers": [],
      "deviceContainers": [
        "5faffabd-fd8f-47f8-9360-49a98b399ea1",
        "6b6535fb-7ca3-4aea-a783-92f99e698d4c"
      ],
      "created": "2017-10-13T10:59:39Z",
      "modified": "2017-10-13T11:04:57Z"
    },
    {
      "id": "93df441f-9a13-45c2-8e22-0f62c48bb2de",
      "name": "companion (flash)",
      "creative": {
        "type": "unknown",
        "unknownType": "companion_browser_flash"
      },
      "enabled": true,
      "campaignId": "d4de4366-fda1-4b39-af7e-e2179014fa24",
      "goalId": "778bebb4-d3e2-4d94-a921-5ea717c85ddd",
      "metrics": {
        "impression": 34,
        "click_through": 15,
        "ad_started": 0,
        "ad_25_percent_completed": 0,
        "ad_50_percent_completed": 0,
        "ad_75_percent_completed": 0,
        "ad_completed": 0
      },
      "zone": "003f6afc-ab47-11e2-9c44-001e4f3cd647",
      "description": "",
      "externalTrackers": [],
      "deviceContainers": [
        "d25462f4-ea19-4eaf-99b9-85de3f29d059"
      ],
      "created": "2016-09-26T08:52:15Z",
      "modified": "2016-10-19T13:48:45Z"
    },
  ],
  "pagination": {
    "totalCount": 3,
    "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
    • 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/b22e12f0-4666-40c4-867e-a7955750da1e?ads&metrics=all HTTP/1.1
Host: api.videoplaza.com
Content-type: application/xml
x-o-api-key="<your key>"

Request body: -

Success response:

HTTP status:
  200 (OK)

Body:
{
  "id": "ad21ad20-1e65-4db6-a48f-eae9f7e118f6",
  "name": "Test Pause Preview",
  "creative": {
    "type": "pause",
    "assetId": "2a0dbce3-4108-430e-87e9-37d712775d30"
  },
  "enabled": true,
  "campaignId": "2769cf04-7510-4702-a3a1-f2a9e43ae08b",
  "goalId": "cd1357e8-643c-45e0-a6ea-2efb2f0b8d43",
  "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
  },
  "description": "",
  "externalTrackers": [],
  "deviceContainers": [
    "6b6535fb-7ca3-4aea-a783-92f99e698d4c"
  ],
  "created": "2017-10-12T12:08:46Z",
  "modified": "2017-10-12T12:08:46Z"
}

해당 내용이 도움 되었습니까?