Submit a Report Definition

This endpoint submits a report definition and instructs the backend to create the report from the given definition.

Method POST
URL /v2/reports/
Header Authentication header (x-o-api-key)
Content type application/json
URL params -
Query params -
Body Report definition object:
{ 
    "reportName": "name of report",
    "reportDefinition": {
       "startDateTime": ZoneDateTime,
       "endDateTime": ZoneDateTime,
       "timeGranularity": granularityDefinition,
       "dimensions": [a, b, c],
       "metrics": [d,e],
       "filters": [filterDefinition1, filterDefinition2]
    }
}
Success response

HTTP status: 201 (created)

Header:

Location: a location header is included with the URL of the report, which contains the report's ID.

Body: -

Example

Request header:

POST /v2/reports/ HTTP/1.1
Host: api.videoplaza.com
Content-­type: application/json
x-o-api-key="<your key>"

Request body:

{
  "reportName" : "Monthly Revenue Quarter 4 2016 per Category for Mobile Devices",
  "reportDefinition": {
    "startDateTime": "2016-10-01T00:00:00+02:00",
    "endDateTime": "2016-12-31T23:59:59+02:00",
    "timeGranularity": "month",
    "dimensions": ["category"],
    "metrics": ["revenue"],
    "filters": [ 
      {
        "type": "in",
        "dimension": "device_container",
        "values" : ["56ca36a7-e350-48e2-a2ad-543d333d96de", "f797c997-d5b2-4a0c-8d53-2bc6vf947ec"]
      }
    ]
  }
}

Success response:

HTTP status:
  201 (Created)

Header:
  Location: https://api.videoplaza.com/v2/reports/f7a550eb-538b-4e23-939b-29b238671d2b

Body: -

Time Filter and Breakdown

Time Filter

Each report must have a specified time range, which is defined by the combination of the startDateTime and endDateTime fields in the request's body. These fields may only contain date strings in the ISO-8601 format, composed of a full date, time and timezone relative to UTC. Currently, only the timezone set in your account is supported. For example, if your Pulse account is set up for the New York timezone (UTC -4) and you want to run a report for data in the first quarter of 2017, then the time range is defined as follows:

...
"startDateTime": "2017-01-01T00:00:00-04:00",
"endDateTime": "2017-03-31T23:59:59-04:00",
...

Time Breakdown

You can optionally define a time based breakdown of the data in the report, through the timeGranularity field in the request's body, to show metrics for each year, month, day or hour. If you set this field to none, or omit it from the body, then the data is not broken down by time.

Summary

Field Description Supported Values
startDateTime The start date and time for the report in your account's timezone. YYYY-MM-DDThh:mm:ss+hh:mm, where:
  • YYYY is the year in four digits,
  • MM is the month in two digits,
  • DD is the day in two digits,
  • hh is the hour in two digits,
  • mm are the minutes in two digits, and
  • ss are the seconds in two digits
endDateTime The end date and time for the report in your account's timezone. The end date and time must be after the start date and time of the report. YYYY-MM-DDThh:mm:ss+hh:mm, where:
  • YYYY is the year in four digits,
  • MM is the month in two digits,
  • DD is the day in two digits,
  • hh is the hour in two digits,
  • mm are the minutes in two digits, and
  • ss are the seconds in two digits
timeGranularity The time based breakdown of the report.
  • year
  • month
  • day
  • hour
  • none

Supported Dimensions

The order of the dimensions in the report definition controls the order in which the data is broken down in the resulting report. If you have defined a timeGranularity, which is different from none, then defining dimensions becomes optional. However, you must always include the dimensions field to correctly parse the definition.

Basic dimensions

Dimension API naming Description
Device group device_container The device group inidcates which devices were targeted by a specific campaign. For exaample, "Android tablets and phones" could be a device group.
Campaign campaign The ad campaign. This dimension is automatically enriched in the report with the campaign's name in a column called "campaign_name".
Goal goal The ad's goal. This dimension is automatically enriched in the report with the goal's name in a column called "goal_name".
Ad ad The ad. This dimension is automatically enriched in the report with the ad's name in a column called "ad_name".
Format type format_type Ad format type, like "Preroll", "Midroll", and so on.
Tag tag Text representing the tags.

Geography dimensions

Currently, codes are used to lookup regional data. The codes are automatically enriched with names in the resulting report.

Dimension API naming Description
Country country Country code
Region region Region code
City city City code

Category dimension

API Naming: category

Breakdown of data based on category is limited to:
  • five levels in the category tree, counting the root level of the tree or the category selected in the filter as level one.
  • maximum the seventh level removed from the root level of the tree, counting the root level as the first level.
For example, if this is the category tree for your account:
  • Root Category (UUID=1)
    • Sports (UUID=11)
      • Football (UUID=111)
        • UEFA Champions League (UUID=1111)
        • FIFA World Cup (UUID=1112)
      • Tennis (UUID=112)
      • Basketball (UUID=113)
    • Kids TV (UUID=12)
    • Reality shows (UUID=13)
    • Hobbies (UUID=14)
      • Cooking (UUID=141)
      • Fashion (UUID=142)
    • News (UUID=15)
    • Documentaries (UUID=16)
      • Nature (UUID=161)
      • Technology (UUID=162)
      • History (UUID=163)

, and you selected to filter on 'Sports', and set Category as a dimension with level two, then the breakdown looks as follows:

Dimensions Metrics
Category Category X
Sports   Direct count for metric X for Sports Category (not including counts for child categories).
  Football Total count for metric X for Football category and all its child categories, which are UEFA Champions League and FIFA World Cup.
  Tennis Direct count for metric X for Tennis category.
  Basketball Direct count for metric X for Basketball category.

To define multiple levels of category breakdown, you simply need to repeat category up to the amount of levels required, and not exceeding five times, in the dimensions object. For example. to break down into three levels:

...
"reportDefinition": {
    "dimensions": ["category","category","category"],
...

Error tracking dimension

Note:

Error tracking reports only work if error tracking is enabled for your account, and you have an integration with at least one of the following SDKs:

  • HTML5 SDK (Core and Pulse) or any of its derivatives (HTML5 Ad Player and Plugins) for version 2.1.16.23.1 or higher
  • iOS Pulse SDK version 2.3.17.1.0 or higher
  • Android Pulse SDK version 2.3.16.25.0 or higher

No error tracking information is available for direct VAST or VMAP integrations.

Warning: Error tracking as a dimension, only yields meaningful reports when used in conjunction with error tracking as a metric (error).

API Naming: error_code

Retrieve the counts for the different errors that have occurred. The following table lists all possible error codes and their descriptions:

Code Name Description
0 Unknown error  
1 Start ad timeout The ad did not start playback within the specified time. Default timeout value is 4 seconds.
2 Total passback timeout The passback chain did not result in successfully showing an ad, because the pasback timeout expired.
100 XML parsing error An error in the XML of a third party VAST ticket was found.
101 VAST schema validation error The third party VAST ticket contains data that is in violation of the VAST schema.
102 VAST version of response not supported The video player cannot handle the VAST ticket, because its version is not supported.
200 Ad type not supported The video player received an ad type that it was not expecting and/or cannot display.
201 Ad linearity error The video player expected a different linearity.
300 General VAST Wrapper error  
301 Timeout of VAST URI An error occurred when retrieving a third party URI. Timeout of a VAST URI provided in Wrapper element, or of VAST URI provided in a subsequent Wrapper element. Includes request errors such as invalid URI, unreachable or request timeout for URI, and security or other exceptions related to requesting a VAST URI.
303 No VAST response No VAST response after one or more Wrappers.
Note: When using the HTML5 SDK or any of its derivatives, then this error is also reported each time an inventory ad is encountered. An inventory ad is a placeholder where a real ad could have been, but no eligible ad was available in Pulse.
400 General Linear error The video player is unable to display the linear ad.
401 File not found Unable to find a media file at the URI.
402 MediaFile timeout Unable to retrieve the media file within the designated time.
403 Could not find supported MediaFile Could not find a media file that is supported by the video player, based on the attributes of the MediaFile element.
405 Problem displaying MediaFile The video player found a media file with a supported type according to the attributes of the MediaFile element and was able to retrieve the file, but could not display the media file. MediaFile may include: unsupported codecs, different MIME type than indicated in @type attribute, unsupported delivery method, and so on.
500 General NonLinearAds error The video player is unable to display the non-linear ad.
502 Unable to fetch NonLinearAds / NonLinear resource The resource for the non-linear ad cannot be fetched.
503 Could not find NonLinear resource with supported type Could not find a resource that is supported by the video player.
900 Undefined error  

Supported Metrics

You can generate reports for the following metrics:

Metric API naming Description
Inventory inventory The amount of opportunities to show an ad.
Impressions impression The amount of successfully shown ads. Success is reported as soon as the first frame of the ad is shown.
Revenue revenue The amount of revenue.
Unique Impressions unique_impressions The amount of successfully shown ads to unique viewers, meaning that a viewer who has seen the ad more than once is only counted one time.
Unique inventory unique_inventory The amount of opportunities to show an ad to unique viewers.
Click-throughs click_through The amount of times a click through link was activated.
Click through rate ctr The proportionate amount of times a click through link was activated (=click-throughs/times a click-through is available).
Completion rate completion_rate The amount of times an ad was viewed to completion in comparison to the amount of times an ad was started (=Ad Completed/ Impressions).
Fill rate fill_rate The amount of impressions in comparison to the amount of inventory (=Impression/Inventory).
Ad started ad_started The amount of time an ad was started, which is the same as impression count for Pulse.
Ad 25 % ad_25_percent_completed The amount of times an ad was viewed to at least 25% completion.
Ad 50 % ad_50_percent_completed The amount of times an ad was viewed to at least 50% completion.
Ad 75 % ad_75_percent_completed The amount of times an ad was viewed to at least 75% completion.
Ad completed ad_completed The amount of times an ad was viewed to completion.
Average view through rate view_rate A complex calculation based on quartile view through rates in comparison to the amount of impressions. This calculation is explained in the following article: How is completion rate calculated in Insight?
Error error

The amount of times errors or a specific error occurred.

To create meaningful reports, you must always use the Error Code dimension in combination with the Error metric. You can also report on error counts for the following dimensions:
  • Campaign
  • Goal
  • Ad
  • Device Group
  • Geography (Country, Region and City)
  • Format Type

Supported Filters

One type of filter is currently supported. The in filter takes an array of values and works similarly to the SQL operator in.

Multiple filters work in addition to one another, which means that filters are strung together with the AND operator.

Requirements and constraints
  • Values field of in filter type must contains at least one value.
  • Maximum of one category filter can be specified.
  • If category filter is present, it must have exactly one filter value.
  • Category filter value must be a UUID.
  • Maximum depth of selected category from the root level is seven, where root level is counted as level one.
  • filters field must be present in the body, but may be empty. For example: "filters": []
  • Country, region and city filters require you to provide the codes for the required geographies. To get these codes, use the Ooyala Geography API. The documentation for this service is located at: https://api.videoplaza.com/v1/swagger
Filter API naming Description
Device group device_container

The device group indicates which devices were targeted by a specific campaign. For example, "Android tablets and phones" could be a device group.

When using this filter, you must provide the ID(s) of the device group(s).

Campaign campaign

The ad campaign(s) you want to filter on.

When using this filter, you must provide the ID(s) of the campaign(s).

Goal goal

The ad goal(s) you want to filter on.

When using this filter, you must provide the ID(s) of the goal(s).

Ad ad

The ad(s) you want to filter on.

When using this filter, you must provide the ID(s) of the ad(s).

Format type format_type

Ad format type, values are case sensitive:

  • Preroll
  • Midroll
  • Postroll
  • PauseAd
  • SeekRoll
  • Overlay
  • Companion
  • Skin
Tag tag

The filter in-value contains a comma separated list of strings representing the full textual tags included in the filter:

{
"type": "in",
"dimension": "tag",
"values":["tag1", "tag2"]
}

Tags are not case sensitive.

Country country Country code. Use the Ooyala Geography API to get the codes.
Region region Region code. Use the Ooyala Geography API to get the codes.
City city City code. Use the Ooyala Geography API to get the codes.
Category category

You can filter on only one category that is up to seven levels deep in the category tree, counting the root category as level one. When using this filter, you must provide the UUID of the category.

Error Code error_code Filter on specific error codes, which are described under the Supported Dimensions.

Was this article helpful?