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 Oath Ad Platforms 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 Oath Ad Platforms 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 Oath Ad Platforms 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.

Table 7 Reporting Payload Parameters
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 Y
currency body

Specifies the denomination used in report data.

In Oath Ad Platforms 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 N
limitSpec body

Specifies the number of rows returned in the report.

To learn more, see Limit Spec Object.

object N
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 Y
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 Y
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.
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 Oath Ad Platforms 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