REST API - Reporting
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 "