Skip to end of metadata
Go to start of metadata

Document Revision 1.35

PulsePoint's Buyer 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 company, and you wish to protect your data from malicious use, please contact DemandSupport@PulsePoint.com. We can generate a new token for you. In such a case, you must modify the token in any queries made via the Reporting API.

Overview


INTRODUCTION

This segment of PulsePoint's Reporting API allows buyers 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 publisher side of the Reporting API, please see: Publisher Reporting API.


AVAILABLE BUYER 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/openAPIAdvertiser/v1.0/reporting/<reportType>


Where reportType can be:

  • spend (For Daily Demand Report)

Daily Demand Report


SUMMARY


The Daily Demand Report allows buyers to obtain key performance metrics over a specified date range. The fields include wonImpressions and  eCPM, among other info. 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 Demand 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/openAPIAdvertiser/v1.0/reporting/spend

QUERY DATA


Data Fields

DAILY DEMAND 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 32 days from today.
4] Maximum date range: 33 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 32 days from today.
4] Maximum date range: 33 days.
5] Time Zone: USA - Eastern Time.

token

Hex
32 characters
Required

1] Generated by PulsePoint Buyer Portal.
2] To obtain the token, email demandsideteam@pulsepoint.com, or contact your PulsePoint Account Manager. You can find your Account Manager's name in the Settings tab of the PulsePoint Buyer Portal.
3] Please note that one buyer 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/openAPIAdvertiser/v1.0/reporting/spend?[fromDate=<fromDate>&toDate=<toDate>&]token=<token>

Query Examples

 

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


With Date Range


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


Without Date Range


https://openapi.pulsepoint.com/OpenAPIAdvertiser/v1.0/reporting/spend?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: 10 requests per minute.
  • Development: 1,000 requests per minute.



OUTPUT DATA

Data Fields

DAILY DEMAND 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 One instance per each date with activity.)

 

 

FieldType/FormatNotes

date

Date
YYYY-MM-DD

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

wonImpressions

Integer

1] Number of impressions won in auction (across all publishers).

spend

Float
Monetary – USD

1] Total amount owed to PulsePoint by the advertiser. i.e. wonImpressions * eCPM.

eCPM

Float
Monetary – USD

1] Effective cost per 1,000 impressions. i.e.(netRevenue * 1,000.0) / wonImpressions. Please note that netRevenue is currently not part of the output.
2] PulsePoint rounds up individual bids to the next cent.
e.g. $9.42365 --> $9.43.

bidsLost

Integer

1] Number of bids lost to another buyer (across all publishers).

bidsReceived

Integer

1] Number of bids received (across all publishers).

bidsTimedOut

Integer

1] Number of bids timed out: no response received after a particular interval (across all publishers).



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-01 EST - 2016-03-02 EST",
  reportData
  [
    {
      date"2016-03-01",
      wonImpressions678684,
      spend1296.33,
      eCPM1.91,
      bidsLost18092801,
      bidsReceived18771485,
      bidsTimedOut1057157,
    },
    {
      date"2016-03-02",
      wonImpressions690861,
      spend1357.97,
      eCPM1.97,
      bidsLost15863956,
      bidsReceived16554817,
      bidsTimedOut2335107,
    }
  ]

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 DEMAND 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 > 32 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-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. "spend" 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]