Resources¶

This article describes DSP Reporting API resources, endpoints, and services. Using this API, you can create and read reports.

Overview¶

The BrightRoll Reporting API exposes two resources:

The Create Reports resource enables you to create a new report based on parameters specified in the Reporting object.
The Read Report resource returns the report status and a URL from which you can download the completed report in CSV format.

All requests require a valid access token. To learn more, see Generate New Access Tokens.

Endpoint¶

The Verizon Media DSP API reporting endpoint accepts requests for creating and retrieving reports and report statuses.

/yamplus_api/extreport/

Calls to generate a new report or return the report status and URL depending on the method:

To create a new report, call the endpoint using the POST method and specify the report payload.
To retrieve report status and a URL, call the endpoint using the GET method and specify the customerReportId.

Resources¶

The Reporting object comprises multiple objects, which consist of separate objects. The following resource objects are described separately:

reportOption
limitSpec

intervalTypeId
filterOption

having
spec

Reporting Object¶

All Verizon Media DSP API reports are defined in the body of a Reporting object that is submitted to the Create Report resource.

The Reporting object consists of attributes that enable you to define the advertiser account associated with the data, report dimensions and metrics, reporting periods, and the granularity of report data.

Table 1 Reporting Payload Parameters¶
Parameter	Description	Data Type
`reportOption`	Specifies the dimensions of data and metrics returned in the report, dimension-value filters for selecting impression events based on dimension values, and metric-value filters for selecting groups of events based on summary statistics. To learn more, see Report Option Object.	`object`
`limitSpec`	Specifies the number of rows returned in the report. To learn more, see Limit Spec Object.	`object`
`dateTypeId`	Specifies the reporting period, the span of time covered by the data set. Options include: `1`: Today `2`: Yesterday `3`: This Week `4`: Last 7 Days `5`: Last Week `6`: Last 14 Days `7`: Month to Date `8`: Last 30 Days `9`: Last Month `10`: All Time `11`: Custom Range To learn more, see Reporting Periods.	`integer`
`intervalTypeId`	Specifies the granularity of report intervals. Options include: `1`: Cumulative. Returns a single row in which each column displays data for the entire range. `2`: Day. Returns one row for each calendar day in the specified date range. `3`: Month. Returns one row for each full or partial month in the specified date range. `4`: Week. Returns one row for each calendar week in the specified date range. `5`: Hour. Returns one row for each hour that has data. To learn more, see Report Intervals.	`integer`
`startDate`	Specifies the start time of date range of the report in the format `yyyy-MM-dd'T'HH:mm:ss`.	`string`
`endDate`	Specifies the start time of date range of the report in the format `yyyy-MM-dd'T'HH:mm:ss`.	`string`

Report Option Object¶

Whenever you create a new report, you must specify report details in the reportOption object.

The reportOption object identifies the dimensions of data and metrics returned in the report, dimension-value filters for selecting impression events based on dimension values, and metric-value filters for selecting groups of events based on summary statistics.

Table 2 Report Option Object Fields¶
Fields	Description	Data Type
`timezone`	Specifies a string that defines time zone of report data. If no `timezone` value is specified, the `America/New_York` attribute is used. Options include: `America/Los_Angeles` `America/Denver` `America/Chicago` `America/El_Salvador` `America/Mexico_City` `America/New_York` `America/Bogota` `America/Lima` `America/Halifax` `America/Puerto_Rico` `America/Argentina/Buenos_Aires` `America/Santiago` `America/Sao_Paulo` `Etc/GMT` `Europe/London` `Europe/Paris` `Asia/Jerusalem` `Asia/Debai` `Asia/Karachi` `Asia/Dhaka` `Asia/Jakarta` `Australia/Perth` `Asia/Shanghai` `Asia/Tokyo` `Australia/Sydney` `Pacific/Auckland` Note: The time zone defines an offset value that must be taken into account when defining the `startDate` and `endDate` of custom report periods. If the report is for a custom date range (`dateTypeId` = `11`, you must specify an offset value in custom date range values. To learn more, see Time Zones.	`string`
`currency`	Specifies the denomination used in reports. By default, all report data is in US dollars (USD). If other currencies are used, you may specify an alternative currency. In Verizon Media DSP, you can specify the denomination at the seat level, advertiser-level, or campaign level. Options include: `1`: Seat `2`: Advertiser `3`: Campaign `4`: USD (default)	`integer`
`dimensionTypeIds`	Specifies an array of dimension type IDs that identify the dimensions of data returned in the report. If omitted, the report returns the time dimension only. Specifies the group by. To learn more, see Dimensions.	`array`
`filterOptions`	Specifies an array of Filter Option objects. Each object identifies a report dimension to include in or exclude from the report and the allowed values. To learn more, see Filter Option Object.	`array`
`metricTypeIds`	Specifies an array of the metric type IDs that specify the metrics measured in the report. To learn more, see Metrics.	`array`
`accountIds`	Specifies an array of advertiser account IDs. If you have access to multiple advertiser accounts, you can filter the report data returned by account ID. To learn more, see Advertisers.	`array`
`having`	Specifies an object consisting of a `type` operator and a `havingSpecs` array, which defines an array of Spec objects. The `having` object enables you to filter report data using a set of dimension and metric values. To learn more, see Having Object.	`object`

Report Option Object Example¶

The reportOption object specifies a report with custom date range (dateTypeId = 11), which enables you to specify custom start (startDate) and end (endDate) dates for report data.

Note that if you do specify a custom date range, you must ensure that the startDate and endDate values include the correct offsets for the specified timezone. The Asia/Shanghai time zone requires an offset of UTC+8. Consequently, the offset is appended to the specified startDate and endDate values.

{
  "reportOption": {
    "timezone": "Asia/Shanghai",
    "currency": 3,
    "dimensionTypeIds": [ 1, 3, 4, 5, 6, 64 ],
    "filterOptions": [
      {
        "dimensionTypeId": 64,
        "isExcluded": false,
        "includeValues": [ {"id": 7} ]
      }
    ],
    "metricTypeIds": [ 1, 2, 23, 44, 46 ]
  },
  "intervalTypeId": 1,
  "dateTypeId": 11,
  "startDate": "2018-02-05T23:59:59+08:00",
  "endDate": "2018-02-06T23:59:59+08:00",
}

The filterOptions object enables you to filter the data returned in a report by advertiser account. Report data is filtered by advertiser group (dimensionTypeId: 64) with an ID of 7.

Filter Option Object¶

The filterOptions array specifies the dimensions of data included in the report. Each of an Filter Option object identifies a report dimension to include in or exclude from the report and the allowed values.

Table 3 Filter Option Object Fields¶
Fields	Description	Data Type
`dimensionTypeId`	Specifies a dimension type ID. To learn more, Dimensions.	`integer`
`isExcluded`	Specifies whether the specified `dimensionTypeId` is included in or excluded from the report. Options include: If `true`, the specified `dimensionTypeId` is excluded from the report. If `false`, the specified `dimensionTypeId` is included in the report.	`boolean`
`includeValues`	Specifies an array of `dimensionTypeId` values that are included in the report.	`array`

Having Object¶

The having object enables you to filter report data by a set of specified dimension and metric values.

The having object specifies a type operator and a havingSpecs array, which defines an array of Spec objects.

Table 4 Having Object Fields¶
Fields	Description	Data Type
`type`	Specifies an operator for selecting the metrics that are included in the report. Options include: `and` `equalTo` `greaterThan` `or` `lessThan` `not`	`string`
`havingSpecs`	Specifies an array of Spec objects that enable you to filter the metrics returned in the report. Each Spec object identifies a report metric ID, an operator, and metric value. To learn more, see Spec Object.	`array`

Having Object Payload¶

{
  "reportOption": {
    "timezone": "America/Los_Angeles",
    "currency": 4,
    "dimensionTypeIds": [ 5 ],
    "filterOptions": [
      {
        "includeValues": [
          {
            "name": "France",
            "id": "250"
          }
        ],
       "isExcluded": "false",
        "dimensionTypeId": 19
      }
    ],
    "metricTypeIds": [ 1, 2, 23 ],
    "having": {
      "type": "and",
      "havingSpecs": [
        {
          "type": "greaterThan",
          "metricTypeId": 1,
          "value": 1
        }
      ]
    }
  },
  "intervalTypeId": 2,
  "dateTypeId": 11,
  "startDate": "2016-11-01T00:00:00-08:00",
  "endDate": "2016-11-01T23:59:59-08:00"
}

Spec Object¶

The havingSpecs array contains one or more Spec objects. Each Spec object enables you to filter the metrics returned in the report. Each Spec object identifies a report metric ID, an operator, and metric value.

Table 5 Spec Object Fields¶
Fields	Description	Data Type
`metricTypeId`	Specifies a metric type ID. To learn more, see Metrics.	`string`
`type`	Specifies a comparison operator for specifying report metrics. Options include: `and` `equalTo` `greaterThan` `or` `lessThan` `not`	`string`
`value`	Specifies a `metricTypeId` value.	`integer`

Limit Spec Object¶

The limitSpec object specifies the maximum number of rows returned (top-N) and their sort order (ascending or descending).

Table 6 Limit Spec Object Fields¶
Field	Description	Data Type	Required
`columns`	Specifies an array of Spec objects that consist of the `direction` and `metricTypeId`. The `metricTypeId` attribute specifies a metric type. The `direction` attribute specifies the sort order for data based on the specified metric type ID. Options include: `ASCENDING` and `DESCENDING`.	`array`	Y
`limit`	Specifies the maximum number of columns returned by the report.	`integer`	Y
`type`	Specifies the spec type. Options include: `default`	`string`	N

Example¶

{
  "reportOption": {
    "timezone": "America/Los_Angeles",
    "currency": 4,
    "dimensionTypeIds": [ 5 ],
    "filterOptions": [
      {
        "includeValues": [
          {
            "name": "France",
            "id": "250"
          }
        ],
       "isExcluded": "false",
        "dimensionTypeId": 19
      }
    ],
    "metricTypeIds": [ 1, 2, 23 ],
    "limitSpec": {
      "columns": [
        {
          "direction": "DESCENDING",
          "metricTypeId": 2
        }
      ],
      "limit": 10000,
      "type": "default"
    }
  },
  "intervalTypeId": 2,
  "dateTypeId": 11,
  "startDate": "2016-11-01T00:00:00-08:00",
  "endDate": "2016-11-01T23:59:59-08:00"
}

Create Reports¶

Creates a report.

POST /extreport/

Parameters¶

All parameters are specified in the body of the application/json payload.

Parameter Parameter Type Description Data Type Required

reportOption

body

Specifies an object that defines key report attributes including the report time zone, an array of dimension type IDs, an array of metric type IDs, filter options, and having options.

To learn more, see Report Option Object.

object

currency

body

Specifies the denomination used in report data.

In Verizon Media DSP, you can specify the denomination at the seat level, advertiser-level, or campaign level. Options include:

1: Seat
2: Advertiser
3: Campaign
4: USD (default)

integer

limitSpec

body

Specifies the number of rows returned in the report.

To learn more, see Limit Spec Object.

object

dateTypeId

body

Specifies the date type ID, which is used to define the interval of data returned in the report. Options include:

1: Today
2: Yesterday
3: This Week
4: Last 7 Days
5: Last Week
6: Last 14 Days
7: Month to Date
8: Last 30 Days
9: Last Month
10: All Time
11: Custom Range

Note: Option 11 (All Time) returns extremely large reports. Use it with a filter, and/or cumulative interval type.

For best results, ensure that the report excludes data from the six hours prior to the report date. To learn more, see Reporting API Limitations.

integer

intervalTypeId

body

Specifies an interval type ID.

The interval type defines the granularity of report time intervals. Options include:

1: Cumulative. Returns a single row in which each column displays data for the entire range.
2: Day. Returns one row for each calendar day in the specified date range.
3: Month. Returns one row for each full or partial month in the specified date range.
4: Week. Returns one row for each calendar week in the specified date range.
5: Hour. Returns one row for each hour that has data.

To learn more, see Report Intervals.

integer

startDate

body

Specifies the start time of date range of the report in the format yyyy-MM-dd'T'HH:mm:ss.

[1]	Required if the `displayTypeId` is `11`.

string

Y [1]

endDate

body

Specifies the start time of date range of the report in the format yyyy-MM-dd'T'HH:mm:ss.

[2]	Required if the `displayTypeId` is `11`.

string

Y [2]

Example Request¶

The request must specify an access token and the request payload:

curl -X POST "http://api-sched-v3.admanagerplus.yahoo.com/yamplus_api/extreport/" \
  -H "Content-Type: application/json" \
  -H "X-Auth-Method: OAUTH" \
  -H "X-Auth-Token: <<ACCESS_TOKEN>>" \
  -d '{
        "reportOption": {
            "timezone": "America/New_York",
            "currency": 4,
            "dimensionTypeIds": [ 5 ],
            "metricTypeIds": [ 44, 1, 2, 23, 11, 41, 43 ]
        },
        "intervalTypeId": 1,
        "dateTypeId": 2,
        "startDate": "2016-07-10T00:00:00-05:00",
        "endDate": "2016-07-10T11:59:59-05:00"
    }'

Substitute your access token for the <<ACCESS_TOKEN>> placeholder. To learn more, see Generate New Access Tokens.

Example Response¶

{
  "customerReportId": "aa78d3a1-5548-4484-8911-4c0a8eea877f",
  "status": "SUBMITTED"
}

The response contains the following fields:

Parameter Type Description

customerReportId string Unique report ID. Use this in GET call to fetch the URL of the report.

Parameter	Type	Description
`customerReportId`	`string`	Unique report ID. Use this in `GET` call to fetch the URL of the report.
`status`	`string`	Current status of the report generation. `SUCCESS`: Report successfully created. `FAILED`: Report generation failed. `SUBMITTED`: Report request is in queue. `PROCESSING`: Report generation is in progress.

status

string

Current status of the report generation.

SUCCESS: Report successfully created.
FAILED: Report generation failed.
SUBMITTED: Report request is in queue.
PROCESSING: Report generation is in progress.

Multiple Seat Request Example¶

Advertisers with access to multiple seat may return data associated with those seats using a Filter Option Object. The object must specify the seat dimension ID in the dimensionTypeId attribute and one or more seat IDs in the Filter Option object’s includeValues array.

{
  "reportOption": {
    "timezone": "Asia/Shanghai",
    "currency": 3,
    "dimensionTypeIds": [ 1, 3, 4, 5, 6, 64 ],
    "filterOptions”: [
      {
        "dimensionTypeId": 56,
        "isExcluded": false,
        "includeValues": [ {“id”:234}, {“id”:235}]
      }
    ],
    "metricTypeIds": [ 1, 2, 23, 44, 46 ]
  },
  "intervalTypeId": 1,
  "dateTypeId": 11,
  "startDate": "2016-11-06T00:00:00+08:00",
  "endDate": "2016-11-06T23:59:59+08:00"
}

If no seat Filter Object is defined, the response returns data based on the user’s current seat in the Verizon Media DSP console.
If a seat Filter Object is defined, the response returns data based on the seat IDs included in the request payload.

Users must have the appropriate privileges to access multiple seats. To learn more, see Seats.

Read Report Status¶

Use the GET method to retrieve the report status and a temporary URL to the report.

GET /extreport/{customerReportId}

The Reporting API returns a URL to the report that you may use to download the report. The URL is valid for 24 hours after report creation.

The report URL is only valid for 24 hours after the report is generated. To ensure the privacy of your data, the URL expires after 24 hours and the returned report cannot be accessed.

All reports are returned in CSV format.

Parameters¶

The request must specify the customerReportId:

Table 8 Create Report Request Parameters¶
Parameter	Parameter Type	Description	Data Type	Required?
`customerReportId`	path	Specifies the report’s unique ID.	`string`	Y

Example Request¶

The request must specify an access token and the customerReportId.

GET http://api-sched-v3.admanagerplus.yahoo.com/yamplus_api/extreport/{customerReportId}

For example,

curl -X GET "http://api-sched-v3.admanagerplus.yahoo.com/yamplus_api/extreport/aa78d3a1-5548-4484-8911-4c0a8eea877f" \
  -H "Content-Type: application/json" \
  -H "X-Auth-Method: OAUTH" \
  -H "X-Auth-Token: <<ACCESS_TOKEN>>"

Replace <<ACCESS_TOKEN>> with the generated OAUTH access token. To learn more, see the Generate New Access Tokens.

Example Response¶

{

  "customerReportId": "eb20bded-06d0-4d1f-b1d3-dde627d0f3f6",

  "status": "Success",

  "url": "https://test.csv",

  "reportFormat": "CSV",

  "requestPayload": "{\"reportOption\":
  {\"timezone\":\"America/New_York\",\"currency\":4,\"accountIds\":[23769],\"dimensionTypeIds\":[],\"metricTypeIds\":[1,2,44,110]},\"intervalTypeId\":2,\"dateTypeId\":11,\"startDate\":\"2017-09-09T00:00:00-04:00\",\"endDate\":\"2017-10-09T23:59:59-04:00\"}",

  "jobStartDate": "2017-10-17T17:24:01.000-07:00",

  "jobEndDate": "2017-10-17T17:24:01.000-07:00",

  "numRows": 1017

}

The response contains the following fields:

Table 9 Read Report Status Response Parameters¶
Parameter	Description	Data Type
`customerReportId`	Specifies a unique report ID.	`string`
`status`	Specifies the current status of the report request. Four statuses are supported: `SUCCESS`: Report successfully created. `FAILED`: Report generation failed. `SUBMITTED`: Report request is in queue. `PROCESSING`: Report generation is in progress.	`string`
`url`	If the report is generated, displays a temporary URL that can be used to download the report. Note: The report URL is valid for only one hour.	`string`
`reportFormat`	Specifies the format of the report: CSV	`string`
`requestPayload`	Specifies the payload submitted in the Create Report request. To learn more about request payloads, see /reporting/payloadspec/index.	`object`
`jobStartDate`	Specifies the date and time that the report started.	`string`
`jobEndDate`	Specifies the date and time that the report ended.	`string`
`numRows`	Specifies the number of rows returned in the report.	`number`