Skip to end of metadata
Go to start of metadata

Document Revision 1.48


PulsePoint's Publisher Reporting API allows you to run key reports of advertising metrics for autonomous downloading. This document describes how to generate queries and interpret the output.


 

CONVENTIONS USED IN THIS DOCUMENT

1) In tables, references to field and array names within the current report are in bold.

2) For floating point calculations, whole numbers are represented with a decimal place (e.g. 100.0, 1,000.0)

IMPORTANT

If a developer/technician who worked for you leaves your organization, and you wish to protect your data from malicious use, you should regenerate a new API Token. Click here for info. In such a case, you must modify the token in any queries made via the Reporting API.

Alternatively, you can email PublisherSupport@PulsePoint.com, or contact your Account Manager. We can generate a new token for you. Please note that you still must modify the token in any queries made via the reporting API.


Overview

INTRODUCTION


This segment of PulsePoint's Reporting API allows publishers to run key reports of advertising metrics for autonomous downloading. These reports are usually run via an API call that generates a URL query, which is populated with required and optional parameters. You can also construct the URL query directly in your browser.

The API is read-only. Requests never alter any data.

NOTE
For information on the buyer side of the Reporting API, please see: Buyer Reporting API.


AVAILABLE PUBLISHER REPORTS


API ENDPOINTS


The Report Endpoints are available through secure (https) protocol only.

NOTE
This URL is non-functional: you must specify a reportType, and add parameters to perform a query.
https://openapi.pulsepoint.com/OpenAPIPublisher/v1.0/reporting/<reportType>


Where reportType can be:

  • dailystats (For Daily Publisher Report)
  • accountmanagement (For Account Management Report)
  • category (For Impressions by Category Report)
  • video (For Video Monetization Report)

Daily Publisher Report


SUMMARY

The Daily Publisher Report allows publishers to obtain daily key performance metrics for revenue earned via the PulsePoint platform. The fields include Paid Impressions and Revenue, among other info. The report is run over a specified date range. This report is usually run via an API call that generates a URL query, which is populated with required and optional parameters. You can also construct the URL query directly in your browser.

API ENDPOINTS


The Daily Publisher Report Endpoint is available via secure (https) protocol only.

NOTE
This URL is non-functional: you must add the parameter(s) described below to perform a query.

https://openapi.pulsepoint.com/OpenAPIPublisher/v1.0/reporting/dailystats

QUERY DATA

 
Data Fields

DAILY PUBLISHER REPORT – QUERY DATA



Field

Type/Format

Notes

fromDate

Date
YYYY-MM-DD
Optional

1] You must specify both fromDate/toDate, or no dates.
2] If no dates specified, defaults to yesterday.
3] You cannot go back more than one year from today.
4] Maximum date range: one year plus one day.
5] Time Zone: USA – Eastern Time.

toDate

Date
YYYY-MM-DD
Optional

1] You must specify both fromDate/toDate, or no dates.
2] If no dates specified, defaults to yesterday.
3] You cannot go back more than one year from today.
4] Maximum date range: one year plus one day.
5] Time Zone: USA – Eastern Time.

token

Hex
32 characters
Required

1] Generated by Publisher Selling Desk.
2] To obtain the token you can either:
.....a] Look it up the Setup → Account Info tab of the Publisher Selling Desk. Click here for info.
.....b] Email PublisherSupport@PulsePoint.com or contact your Account Manager.
3] Please note that one publisher can have multiple accounts, each with its own token.


Query Format


Query is a URL.

URL CONVENTIONS

1) Construct with https (secure protocol).

2) Optional elements are delimited in square brackets [].

3) Assume all components are case-sensitive.

https://openapi.pulsepoint.com/OpenAPIPublisher/v1.0/reporting/dailystats?[fromDate=<fromDate>&toDate=<toDate>&]token=<token>

Query Examples

NOTE (token)
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx represents a 32-character hex value.

With Date Range


https://openapi.pulsepoint.com/OpenAPIPublisher/v1.0/reporting/dailystats?fromDate=2016-03-02&toDate=2016-03-03&token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Without Date Range


https://openapi.pulsepoint.com/OpenAPIPublisher/v1.0/reporting/dailystats?token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx


ADDITIONAL INFO


Throttle Settings


PulsePoint caps the maximum number of requests as per the following Throttle Settings, to ensure database operations will not be overwhelmed by requests:

  • Production: 5 requests per minute.
  • Development: 1,000 requests per minute.



OUTPUT DATA


Data Fields

DAILY PUBLISHER REPORT – OUTPUT DATA



Header (One instance.)



FieldType/FormatNotes

dateRange

String
YYYY-MM-DD "EST" - YYYY-MM-DD "EST"

1] Report Date Range.
2] Time Zone: USA – Eastern Time.

reportData array (Each element contains one instance of the fields below for each date with activity.)



FieldType/FormatNotes

avgCPM

Float
Monetary – USD

1] Avg. cost per 1,000 impressions. i.e. (netRevenue * 1,000.0) / paidImpressions

paidImpressions

Integer

1] Impressions paid.

passbackImpressions

Integer

1] Impressions "passed back" (i.e. defaulted) to another ad platform because PulsePoint could not serve an ad.

totalImpressions

Integer

1] Total impressions i.e.
paidImpressions + passbackImpressions

date

Date
YYYY-MM-DD

1] Date for this data block.
2] Time Zone: USA – Eastern Time.

fillRate

Float
Percentage

1] Rate at which impressions were paid. i.e.
100.0 * (paidImpressions / totalImpressions)

netRevenue

Float
Monetary – USD

1] Net Revenue earned from all impressions.



Format/Examples


These examples demonstrate that there is a separate block for each date in the date range. The data therein does not represent live information.


Currently, JSON is the only supported format.


JSON


{
  dateRange"2016-03-02 EST - 2016-03-03 EST",
  reportData
  [
    {
      avgCPM87.86,
      paidImpressions: 14,
      passbackImpressions: 96,
      totalImpressions: 110,
      date"2016-03-02",
      fillRate: 12.73,
      netRevenue1.23
    },
    {
      avgCPM: 6.92,
      paidImpressions13,
      passbackImpressions: 26,
      totalImpressions: 39,
      date"2016-03-03",
      fillRate: 33.33,
      netRevenue0.09
    }
  ]
}

Returned Errors

Error Messages


NOTE
Certain invalid URLs generate Internet errors (e.g. HTTP ERROR: 404) before the reporting engine can be accessed. Such errors will not appear in the supported output format (i.e. JSON).


DAILY PUBLISHER REPORT – ERROR EXAMPLES



Error Message

Field(s)

Explanation

Unauthorized: Authentication token was either missing or invalid

(token)1

Request contains invalid token. e.g.
1] Length != 32.
2] Contains non-hex characters.

should not be greater than today

fromDate
toDate

Request contains a future date (beyond today).

should not be less than
YYYY-MM-DD

fromDate

Request contains a date more than a year ago.

should be less than toDate

fromDate

Request contains a fromDate later than toDate.
(Both dates are allowed to be the same.)

Invalid value ________

fromDate
toDate

Request contains invalid date. e.g. 2016-01-32,
2016-0131, 01-31-2016

Bad URL

(various) 1

Request URL contains invalid data. e.g.
1] Invalid version.
2] Invalid report name (e.g. "dailystats" misspelled.)
3] "reporting" URL component misspelled.

NOTES:

1] Fields in ()s are not specified in name field of error message.




JSON Output


Known errors are returned in one of the following two formats.

ONE-LEVEL ERROR STRUCTURE (SINGLE ERROR)


Format:


{
  errorDescription: "<error description>"
}


Example:



  errorDescription: "Unauthorized: Authentication token was either missing or invalid."


ARRAY OF ONE OR MORE ERRORS


Format:


Components in italics represent one or more optional additional array elements. Each additional array element is preceded by a comma.


{
  validationErrors:
  [
    { 
      name: "<Field Name>"
      errorDescription: "<error description>"
    }<comma>
    { 
      name: "<Field Name>"
      errorDescription: "<error description>"
    } 
  ]
}

Examples:


{
  validationErrors:
  [
    { 
      name: "fromDate"
      errorDescription: "Invalid value 2016-01-32"
    }
  ]
}


=======


{
  validationErrors:
  [
    { 
      name: "toDate"
      errorDescription: "should not be greater than today"
    },
    { 
      name: "fromDate"
      errorDescription: "date should not be less than 2015-03-05"
    }
  ]
}

[ Back to Top ]

Account Management Report


SUMMARY

 
The Account Management Report allows publishers to obtain key performance metrics. broken out by PulsePoint tag (tagID). The fields include Paid Impressions and Revenue, among other info. The report is run over a specified date range. This report is usually run via an API call that generates a URL query, which is populated with required and optional parameters. You can also construct the URL query directly in your browser.

API ENDPOINTS

 
The Account Management Report Endpoint is available via secure (https) protocol only.

NOTE
This URL is non-functional: you must add the parameter(s) described below to perform a query.

https://openapi.pulsepoint.com/OpenAPIPublisher/v1.0/reporting/accountmanagement

QUERY DATA


Data Fields

ACCOUNT MANAGEMENT REPORT – QUERY DATA



Field

Type/Format

Notes

fromDate

Date
YYYY-MM-DD
Optional

1] You must specify both fromDate/toDate, or no dates.
2] If no dates specified, defaults to yesterday.
3] You cannot go back more than one year from today.
4] Maximum date range: one year + one day.
5] Time Zone: USA – Eastern Time.

toDate

Date
YYYY-MM-DD
Optional

1] You must specify both fromDate/toDate, or no dates.
2] If no dates specified, defaults to yesterday.
3] You cannot go back more than one year from today.
4] Maximum date range: one year + one day.
5] Time Zone: USA – Eastern Time.

token

Hex
32 characters
Required

1] Generated by Publisher Selling Desk.
2] To obtain the token you can either:
.....a] Look it up the Setup → Account Info tab of the Publisher Selling Desk. Click here for info.
.....b] Email PublisherSupport@PulsePoint.com or contact your Account Manager.
3] Please note that one publisher can have multiple accounts, each with its own token.


Query Format


Query is a URL.

URL CONVENTIONS

1) Construct with https (secure protocol).

2) Optional elements are delimited in square brackets [].

3) Assume all components are case-sensitive.


https://openapi.pulsepoint.com/OpenAPIPublisher/v1.0/reporting/accountmanagement?[fromDate=<fromDate>&toDate=<toDate>&]token=<token>

Query Examples

NOTE (token)
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx represents a 32-character hex value.


With Date Range


https://openapi.pulsepoint.com/OpenAPIPublisher/v1.0/reporting/accountmanagement?fromDate=2017-03-13&toDate=2017-03-14&token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx


Without Date Range


https://openapi.pulsepoint.com/OpenAPIPublisher/v1.0/reporting/accountmanagement?token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx


ADDITIONAL INFO


Throttle Settings


PulsePoint caps the maximum number of requests as per the following Throttle Settings, to ensure database operations will not be overwhelmed by requests:

  • Production: 5 requests per minute.
  • Development: 1,000 requests per minute.



OUTPUT DATA

Data Fields

ACCOUNT MANAGEMENT REPORT – OUTPUT DATA



Header (One instance.)



FieldType/FormatNotes

dateRange

String
YYYY-MM-DD "EST" - YYYY-MM-DD "EST"

1] Report Date Range.
2] Time Zone: USA – Eastern Time.

reportData array (Each element contains one instance of the fields below for each tagID with activity.)



FieldType/FormatNotes

tagID

Integer

1] Unique ad tag ID for this data block.

e.g. 282033

tagName

String

1] Name of tag for an ad.

e.g. "scout_delivery"

size

String

  • <Width>X<Height> (See Note 1.)
  • Other values

1] Size of ad, in pixels or otherwise. e.g.
"120x600" (Pixels)
"Video"

"HighImpact"

status

String

1] Status of ad, e.g.
"Active"

"Inactive"

askPrice

Float
Monetary – USD

1] Price asked by publisher when bidding.

avgCPM

Float
Monetary – USD

1] Avg. cost per 1,000 impressions. i.e. (netRevenue * 1,000.0) / paidImpressions

fillRate

Float
Percentage

1] Rate at which impressions were paid. i.e. 100.0 * (paidImpressions / totalImpressions)

paidImpressions

Integer

1] Impressions paid.

passbackImpressions

Integer

1] Impressions "passed back" (i.e. defaulted) to another ad platform because PulsePoint could not serve an ad.

totalImpressions

Integer

1] Total impressions. i.e. paidImpressions + passbackImpressions

netRevenue

Float
Monetary – USD

1] Net Revenue earned from all impressions.

channelString1] Specific tagtype. (e.g. "Display", "Video", "In-Image")
connectionString1] Method by which ad request is initiated (e.g. "Tag", "Header Bidder")


Format/Examples

 
These examples demonstrate that there is a separate block for each tag (not date).


Currently, JSON is the only supported format.

JSON


{
  dateRange"2017-03-13 EST - 2017-03-14 EST",
  reportData
  [
    {
      tagId: 40742,
      tagName"afsfgqy",
      size"video",
      status"Active",
      askPrice0.25,
      avgCPM0.2,
      fillRate4.16,
      paidImpressions99,
      passbackImpressions2278,
      totalImpressions: 2377,
      netRevenue0.02,
      channel: "Video",
      connection: "Tag"
    },

    {
      tagId40743,
      tagName"fsadst",
      size"Video",
      status"Active",
      askPrice0.5,
      avgCPM0.43,
      fillRate11.27,
      paidImpressions23,
      passbackImpressions181,
      totalImpressions204,
      netRevenue0.01, 
      channel: "Video",
      connection: "Tag"
    },

    {
      tagId: 40744,
      tagName"fahdt",
      size"120x21",
      status"Active",
      askPrice0.25,
      avgCPM0.28,
      fillRate17.31,
      paidImpressions143,
      passbackImpressions683,
      totalImpressions826,
      netRevenue0.04,
      channel: "Display",
      connection: "Tag" 
    }
  ]

 

Returned Errors

Error Messages


NOTE
Certain invalid URLs generate Internet errors (e.g. HTTP ERROR: 404) before the reporting engine can be accessed. Such errors will not appear in the supported output format (i.e. JSON).


ACCOUNT MANAGEMENT REPORT – ERROR EXAMPLES



Error Message

Field(s)

Explanation

Unauthorized: Authentication token was either missing or invalid

(token)1

Request contains invalid token. e.g.
1] Length != 32.
2] Contains non-hex characters.

should not be greater than today

fromDate
toDate

Request contains a future date (beyond today).

should not be less than
YYYY-MM-DD

fromDate

Request contains a date more than a year ago.

should be less than toDate

fromDate

Request contains a fromDate later than toDate.
(Both dates are allowed to be the same.)

Invalid value ________

fromDate
toDate

Request contains invalid date. e.g. 2017-01-32,
2017-0131, 01-31-2017

Bad URL

(various) 1

Request URL contains invalid data. e.g.
1] Invalid version.
2] Invalid report name (e.g. "accountmanagement" misspelled.)
3] "reporting" URL component misspelled.

NOTES:

1] Fields in ()s are not specified in name field of error message.




JSON Output

Known errors are returned in one of the following two formats.

ONE-LEVEL ERROR STRUCTURE (SINGLE ERROR)


Format:


{
  errorDescription: "<error description>"
}


Example:



  errorDescription: "Unauthorized: Authentication token was either missing or invalid."


ARRAY OF ONE OR MORE ERRORS


Format:


Components in italics represent one or more optional additional array elements. Each additional array element is preceded by a comma.


{
  validationErrors:
  [
    { 
      name: "<Field Name>"
      errorDescription: "<error description>"
    }<comma>
    { 
      name: "<Field Name>"
      errorDescription: "<error description>"
    } 
  ]
}

Examples:


{
  validationErrors:
  [
    { 
      name: "fromDate"
      errorDescription: "Invalid value 2017-01-32"
    }
  ]
}

=======

{
  validationErrors:
  [
    { 
      name: "toDate"
      errorDescription: "should not be greater than today"
    },
    { 
      name: "fromDate"
      errorDescription: "date should not be less than 2016-03-18"
    }
  ]
}

[Back to Top]

Impressions by Category Report


SUMMARY

PulsePoint assigns a contextual category (e.g.  Arts & Entertainment) to the ads served on your site. The Impressions by Category Report breaks down your advertising data by these categories, and outputs data such as Total Impressions and Paid Impressions. The report is run over a specified date range. It is usually run via an API call that generates a URL query, which is populated with required and optional parameters. You can also construct the URL query directly in your browser. 


API ENDPOINTS


The Impressions by Category Report Endpoint is available via secure (https) protocol only.

NOTE
This URL is non-functional: you must add the parameter(s) described below to perform a query.

https://openapi.pulsepoint.com/OpenAPIPublisher/v1.0/reporting/category  

QUERY DATA

 
Data Fields

IMPRESSIONS BY CATEGORY REPORT – QUERY DATA



Field

Type/Format

Notes

fromDate

Date
YYYY-MM-DD
Optional

1] You must specify both fromDate/toDate, or no dates.
2] If no dates specified, defaults to yesterday.
3] You cannot go back more than one year from today.
4] Maximum date range: one year + one day.
5] Time Zone: USA – Eastern Time.

toDate

Date
YYYY-MM-DD
Optional

1] You must specify both fromDate/toDate, or no dates.
2] If no dates specified, defaults to yesterday.
3] You cannot go back more than one year from today.
4] Maximum date range: one year + one day.
5] Time Zone: USA – Eastern Time.

token

Hex
32 characters
Required

1] Generated by Publisher Selling Desk.
2] To obtain the token you can either:
.....a] Look it up the Setup → Account Info tab of the Publisher Selling Desk. Click here for info.
.....b] Email PublisherSupport@PulsePoint.com or contact your Account Manager.
3] Please note that one publisher can have multiple accounts, each with its own token.


Query Format


Query is a URL.

URL CONVENTIONS

1) Construct with https (secure protocol).

2) Optional elements are delimited in square brackets [].

3) Assume all components are case-sensitive.


https://openapi.pulsepoint.com/OpenAPIPublisher/ v1.0/reporting/category?[fromDate=<fromDate>&toDate=<toDate>&]token=<token> 

Query Examples

NOTE (token)
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx represents a 32-character hex value.

 
With Date Range


https://openapi.pulsepoint.com/OpenAPIPublisher/v1.0/reporting/category?fromDate=2016-12-05&toDate=2016-12-09&token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx


Without Date Range


https://openapi.pulsepoint.com/OpenAPIPublisher/v1.0/reporting/category?token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx


ADDITIONAL INFO


Throttle Settings


PulsePoint caps the maximum number of requests as per the following Throttle Settings, to ensure database operations will not be overwhelmed by requests:

  • Production: 5 requests per minute.
  • Development: 1,000 requests per minute.



OUTPUT DATA


Data Fields

IMPRESSIONS BY CATEGORY REPORT – OUTPUT DATA



Header (One instance.)



FieldType/FormatNotes

dateRange

String
YYYY-MM-DD "EST" - YYYY-MM-DD "EST"

1] Report Date Range.
2] Time Zone: USA – Eastern Time.

reportData array (Each element contains one instance of the fields below for each CategoryName with activity.)




FieldType/FormatNotes
fillRateFloat
Percentage
1] Rate at which impressions were paid. i.e.
100.0 * (PaidImpressions / TotalImpressions)
CategoryNameString1] Name of contextualized category.
TotalImpressionsInteger1] Total impressions.

PaidImpressions

Integer

1] Impressions paid.



Format/Examples


These examples demonstrate that there is a separate block for each category. The data therein does not represent live information.


Currently, JSON is the only supported format.


JSON


{
  dateRange "2016-12-05 EST - 2016-12-09 EST",
  reportData :  
  [
    {
      fillRate : 75.27 ,
      CategoryName: "Arts & Entertainment",
      TotalImpressions: 135,

      PaidImpressions : 94
         },
    {
      fillRate: 88.52 ,
      CategoryName: "Pets",
      TotalImpressions: 203 ,

      PaidImpressions: 162
      

    },
    {
      fillRate: 67.02 ,
      CategoryName: "Uncategorized ",
      TotalImpressions: 102 ,

      PaidImpressions: 73
      

    }

  ]
} 

Returned Errors  

Error Messages

NOTE
Certain invalid URLs generate Internet errors (e.g. HTTP ERROR: 404) before the reporting engine can be accessed. Such errors will not appear in the supported output format (i.e. JSON).


IMPRESSIONS BY CATEGORY REPORT – ERROR EXAMPLES



Error Message

Field(s)

Explanation

Unauthorized: Authentication token was either missing or invalid

(token)1

Request contains invalid token. e.g.
1] Length != 32.
2] Contains non-hex characters.

should not be greater than today

fromDate
toDate

Request contains a future date (beyond today).

should not be less than
YYYY-MM-DD

fromDate

Request contains a date more than one year ago.

should be less than toDate

fromDate

Request contains a fromDate later than toDate.
(Both dates are allowed to be the same.)

Invalid value ________

fromDate
toDate

Request contains invalid date. e.g. 2016-12-32,
2016-1231, 12-31-2016

Bad URL

(various) 1

Request URL contains invalid data. e.g.
1] Invalid version.
2] Invalid report name (e.g. "category" misspelled.)
3] "reporting" URL component misspelled.

NOTES:

1] Fields in ()s are not specified in name field of error message.




JSON Output


Known errors are returned in one of the following two formats.

ONE-LEVEL ERROR STRUCTURE (SINGLE ERROR)


Format:


{
  errorDescription: "<error description>"
}


Example:



  errorDescription: "Unauthorized: Authentication token was either missing or invalid."


ARRAY OF ONE OR MORE ERRORS


Format:


Components in italics represent one or more optional additional array elements. Each additional array element is preceded by a comma.


{
  validationErrors:
  [
    { 
      name: "<Field Name>"
      errorDescription: "<error description>"
    }<comma>
    { 
      name: "<Field Name>"
      errorDescription: "<error description>"
    } 
  ]
}

Examples:


{
  validationErrors:
  [
    { 
      name: "fromDate"
      errorDescription: "Invalid value 2016-12-32"
    }
  ]
}


=======


{
  validationErrors:
  [
    { 
      name: "toDate"
      errorDescription: "should not be greater than today"
    },
    { 
      name: "fromDate"
      errorDescription: "date should not be less than 2016-01-03"
    }
  ]
}

[ Back to Top ]

Video Monetization Report


SUMMARY

The Video Monetization Report (a.k.a. Video Monetization Performance) provides information on the revenue brought in by video tags of various sizes. The fields include Paid Impressions and Click-Through Rate (CTR). The report is run over a specified date range. This report is usually run via an API call that generates a URL query, which is populated with required and optional parameters. You can also construct the URL query directly in your browser. 

API ENDPOINTS


The Video Monetization Report Endpoint is available via secure (https) protocol only.

NOTE
This URL is non-functional: you must add the parameter(s) described below to perform a query.

https://openapi.pulsepoint.com/OpenAPIPublisher/v1.0/reporting/video  

QUERY DATA

 
Data Fields

VIDEO MONETIZATION REPORT – QUERY DATA



Field

Type/Format

Notes

fromDate

Date
YYYY-MM-DD
Optional

1] You must specify both fromDate/toDate, or no dates.
2] If no dates specified, defaults to yesterday.
3] You cannot go back more than 30 days from today.
4] Maximum date range: 31 days.
5] Time Zone: USA – Eastern Time.

toDate

Date
YYYY-MM-DD
Optional

1] You must specify both fromDate/toDate, or no dates.
2] If no dates specified, defaults to yesterday.
3] You cannot go back more than 30 days from today.
4] Maximum date range: 31 days.
5] Time Zone: USA – Eastern Time.

token

Hex
32 characters
Required

1] Generated by Publisher Selling Desk.
2] To obtain the token you can either:
.....a] Look it up the Setup → Account Info tab of the Publisher Selling Desk. Click here for info.
.....b] Email PublisherSupport@PulsePoint.com or contact your Account Manager.
3] Please note that one publisher can have multiple accounts, each with its own token.


Query Format


Query is a URL.

URL CONVENTIONS

1) Construct with https (secure protocol).

2) Optional elements are delimited in square brackets [].

3) Assume all components are case-sensitive.


https://openapi.pulsepoint.com/OpenAPIPublisher/v1.0/reporting/video?[fromDate=<fromDate>&toDate=<toDate>&]token=<token> 

Query Examples

NOTE (token)
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx represents a 32-character hex value.

 
With Date Range

https://openapi.pulsepoint.com/OpenAPIPublisher/v1.0/reporting/video?fromDate=2017-01-16&toDate=2017-01-22&token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Without Date Range


https://openapi.pulsepoint.com/OpenAPIPublisher/v1.0/reporting/video?token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx


ADDITIONAL INFO


Throttle Settings


PulsePoint caps the maximum number of requests as per the following Throttle Settings, to ensure database operations will not be overwhelmed by requests:

  • Production: 5 requests per minute.
  • Development: 1,000 requests per minute.



OUTPUT DATA


Data Fields

The Video Monetization output data is formatted as follows:

  • Header (One instance).
  • For each domain:
    • reportData object, containing:
      • videoAdTagReport: Array of objects for individual tags with their video statistics.
      • Totals: An object with a summary of statistics across all ad tags.

VIDEO MONETIZATION REPORT - HEADER
Field Type/Format Notes

dateRange

String
YYYY-MM-DD "EST" - YYYY-MM-DD "EST"

1] Report Date Range.
2] Time Zone: USA – Eastern Time.



VIDEO MONETIZATION REPORT – INDIVIDUAL TAG DATA



One element of videoAdTagReport array for each VideoTagName with activity.
FieldType/FormatNotes
DomainNameString1] Domain name for this ad tag.
Revenue

Float

Monetary - USD

1] Revenue earned for this ad tag.
fillRateFloat
Percentage

1] Rate at which impressions were paid for this ad tag. i.e.

100.0 * (PaidImpressions / TotalImpressions)

PaidImpressionsInteger1] Impressions paid for this ad tag.
TotalImpressionsInteger

1] Total impressions for this ad tag.  

AdTagId

Integer

1] Unique ID for this ad tag.

VideoTagNameString1] Name for this ad tag.
VideoTagTypeString1] "Instream" or "Outstream".
CTRFloat
Percentage

1] Click-Through Rate for this ad tag i.e. 100.0 * TotalClicks / TotalImpressions

25%CompFloat
Percentage
1] Percentage of ads (for this ad tag) played to at least 25% completion.1
50%CompFloat
Percentage
1] Percentage of ads (for this ad tag) played to at least 50% completion. 2
75%CompFloat
Percentage
1] Percentage of ads (for this ad tag) played to at least 75% completion.3
100%CompFloat
Percentage
1] Percentage of ads (for this ad tag) played to 100% completion.4
AvgCPM

Float

Monetary - USD 

1] Average cost for this ad tag per 1,000 impressions. i.e. (Revenue * 1,000.0) / PaidImpressions

NOTES:

1] Example: If 25%Comp = 28.2%, it means that 28.2% of ads for this ad tag played to at least 25% completion.

2] Example: If 50%Comp = 20.5%, it means that 20.5% of ads for this ad tag played to at least 50% completion.

3] Example: If 75%Comp = 17.8%, it means that 17.8% of ads for this ad tag played to at least 75% completion.

4] Example: If 100%Comp = 16.6%, it means that 16.6% of ads for this ad tag played to 100% completion.


VIDEO MONETIZATION REPORT – DOMAIN TOTALS DATA



Totals of all elements in videoAdTagReport array
FieldType/FormatNotes
DomainNameString1] Domain name for ad tags in videoAdTagReport array.
Revenue

Float

Monetary - USD

1] Revenue across all ad tags for this domain.
fillRateFloat
Percentage

1] Rate (across all ad tags for this domain) at which impressions were paid. i.e.

100.0 * (PaidImpressions / TotalImpressions)

PaidImpressionsInteger1] Impressions paid for this domain across all tags.
TotalImpressionsInteger

1] Total impressions for this domain across all ad tags.

CTRFloat
Percentage

1] Click-Through Rate over all ad tags for this domain. i.e. 100.0 * TotalClicks / TotalImpressions

25%CompFloat
Percentage
1] Percentage of all ads played across all tags for this domain that played to at least 25% completion.1
50%CompFloat
Percentage
1] Percentage of all ads played across all tags for this domain that played to at least 50% completion.2
75%CompFloat
Percentage
1] Percentage of all ads played across all tags for this domain that played to at least 75% completion.3
100%CompFloat
Percentage
1] Percentage of all ads played across all tags for this domain that played to at least 100% completion.4
AvgCPM

Float

Monetary - USD 

1] Average cost per 1,000 impressions (across all ad tags for this domain).
i.e. (Revenue * 1,000.0) / PaidImpressions



NOTES:

1] Example: If 25%Comp = 24.1%, it means that 24.1% of ads for this domain played to at least 25% completion.

2] Example: If 50%Comp = 18.5%, it means that 18.5% of ads for this domain played to at least 50% completion.

3] Example: If 75%Comp = 16.2%, it means that 16.2% of ads for this domain played to at least 75% completion.

4] Example: If 100%Comp = 14.3%, it means that 14.3% of ads for this domain played to 100% completion.



Format/Examples


This example demonstrates the video format described above. (Click here for more info.)

Currently, JSON is the only supported format.


JSON

{

   
   dateRange: "2017-01-16 ET - 2017-01-22 ET",

   reportData

   [

       {

          videoAdTagReport

           [

               {

                     
                   DomainName
: "sampledomain.com ",

                   Revenue: 3.85,
                   FillRate2.26,
                   PaidImpressions300,
                   TotalImpressions13282,
                   AdTagId482753,
                   VideoTagName"test1tag",
                   VideoTagType"Instream",
                   CTR: 12.75,
                   25%Comp
28.2,

                   50%Comp20.5,
                   75%Comp17.8,
                   100%Comp16.6,
                   AvgCPM: 12.83
                   

              },

              { 

                    DomainName:  "sampledomain.com " ,
                    Revenue:  4.21 ,
                    FillRate: 1.41,
                    PaidImpressions: 522,
                    TotalImpressions: 37053,
                    AdTagId: 502376,
                    VideoTagName: "test2tag",
                    VideoTagType "Outstream"
                    CTR: 9.75,
                    25%Comp: 22.2

                    50%Comp: 17.1
                    75%Comp: 15.2
                    100%Comp: 13.2,
                    AvgCPM: 8.07
 
 
             }

                      ]

                   { 

          
           DomainName:
 "sampledomain,com",

           Revenue: 8.06 ,
           FillRate: 1.63 ,
           PaidImpressions: 822,
           TotalImpressions: 50335,
           CTR: 10.38,
           25%Comp: 24.1,
           50%Comp: 18.2,
           75%Comp: 16.2,
           100%Comp: 14.3,
           AvgCPM: 9.81 

        }

   ]

}



Returned Errors 

Error Messages

NOTE
Certain invalid URLs generate Internet errors (e.g. HTTP ERROR: 404) before the reporting engine can be accessed. Such errors will not appear in the supported output format (i.e. JSON).


VIDEO MONETIZATION REPORT – ERROR EXAMPLES



Error Message

Field(s)

Explanation

Unauthorized: Authentication token was either missing or invalid

(token)1

Request contains invalid token. e.g.
1] Length != 32.
2] Contains non-hex characters.

should not be greater than today

fromDate
toDate

Request contains a future date (beyond today).

should be less than 30 days

fromDate

Request contains a date more than 30 days ago.

should be less than toDate

fromDate

Request contains a fromDate later than toDate.
(Both dates are allowed to be the same.)

Invalid value ________

fromDate
toDate

Request contains invalid date. e.g. 2016-12-32,
2016-1231, 12-31-2016

Bad URL

(various) 1

Request URL contains invalid data. e.g.
1] Invalid version.
2] Invalid report name (e.g. "video" misspelled.)
3] "reporting" URL component misspelled.

NOTES:

1] Fields in ()s are not specified in name field of error message.




JSON Output


Known errors are returned in one of the following two formats.

ONE-LEVEL ERROR STRUCTURE (SINGLE ERROR)


Format:


{
  errorDescription: "<error description>"
}


Example:



  errorDescription: "Unauthorized: Authentication token was either missing or invalid."


ARRAY OF ONE OR MORE ERRORS


Format:


Components in italics represent one or more optional additional array elements. Each additional array element is preceded by a comma.


{
  validationErrors:
  [
    { 
      name: "<Field Name>"
      errorDescription: "<error description>"
    }<comma>
    { 
      name: "<Field Name>"
      errorDescription: "<error description>"
    } 
  ]
}

Examples:


{
  validationErrors:
  [
    { 
      name: "fromDate"
      errorDescription: "Invalid value 2016-12-32"
    }
  ]
}


=======


{
  validationErrors:
  [
    { 
      name: "toDate"
      errorDescription: "should not be greater than today"
    },
    { 
      name: "fromDate"
      errorDescription: "date should not be less than 2017-01-03"
    }
  ]
}

[Back to Top]