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.

Dimensions

Metrics

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.

curl -b cookies 'https://api.appnexus.com/report-download?id=b97897a7864dd8f34e7457226c7af592' > /tmp/buyer_approximate_unique_users_hourly.csv