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 "