Digital Platform API - Buyer Segment Performance report

  • Articolo

This report provides buyers with segment performance across campaigns and multiple advertisers.

The time_granularity of the data is hourly. For instructions on retrieving a report, see the Report Service or the examples.

Note

Impressions across user segments: Since this report aggregates impressions served by user segment, impressions associated with users who are present in multiple segments will be counted more than once. As a result, be sure to group by segment_id when running the report.

Time frame

The report_interval field in the JSON request must be set to one of the following:

  • today
  • yesterday
  • last_7_days
  • last_14_days
  • last_30_days

Data retention period

Data retention period for this report is 45 days.

Note

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.

Dimensions

Column Type Filter? Examples Description
month time no "2010-02" The month of the auction.
day date yes "2010-02-01" The day of the auction.
hour time no "2010-02-01 06:00:00" The hour of the auction.
insertion_order_id int yes 321 The ID of the insertion order. If the value is 0, the impression was purchased by a third-party buyer.
campaign_id int yes 222 The ID of the campaign that purchased the impression.
campaign_name string no "Fall Wares" The name of the campaign that purchased the impression.
campaign string no "Fall Wares (222)" Deprecated.
advertiser_id int yes 789 The ID of the advertiser. If the value is 0, either the impression was purchased by third-party buyer, or a default or PSA was shown.
line_item_id int yes 111 The ID of the line item. If the value is 0, the impression was purchased by a third-party buyer.
advertiser_name string no "Amco" The name of the advertiser.
advertiser string no "Amco (789)" Deprecated.
line_item_name string no "Kitchen" The name of the line item.
line_item string no "Kitchen (111)" Deprecated.
split_id int yes 342 The ID of the split that purchased the impressions in this data set. Splits are only applicable to augmented line items. For any reports that contain campaigns, the split_id (if included) will be null.
split_name string yes "Mobile Split A" The name of the split that purchased the impressions in this data set. Splits are only applicable to augmented line items. For any reports that contain campaigns, the split_name (if included) will be null.
campaign_code string no "Mobile Campaign Code" The custom code for the campaign.
segment_id int yes 220 The ID of the segment pixel.
segment_name string no "Submitted application" The name of the segment.
segment string no "Submitted application (220)" Deprecated.
insertion_order_name string no "Mobile Insertion Order" The name of the insertion order.
insertion_order string no "Mobile Insertion Order (321)" Deprecated.
segment_code string no "Mobile Insertion Order Code" The (optional) custom code associated with the user segment present for this impression.
pixel_id int yes 1942 The unique identification number of the conversion pixel.

Note: This dimension will return a maximum of 10 conversion pixels. Also, you can filter by no more than 10 conversion pixels. Although pixel_id is groupable, we do not recommend that you group by this dimension since doing so will cause conversion events to then be shown in separate rows from impression and click events. We generally assume you want to view all of these events in a single row so as to be able to retrieve accurate and aggregated values for conversion rate and cost-per-conversion calculations. As a result, we instead recommend that you filter by pixel_id so you can retrieve conversion counts and related metrics for your most relevant pixel IDs.
gender string yes "m", "f", "u" The gender of the user.

Note: For impressions older than 100 days, the gender will be "u".
age_bucket string yes "18-24, "45-54" The age bucket in which the user is contained. For more information, see Age Bucket below.
age_bucket_id int yes 1, 3, 0 The ID of the age bucket. For more information, see Age Bucket below.

Age bucket

Bucket ID Bucket Name
0 "unknown"
1 "13-17"
2 "18-24"
3 "25-34"
4 "35-44"
5 "45-54"
6 "55-64"
7 "65+"

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.
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.
booked_revenue money 450.00 post_view_revenue + post_click_revenue The total revenue booked through direct advertisers.
booked_revenue_buying_currency money 145.00 (post_view_revenue + post_click_revenue) in buying currency The total revenue booked through direct advertisers expressed in buying currency.
post_view_convs int 15 post_view_convs The number of post-view conversions.
post_view_revenue money 150.00 post_view_revenue Advertiser revenue from post-view conversions.
post_click_convs int 10 post_click_convs The number of post-click conversions that occurred.
post_click_revenue money 300.00 post_click_revenue Advertiser revenue from post-click conversions.
post_view_convs_rate double 0.00013 post_view_convs / imps The rate of post-view conversions to impressions.
post_click_convs_rate double 0.0002 post_click_convs / imps The rate of post-click conversions to impressions.
spend money 304.36 spend The total marketer spend across both direct and real time media buys for this segment.
media_cost money 100.00 media_cost The total cost of the inventory purchased.
cpm money 5.00 media_cost / imps * 1000 The cost per thousand impressions.
revenue_ecpm money 1.9221 (booked_revenue / impressions) x 1000 The total revenue per 1000 impressions.
profit money 4.14 booked_revenue - total_cost Booked revenue minus total cost.
profit_ecpm money 0.4949 (booked_revenue - total_cost)/imps * 1,000 The profit (defined as booked revenue minus total cost) per 1,000 impressions.
revenue_ecpc money 0.8256 booked_revenue / clicks The total revenue per click.
revenue_ecpa money 5.00 booked_revenue / total_convs The total revenue per conversion.
cost_ecpc money 0.1834 media_cost / clicks The cost per click.
cost_ecpa money 1.1111 media_cost / total_convs The cost per acquisition/conversion.
commissions money 0 Commissions for standard line items, $0 for ALIs. Fees that come out of the booked revenue.
serving_fees money 0.025143 Serving fees for standard line items, $0 for ALIs. Fees that are added to the media cost.
convs_per_mm double 384.4 (total_convs / imps) * 1,000,000 The number of conversions per million impressions.
partner_fees money 123.45 partner_fees The total amount of third-party costs, budgeted using the Partner Fee Service, that have accrued on an augmented line item over the reported period of time.
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 (August 6-After 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.
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.
video_skips int 10 video_skips The total number of times a user skipped the video. Use this metric for reporting when buying skippable inventory.
video_starts int 11 video_starts The total number of times the first segment of the video creative was downloaded and started.
video_25_pcts int 10 video_25_pcts The total number of times the video creatives completed 25% of the entire duration.
video_50_pcts int 10 video_50_pcts The total number of times the video creatives completed 50% of the entire duration.
video_75_pcts int 10 video_75_pcts The total number of times the video creatives completed 75% of the entire duration.
video_completions int 12 video_completions The total number of times the video creatives played for the entire duration.
video_served int 10 video_served The total number of video responses served to the player.An ad response occurs when the VAST document (XML) is served in response to a request. An ad response doesn't necessarily indicate a successful impression. For an impression, the first frame of the video must be served.
video_errors int 2 video_errors The total number of times a video error occurred.
revenue_per_video_complete money 25.76 revenue_per_video_complete The revenue per video completion.
cost_per_video_complete money 22.76 cost_per_video_complete The cost per video completion.
video_completion_rate double 1.12359550561797% (video completions/total impressions) x 100 The ratio of video completions to impressions, expressed as a percentage.
video_start_rate double 1.12359550561797% video_start_rate The percentage of times the first segment of the video creative was downloaded and started.
video_skip_rate double 1.12359550561797% video_skip_rate The percentage of times the user opted to skip the video.

Examples

Create the JSON report request

The JSON file should include the report_type of "buyer_segment_performance", 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 buyer_segment_performance

{"report": 
    {
        "format": "csv",
        "report_interval": "yesterday",
        "row_per": ["campaign_id"],
        "columns": ["campaign_id", "segment_id", "advertiser_id", "advertiser_name","line_item_id"],
        "report_type": "buyer_segment_performance"
    }
}

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 @buyer_segment_performance "https://api.appnexus.com/report"

{
   "response":{
      "status":"OK",
      "report_id":"71816ec6d09b32a5140730afe5cf6af5"
   }
}

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=71816ec6d09b32a5140730afe5cf6af5'

{
    "response": {
        "status": "OK",
        "report": {
            "name": null,
            "created_on": "2014-11-19 21:15:10",
            "json_request": "{\"report\":{\"format\":\"csv\",\"report_interval\":\"yesterday\",\"row_per\":[\"campaign_id\"],\"columns\":[\"campaign_id\",\"segment_id\",\"advertiser_id\",\"advertiser_name\",\"line_item_id\"],\"report_type\":\"buyer_segment_performance\",\"filters\":[{\"member_id\":\"1234\"}]}}",
            "url": "report-download?id=71816ec6d09b32a5140730afe5cf6af5"
        },
        "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.

Note

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=71816ec6d09b32a5140730afe5cf6af5' > /tmp/buyer_segment_performance.csv

Note

There is a limit of 100,000 rows per report when you download them as XLSX and Excel file.

Report Service