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 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, or
    • ±hh:mm indicating the offset from UTC in positive or negative direction (±) in hours (hh) and optionally minutes (mm), or
    • Z[timeZoneName] to indicate a time zone name, for example: Z[Europe/Stockholm].

For example, to define the time range of the first quarter of 2017 in New York, the startDateTime and endDateTime fields could look as follows:

...
"startDateTime": "2017-01-01T00:00Z[America/New_York]",
"endDateTime": "2017-04-01T00:00Z[America/New_York]",
...
Note: It is recommended to use the time zone name of your account, because the offset from UTC changes when the zone is affected by daylight saving time. The IANA time zone database, also named TZDB, is used to make the translation between time zone name and UTC offset. Dates and times returned in the resulting reports are always according to the time zone defined in the account.

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. See Time Filter
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. See Time Filter
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 or goal. For example, "Android tablets and phones" could be a device group.
Campaign campaign The ad's 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.
Content partner content_partner The content partner targeted by a specific campaign or goal. This dimension is automatically enriched in the report with the content partner's name in a column called content_partner_name.
Advertiser advertiser The advertiser associated with a campaign. This dimension is automatically enriched in the report with the advertiser's name in a column named advertiser_name.
Agency agency The agency associated with a campaign. This dimension is automatically enriched in the report with the advertiser's name in a column named agency_name.
Brand brand The brand associated with a campaign. This dimension is automatically enriched in the report with the advertiser's name in a column named brand_name.

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
Metro Area metro_area Metro Area 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.

Requesting inventory metrics only yields meaningful results for the following dimensions, because they are part of the ad request (directly or indirectly):
  • Device group
  • Format type
  • Tag
  • Content partner
  • Geography dimensions
  • Category
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, City and Metro Area)
  • 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 or goal. 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
Note: you may filter on maximum ten tags in one report. Using more tags may result in failing reports.

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.

Content partner content_partner

The content partner targeted by a specific campaign or goal.

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

Advertiser advertiser

The advertiser associated with a campaign.

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

Agency agency

The agency associated with a campaign.

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

Brand brand

The brand associated with a campaign.

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

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.
Metro Area metro_area Metro Area 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?