Digital Platform API - Seller Brand Review report
This report provides a view of brand performance across all of your inventory. You can:
- review what creative has served on your inventory and how it performed.
- review creative performance by audit status.
- review client brand category performance across all of your inventory.
The time_granularity of the data is daily. For instructions on retrieving a report, see the Report Service or the Example below.
Time frame
The report_interval field in the JSON request must be set to one of the following:
- yesterday
- last_7_days
- last_30_days
- month_to_date
- last_month
Tip
To run a report for a custom time frame, set the start_date and end_date fields in your report request. For more details about these fields, see Report Service.
Data retention period
Data retention period for this report is 428 days.
Dimensions
| Column | Type | Filter? | Example | Description |
|---|---|---|---|---|
month |
time | no | "2010-02" |
The month of the auction. |
day |
time | no | "2010-02-01" |
The day of the auction. |
buyer_member_id |
int | yes | 643 |
The ID of the member that won the auction. |
buyer_seat_name |
string | no | "My Custom Seat" |
The display name for the buyer seat code. |
buyer_seat_id |
int | yes | 123 |
The ID of the buyer seat. |
buyer_seat_code |
string | no | "Custom Seat" |
The Custom Buyer Seat ID (submitted by DSP) which was used to bid on the impression. |
bidder |
int | no | Deprecated. | |
bidder_name |
int | no | "Microsoft Invest" |
The name of the bidder. |
bidder_id |
int | no | 2 |
The bidder ID of the member. |
curator_member_id |
int | yes | 10652 |
The ID of the curator member. |
placement_id |
int | yes | 546 |
The ID of the placement. |
placement_name |
string | no | "300x250 Business" |
The name of the placement. |
placement |
string | no | "300x250 Business (546)" |
Deprecated. |
publisher_id |
int | yes | 6787 |
The ID of the publisher. |
geo_country |
string | yes | "US" |
The code of the geographical country. |
geo_country_name |
string | no | "United States" |
The name of the geographical country. |
imp_type |
string | yes | "Kept" |
Deprecated. |
imp_type_id |
int | yes | 1 |
The ID for the type of impression. Possible values (associated types in parentheses):1 ("Blank"): No creative served.2 ("PSA"): A public service announcement served because there were no valid bids and no default creative was available.3 ("Default Error"): A default creative served due to a timeout issue.4 ("Default"): A default creative served because there were no valid bids.5 ("Kept"): Your advertiser's creative served on your publisher's site.6 ("Resold"): Your publisher's impression was sold to a third-party buyer.7 ("RTB"): Your advertiser's creative served on third-party inventory.8 ("PSA Error"): A public service announcement served due to a timeout issue or lack of a default creative.9 ("External Impression"): An impression from an impression tracker.10 ("External Click"): A click from a click tracker. |
creative_id |
int | yes | 654 |
The ID of the creative. |
site_id |
int | yes | 555 |
The ID of the site. For more information, see the Site Service. |
site_name |
string | no | "My Site" |
The name of the site. For more information, see the Site Service. |
brand_id |
int | yes | 3 |
The ID of the brand associated with a creative served on the publisher's inventory. |
brand_name |
string | no | "Ace Hardware" |
The name of the brand associated with a creative served on the publisher's inventory. |
brand |
string | no | "Ace Hardware (3)" |
Deprecated. |
payment_type |
string | yes | "cpm" |
The type of payment to the broker. |
revenue_type |
string | no | "cpm" |
The way the advertiser has agreed to pay you. |
revenue_type_id |
int | yes | 4 |
The ID of the revenue type. Possible values:-1 = No Payment0 = Flat CPM1 = Cost Plus CPM,2 = Cost Plus Margin3 = CPC4 = CPA5 = Revshare6 = Flat Fee7 = Variable CPM8 = Estimated CPM |
width |
int | yes | 250 |
The width of the creative. |
height |
int | yes | 300 |
The height of the creative. |
site |
string | no | "My Site (555)" |
Deprecated. |
publisher_code |
string | no | "My Publisher Code" |
The custom code for the publisher. |
site_code |
string | no | "Site Name Code" |
The custom code for the site. |
placement_code |
string | no | "Photos Code" |
The custom code for the placement. |
buyer_member_name |
string | no | "Network" |
The name of the buying member. |
buyer_member |
string | no | "Network (567)" |
Deprecated. |
media_type |
string | yes | "Banner", "Pop", "Interstitial", "Video", "Text" |
The general display style of a creative served on the publisher's inventory. You can use the Media Type Service to view the complete list of media types. |
mediatype_id |
int | yes | 444 |
The ID of the media type associated with the creative that was served. For more information, see the Media Type Service. |
publisher_name |
string | no | "LOL - US" |
The name of the publisher on whose site the impression occurred. |
publisher |
string | yes | "LOL - US (44389)" |
Deprecated. |
deal_id |
int | yes | 2345 |
The ID of the deal. For more information about deals you have negotiated with buyers, see Deal Service. |
deal_name |
string | no | "Private deal for buyer 1085 with floor of $2.50" |
The name of the deal. |
deal_type |
string | yes | 1 |
The ID representing the type of deal. Possible values:1 = Open Auction2 = Private Auction4 = Programmatic Guaranteed5 = Curated Auction |
deal |
string | no | "Private deal for buyer 1085 with floor of $2.50 (45)" |
Deprecated. |
deal_code |
string | no | "Custom code" |
The custom code for the deal. |
brand_offer_category_id |
int | yes | 1256 |
The ID of the brand offer category associated with the impression. See category_id in the Brand Service page. |
brand_offer_category_name |
string | no | "Luxury Cars" |
The name of the brand offer category associated with the impression. See category_id in the Brand Service page. |
creative_audit_status_id |
int | yes | 0 |
The ID of the audit status of the creative associated with the impression:0 = unaudited1 = seller audited only2 = appnexus audited |
creative_audit_status |
string | no | "Unaudited" |
The audit status of the creative associated with the impression: - "Unaudited"- "Self Audit Only"- "AppNexus Audited" |
size |
string | yes | "728x90" |
The width and height of the creative associated with the impression. |
Metrics
| Column | Type | Example | Formula | Description |
|---|---|---|---|---|
imps |
int | 34534 |
imps | The total number of impressions (including defaults). |
clicks |
int | 345 |
clicks | The total number of clicks across all impressions. |
cost |
money | 16.833378 |
cost | The total amount of media cost for direct publisher and purchased real-time inventory. |
revenue |
money | 25.767257 |
booked_revenue + reseller_revenue | The sum of booked revenue and reseller revenue. |
booked_revenue |
money | 25.767257 |
booked_revenue | The total revenue booked through direct advertisers (line item). |
reseller_revenue |
money | 0 |
reseller_revenue | The total revenue on resold impressions through direct publishers. |
profit |
money | 970.40 |
booked_revenue - total_cost | Booked revenue minus total cost. |
cpm |
money | 1.66051685393258 |
(cost / imps) x 1000 | The cost per 1000 impressions. |
total_convs |
int | 5 |
total_convs | The total number of post-view and post-click conversions. |
convs_rate |
double | 0.000221877080097626 |
total_convs / imps | The rate of conversions to impressions. |
ctr |
double | 0.002327 |
clicks / imps | The rate of clicks to impressions. |
rpm |
money | 2.60548314606741 |
(revenue / imps) x 1000 | The revenue per 1000 impressions. |
ppm |
money | 0.944966292134831 |
(profit / imps) x 1000 | To be deprecated. The profit per 1000 impressions. |
convs_per_mm |
double | 221.877080097625 |
(total_convs / imps) x 1,000,000 | The number of conversions per million impressions. |
imps_viewed |
int | 30,450 |
imps_viewed | The number of measured impressions that were viewable, per the IAB Viewability definition, which states that an impression is viewable if 50% of the pixels are in-view during 1 consecutive second. |
view_measured_imps |
int | 10,120 |
view_measured_imps | The total number of impressions that were measured for viewability. |
view_rate |
double | 58% |
view_rate | The percentage of impressions that were viewable out of the total number of impressions measured for viewability. (Viewed Imps / View Measured Imps) |
view_measurement_rate |
double | 45% |
view_measurement_rate | The percentage of impressions measured for viewability out of the total number of impressions. (View Measured Imps / Imps) |
total_cost |
money | 123.45 |
total_cost = media_cost + data_costs + partner_fees + commissions + serving_fees + publisher_revenue | The total amount of costs accrued over the reported period of time. This generally includes two types of costs, budgeted costs (media cost, data cost, partner fees, serving fees, commissions) and publisher revenue if you track publisher payouts on the platform. Note: We have added logic to prevent double counting third-party fees during the breaking change period. |
total_cost_ecpm |
money | 123.45 |
(total_cost/imps) * 1,000 | The total cost per 1,000 imps. |
total_cost_ecpc |
money | 123.45 |
total_cost/clicks | The total cost per click. |
total_cost_ecpa |
money | 123.45 |
total_cost/conversions | The total cost per conversion. |
network_profit |
money | 123.45 |
(booked_revenue + reseller_revenue) - total_cost | The sum of booked revenue and reseller revenue minus total cost. |
network_profit_ecpm |
money | 123.45 |
(network_profit/imps) * 1,000 | Network profit per 1,000 imps. |
network_profit_ecpc |
money | 123.45 |
network_profit/clicks | Network profit per click. |
network_profit_ecpa |
money | 123.45 |
network_profit/conversions | Network profit per conversion. |
network_profit_margin |
money | 123.45 |
network_profit/(booked_revenue + reseller_revenue) | Network profit margin. |
profit_ecpm |
money | 123.45 |
((booked_revenue - total_cost)/imps) * 1,000 | Profit per 1,000 imps. |
profit_ecpc |
money | 123.45 |
(booked_revenue - total_cost)/clicks | Profit per click. |
profit_ecpa |
money | 123.45 |
(booked_revenue - total_cost)/conversions | Profit per conversion. |
profit_margin |
money | 123.45 |
(booked_revenue - total_cost)/booked_revenue | Buyer profit margin. |
Example
Create a JSON report request
The JSON file should include the report_type of "seller_brand_review", as well as the columns (dimensions and metrics) and report_interval that you want to retrieve. You can also filter for specific dimensions, define granularity (year, month, day), and specify the "format" in which the data should be returned (csv, excel, or html). For a full explanation of fields that can be included in the JSON file, see the Report Service.
$ cat seller_brand_review
{"report":
{
"format": "csv",
"report_interval": "yesterday",
"row_per": ["geo_country"],
"columns": ["placement_id","imp_type_id","creative_id","brand_id","geo_country"],
"report_type": "seller_brand_review"
}
}
POST the request to the Report Service
POST the JSON request to get back a report ID.
$ curl -b cookies -c cookies -X post -d @seller_brand_review "https://api.appnexus.com/report"
{
"response":{
"status":"OK",
"report_id":"c445bca183a3d338dc1c5b85a3d484f5"
}
}
GET the report status from the report service
Make a GET call with the report ID to retrieve the status of the report. Continue making this GET call until the execution_status is "ready". Then use the report-download service to save the report data to a file, as described in the next step.
$ curl -b cookies -c cookies 'https://api.appnexus.com/report?id=c445bca183a3d338dc1c5b85a3d484f5'
{
"response": {
"status": "OK",
"report": {
"name": null,
"created_on": "2014-11-19 22:33:31",
"json_request": "{\"report\":{\"format\":\"csv\",\"report_interval\":\"yesterday\",\"row_per\":[\"geo_country\"],\"columns\":[\"placement_id\",\"imp_type_id\",\"creative_id\",\"brand_id\",\"geo_country\"],\"report_type\":\"seller_brand_review\",\"filters\":[{\"seller_member_id\":\"958\"}]}}",
"url": "report-download?id=c445bca183a3d338dc1c5b85a3d484f5"
},
"execution_status": "ready"
}
}
GET the report data from the report download service
To download the report data to a file, make another GET call with the report ID, but this time to the report-download service. You can find the service and report ID in the url field of the response to your previous GET call. When identifying the file that you want to save to, be sure to use the file extension of the file format that you specified in your initial POST.
Tip
If an error occurs during download, the response header will include an HTTP error code and message. Use -i or -v in your call to expose the response header.
$ curl -b cookies -c cookies 'https://api.appnexus.com/report-download?id=c445bca183a3d338dc1c5b85a3d484f5' > /tmp/seller_brand_review.csv
Note
There is a limit of 100,000 rows per report when you download them as XLSX and Excel file.