Partilhar via


Digital Platform API - Buyer Reach and Frequency report

The Buyer Reach and Frequency report shows you the information associated with two parameters: "reach" and "frequency". "reach" is the number of unique devices or persons exposed to ads. "frequency" is the average number of times each unique device or person was exposed to advertisements. It helps to draw meaningful conclusions about the impact of cross device on conversion use cases. In short, buyers can have an insight on how cross device impacted the number of times a single person saw their ads across all their devices using this report as this report shows historical reach and average frequency on your buying.

The Buyer Reach and Frequency Report offers flexible filtering to analyze unique devices by facilitating below procedure:

  • Pull a basic running total of unique devices for their active Line Items or Insertion Orders.
  • Pull unique devices for these objects over a defined period of time (for example, past week).
  • You can filter and group on specific criteria, which will provide an accurate unique device count across the specified criteria. For example, the count of unique devices across Line Items A, B, and D, in the US and Canada, for the past month.

Time frame

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

  • custom
  • today
  • last_hour
  • last_24_hours
  • yesterday
  • last_48_hours
  • last_2_days
  • last_7_days
  • last_14_days
  • last_30_days
  • last_month
  • month_to_date
  • quarter_to_date
  • lifetime

Data retention period

Data in this report is retained for 90 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? Example Description
month date Yes "2010-02" The month of the auction.
day date Yes "2010-02-01" The day of the auction.
hour date Yes "2010-02-01 06:00:00" The hour of the auction.
buyer_member_id int Yes 123 The ID of the buying member.
geo_country string Yes "US" The targeted country of the advertisement.
media_type string No "Banner" The general display style of the creative.
media_type_id int Yes 1 The ID of the media type.
supply_type string Yes "Mobile App" The method of rendering the creative on a device.
billing_period_id int Yes 453 The ID of the insertion order's billing period.
billing_period.start_date string No "2010-02-01" The start date of the insertion order's billing period.
billing_period.end_date string No "2010-02-08" The end date of the insertion order's billing period.
split_id int Yes 111 The ID of the split that purchased the impressions in this data set.
split_name string No "FirstSplit" The name of the split that purchased the impressions in this data set.
flight int No 32 The ID of the flight in a billing period under an insertion order.
flight.start_dt string No "2010-02-01" The start date of the flight in a billing period under an insertion order.
flight.end_dt string No "2010-02-03" The end date of the flight in a billing period under an insertion order.
advertiser_id int Yes 789 The ID of the advertiser for which impression was purchased.
advertiser_name string No "AdvertiserA" The name of the advertiser for which impression was purchased.
line_item_id int Yes 1122 The ID of the line item under which the impression was purchased.
line_item_name string No "Line Item 1" The name of the line item under which the impression was purchased.
creative_id int Yes 444 The ID of the creative that we're reporting on the frequency and/or recency of.
creative_name string No "Q1 2017 728x90" The name of the creative that we're reporting on the frequency and/or recency of.
insertion_order_id int Yes 321 The ID of the insertion order under which the impression was purchased.
device_type string Yes "Desktops and Laptops" The type of the device where the impression has occurred.
frequency_cap_type string No "Classical", "Advanced", or "None" The type of frequency cap used to limit over-delivery to individual users. When an ID was available in the request, "Classical" is the default frequency cap type. "Advanced" refers to "Advanced Frequency Management" feature.

Metrics

Column Type Example Formula Description
imps int 234123 imps The total number of impressions.
identified_imps int 234123 identified_imps The total number of identified impressions (i.e. those impressions which included a cookie, device id, etc. as part of the ad request).
unidentified_imps int 234212 unidentified_imps The total number of unidentified impressions (i.e. those impressions which did not include a cookie, device id, etc. as part of the ad request).
approx_users_count int 5654 approx_users_count The approximate unique users count who viewed the impression.
average_impression_frequency double 8898 imps/approx_users_count The number of impressions viewed by per unique users.
approximate_consumer_count int 8888 approximate_consumer_count The approximate consumer count who viewed the impression due to cross-device audience extension.
average_consumer_impression_frequency double 7999 imps/approximate_consumer_count The number of impressions viewed by per unique consumers due to cross-device audience extension.
approximate_incremental_devices int 899 approximate_incremental_devices The total number of unique cookies, mobile or other devices reached by the impressions.
cross_device_incremental_imps int 6888 cross_device_incremental_imps The number of impressions which are transacted due to cross-device audience extension. This represents the number of impressions which were delivered on devices outside of the targeted segment(s), due to a cross device graph being applied to extend the reach to more devices owned by a consumer.
average_identified_impression_frequency double 1.23 identified_imps / approx_users_count The number of identified impressions viewed per unique users.
estimated_people_reach (currently available in the US only) int 269,266 unique devices / device density factor The estimated number of people reached, deduplicated across the user-specified dimensions.

Note

The metric estimated_people_reach is currently available in the US only. This model considers the unique devices reached at the zip code level, and utilizes publicly available US census data for the total population of each zip code, in order to estimate the number of people reached for that zip code. This zip code level data is then aggregated when a report is pulled by the API so that the buyer can view it at any level of granularity that is provided by the existing dimensions in the report.

Advanced Frequency Management (AFM), which is currently in beta, does not take universal identifier (Universal ID) into account. This is subject to change as the feature would move into GA. Line items utilising Universal ID targeting should avoid using AFM until this is completely adapted.

Examples

Create the JSON report request

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

{"report":
    {
        "report_type":"buyer_approximate_unique_users_hourly",
        "columns":[
            "hour",
            "buyer_member_id",
            "media_type",
            "supply_type",
            "creative",
            "line_item_id",
            "imps",
            "average_impression_frequency",
            "cross_device_incremental_imps"
        ],
        "report_interval":"last_48_hours",
        "format":"csv"
    }
}

POST the request to the Report Service

POST the JSON request to get back a report ID.

$ curl -b cookies -X post -d @buyer_approximate_unique_users_hourly "https://api.appnexus.com/report?advertiser_id=789"

{
   "response":{
      "status":"OK",
      "report_id":"09b6979a6a4c3805bdac8921378d3622"
   }
}

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 'https://api.appnexus.com/report?id=09b6979a6a4c3805bdac8921378d3622'

{
   "response":{
      "status":"OK",
      "report":{
         "name":null,
         "created_on":"2016-12-11 19:15:48",
         "json_request": "{\"report\":{\"report_type\":\"buyer_approximate_unique_users_hourly\",
             \"columns\":[\"hour\",\"buyer_member_id\",
             \"media_type\",\"supply_type\",\"creative\",\"line_item_id\",
             \"imps\",\"average_impression_frequency\",\"cross_device_incremental_imps\"],
             \"report_interval\":\"last_48_hours\",\"format\":\"csv\",\"filters\":[{\"advertiser_id\":\"789\"}]}}",
             "url":"report-download?id=b97897a7864dd8f34e7457226c7af592"
      },
      "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 'https://api.appnexus.com/report-download?id=b97897a7864dd8f34e7457226c7af592' > /tmp/buyer_approximate_unique_users_hourly.csv

Note

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