Resources

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

Overview

The DSP 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.

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 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

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": 11,
        "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 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