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 thecustomerReportId
.
Resources¶
The Reporting object comprises multiple objects, which consist of separate objects. The following resource objects are described separately:
|
|
|
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.
Parameter |
Description |
Data Type |
---|---|---|
|
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. |
|
|
Specifies the number of rows returned in the report. To learn more, see Limit Spec Object. |
|
|
Specifies the reporting period, the span of time covered by the data set. Options include:
To learn more, see Reporting Periods. |
|
|
Specifies the granularity of report intervals. Options include:
To learn more, see Report Intervals. |
|
|
Specifies the start time of date range of the report in the format |
|
|
Specifies the start time of date range of the report in the format |
|
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.
Fields |
Description |
Data Type |
---|---|---|
|
Specifies a string that defines time zone of report data. If no Options include:
Note: The time zone defines an offset value that must be taken into account when defining the |
|
|
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:
|
|
|
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. |
|
|
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. |
|
|
Specifies an array of the metric type IDs that specify the metrics measured in the report. To learn more, see Metrics. |
|
|
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. |
|
|
Specifies an object consisting of a To learn more, see Having 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.
Fields |
Description |
Data Type |
---|---|---|
|
Specifies a dimension type ID. To learn more, Dimensions. |
|
|
Specifies whether the specified
|
|
|
Specifies an array of |
|
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.
Fields |
Description |
Data Type |
---|---|---|
|
Specifies an operator for selecting the metrics that are included in the report. Options include:
|
|
|
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. |
|
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.
Fields |
Description |
Data Type |
---|---|---|
|
Specifies a metric type ID. To learn more, see Metrics. |
|
|
Specifies a comparison operator for specifying report metrics. Options include:
|
|
|
Specifies a |
|
Limit Spec Object¶
The limitSpec
object specifies the maximum number of rows returned (top-N) and their sort order (ascending or descending).
Field |
Description |
Data Type |
Required |
---|---|---|---|
|
Specifies an array of Spec objects that consist of the
|
|
Y |
|
Specifies the maximum number of columns returned by the report. |
|
Y |
|
Specifies the spec type. Options include:
|
|
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 |
---|---|---|---|---|
|
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. |
|
Y |
|
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:
|
|
N |
|
body |
Specifies the number of rows returned in the report. To learn more, see Limit Spec Object. |
|
N |
|
body |
Specifies the date type ID, which is used to define the interval of data returned in the report. Options include:
Note: Option 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. |
|
Y |
|
body |
Specifies an interval type ID. The interval type defines the granularity of report time intervals. Options include:
To learn more, see Report Intervals. |
|
Y |
|
body |
Specifies the start time of date range of the report in the format
|
|
Y 1 |
|
body |
Specifies the start time of date range of the report in the format
|
|
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 |
---|---|---|
|
|
Unique report ID. Use this in |
|
|
Current status of the report generation.
|
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
:
Parameter |
Parameter Type |
Description |
Data Type |
Required? |
---|---|---|---|---|
|
path |
Specifies the report’s unique ID. |
|
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:
Parameter |
Description |
Data Type |
---|---|---|
|
Specifies a unique report ID. |
|
|
Specifies the current status of the report request. Four statuses are supported:
|
|
|
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. |
|
|
Specifies the format of the report: CSV |
|
|
Specifies the payload submitted in the Create Report request. To learn more about request payloads, see /reporting/payloadspec/index. |
|
|
Specifies the date and time that the report started. |
|
|
Specifies the date and time that the report ended. |
|
|
Specifies the number of rows returned in the report. |
|