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

• The Close Of Books resource returns an indication for book closed for specific advertiser.

All requests require a valid access token. To learn more, refer to DSP Authentication.

Endpoints

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

http://api-sched-v3.admanagerplus.yahoo.com/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.

http://api-sched-v3.admanagerplus.yahoo.com/yamplus_api/extreport/cob

Call to retrieve close of book status:

• To retrieve close of book status call the endpoint using the GET method and specify advertiserId and day.

Resources

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

Reporting Object

All Yahoo 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.

• The accountIds attribute enables you to filter report data by advertiser account by specifying an array of advertiser account IDs.

• The reportOption object enables you to specify report dimensions and metrics.

• The dateTypeId, startDate, and endDate attributes enable you to specify the reporting period.

• The intervalTypeId attribute enables you to specify the granularity of report data within a data set.

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.

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

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.

Note

Although an advertiser filter (dimensionTypeId 4) will work, we recommended that you use the accountIds payload field instead.

Filter Option Object

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

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.

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.

Limit Spec Object

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

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.

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: OAuth2" \
  -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, refer to Generate the Access Token.

Example Response

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

The response contains the following fields:

Create a Bidding Report

Create a report that displays ad bidding performance insights per advertiser, campaign, package or line.

POST /extreport/

Parameters

All parameters are specified in the request body.

Example Request

The following request provides an example of creating a bidding report to display the number of qualified bid requests and average win rate per campaign.

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

Ensure that your access token replaces the <<ACCESS_TOKEN>> placeholder. To learn more, refer to Setup & Access Guide.

Example Response

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

The response contains the following fields:

Multiple Seat Request Example

Advertisers with access to multiple seats 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 Yahoo 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, refer to 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:

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: OAuth2" \
  -H "X-Auth-Token: <<ACCESS_TOKEN>>"

Replace <<ACCESS_TOKEN>> with the generated OAuth2 access token. To learn more, refer to Generate the Access Token.

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:

Close Of Books Status

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

To check COB for a specific advertiser, the user must have the AdvertiserManager or Advertiser Report role for that advertiser.

GET /extreport/cob

The Reporting API returns the advertiser book status in a specific day.

Example Request

The request must specify an access token and the /cob.

GET http://api-sched-v3.admanagerplus.yahoo.com/yamplus_api/extreport/cob?advertiserId=...&day=...

Parameters

The request must specify the /cob:

For example,

curl -X GET "http://api-sched-v3.admanagerplus.yahoo.com/yamplus_api/extreport/cob?advertiserId=1234&day=20210701" \
  -H "Content-Type: application/json" \
  -H "X-Auth-Method: OAuth2" \
  -H "X-Auth-Token: <<ACCESS_TOKEN>>"

Replace <<ACCESS_TOKEN>> with the generated OAuth2 access token. To learn more, refer to Generate the Access Token.

Example Response

{
  "advertiserTimezone": "America/New_York",
  "dayClosed": "true"
}

The response contains the following fields: