Bidders get reports via API. The following limitations apply to fetching reports.
A single authentication may have more than 1 DSP associated with it and can pull reports for any of them. Some metrics are only available if the DSP is used as a dimension.
Use this API to pull information based on specified dimensions and metrics.
Scheme: HTTP
Method: GET /API/V1/brxd/report
Content-Type: application/json
REST Endpoint
https://api.yax.yahoo.com/API/V1/report [“?” [modifiers] [& selectors] ]
Selectors may contain any field names from the dimension and metric table. Separate multiple field names with a comma. Modifiers are specified in the resource modifier directive table.
The fields that appear in Modifiers must also be added in Selectors.
Resource Modifier
Used to set a condition for the resource of concern.
|
Token |
Definition |
|---|---|
|
modifiers |
“modifiers=” &(modifier) |
|
modifier |
key.operator [.sort] |
|
key |
name of any dimensions and metrics listed below. |
|
operator |
[ ! ] ( g t | l t | e q | n i l | i n | l i k e ) |
|
! |
to negate a following operator |
|
gt |
“gt” “(“ {value} “)” the value of a keyed field should be greater than an enclosed value |
|
lt |
“lt” “(“ {value} “)” the value of a keyed field should be less than an enclosed value |
|
eq |
“eq” “(“ {value} “)” the value of a keyed field should be equal to an enclosed value |
|
nil |
“nil(1)” or “nil(0)” the value of a keyed field is nil “1” or not nil “0” |
|
in |
“in” “(“ *{value} “)” the value of a keyed field is equal to one of values, separated by semicolon or comma |
|
like |
“like” “(“ {value} “)” the value of a keyed field should contain a case-insensitive enclosed value |
|
sort |
“sort(0)” or “sort(1)” sort a collection on a keyed field in either ascending “0” or descending “1” order |
|
Limit * |
“limit” “(“ {size} “)” User sets the limit for number of rows to be returned, must be between 0-500,000 |
* = mandatory, otherwise optional
Parameters
|
Field Name |
Type |
Description |
Modifier Support |
|---|---|---|---|
|
startdate* |
date |
Specify the start date for the report data |
startdate.eq() |
|
enddate* |
date |
Specify the end date for the report data |
enddate.eq() |
|
interval* |
string |
Enum: “Cumulative”, “Day”, “Month”, “Week”, “Hour” |
interval.eq() |
|
timezone |
string |
See available ids of java.util.TimeZone. Eg. “America/Los_Angeles”. |
timezone.eq() |
* = mandatory, otherwise optional
Dimensions
|
Dimension Name |
Type |
Description |
Modifier Support |
|---|---|---|---|
|
dspid |
Long array |
dsp id as dimension. |
dspid.eq(), dspid.in() |
|
wseat |
String array |
buyer id as dimension |
wseat.eq(), wseat.in() |
|
seat |
Long array |
supply seat id as dimension |
Seat should be passed through “current_seat” header |
|
dealid |
Long array |
deal id as dimension. |
dealid.eq(), dealid.in(), dealid.sort() |
|
adsize |
String array |
ad size as dimension. format: width x height (eg. 300x200) |
adsize.eq(), adsize.in() |
|
bidlossreason |
Int array |
bid loss reason as dimension. use enum ID instead of string. enum mapping is listed in the following page. Can’t use with fields in asterisk below. |
bidlossreason.eq(), bidlossreason.in(), bidlossreason.sort() |
Metrics
|
Field Name |
Type |
Description |
|---|---|---|
|
impressions |
long |
Impression on VMX |
|
revenue |
double |
Total amount payable by the Buyer |
|
eCPM |
double |
The average effective cost-per-thousand-impressions calculated from the ads delivered by VMX |
|
bidrequests |
long |
Total bid requests sent to the buyer/DSP |
|
bidresponses |
long |
Total bid responses received from buyer/DSP |
|
Nobids * |
long |
Total ‘No bids’ responses by DSP |
|
Timeouts * |
long |
Total bid requests for which DSP did not respond within given latency |
|
bidthrottled * |
long |
Bid requests not sent due to qps constraint set for DSP |
|
badresponses * |
long |
Incorrectly constructed responses |
* Displayed when DSP is the only dimension.
Result Object
|
Field Name |
Type |
Description |
|---|---|---|
|
errors |
String array |
errors information |
|
headers |
String array |
string array from the selectors, which is all the columns that users interest. if dspid is selected as selector, it is followed by its corresponding DSP name |
|
data |
array of string array |
report data according to selected impressions and metrics |
Request and Response Example
GET https://api.yax.yahoo.com/API/V1/brxd/creatives/report?modifiers=bidresponse.gt(111),wseat.eq(<buyer seat>)&selectors=wseat,revenue,bidresponse
{
"result": {
"errors": [],
"dataObject": {
"reportResult": {
"headers": [
{
"id": "demand_seat_id",
"name": "Buyer",
"adwColumnName": "demand_seat_id",
"isDate": false,
"isMetric": false,
"dimensionType": "DemandSeat",
"excelName": "Buyer"
},
{
"id": "demand_seat_id_name",
"name": "DemandSeat",
"adwColumnName": "demand_seat_id",
"isDate": false,
"isMetric": false,
"excelName": "DemandSeat"
},
{
"id": "timestamp",
"name": "Day",
"adwColumnName": "timestamp",
"isDate": true,
"isMetric": false,
"excelName": "Day"
},
{
"id": "revenue",
"name": "Revenue",
"adwColumnName": "revenue",
"isDate": false,
"isMetric": true,
"metricType": "Revenue",
"unit": "Currency",
"excelName": "Revenue"
},
{
"id": "bidrequestcount",
"name": "BidResponseCount",
"adwColumnName": "bidrequestcount",
"isDate": false,
"isMetric": true,
"metricType": "BidRequestCount",
"unit": "Count",
"excelName": "BidResponseCount"
}
],
"data": [
[
"10925",
"Buyer Seat",
"2016-07-19T00:00:00.000-04:00",
"2862.4736099243164",
"18536961"
]
],
"dataWithColumnNames": [
{
"revenue": "2862.4736099243164",
"bidrequestcount": "18536961",
"total_pub_payment": "0.0",
"total_supply_payment": "2862.4736099243164",
"demand_seat_id": "10925",
"timestamp": "2016-07-19T00:00:00.000-04:00",
"demand_seat_id_name": "Client"
}
],
"totals": {
"revenue": "2862.4736099243164",
"bidrequestcount": "18536961",
"total_pub_payment": "0.0",
"total_supply_payment": "2862.4736099243164"
}
}
},
"operationResult": "Success"
}
}
Curl Example
curl -X GET -H "Authorization: Bearer <token>" -H "X-Yahoo-Guid: <guid>" -H "Content-Type: application/json" "/API/V1/brxd/report?selectors=dspid,impressions,wseat&modifiers=dspid.eq(<DSP ID>),limit(10),interval.eq(Day),startdate.eq(2017-05-01),enddate.eq(2017-06-15)&selectors=impressions,revenue "
