Digital Platform API - Key Value Analytics report

The Key Value Analytics report shows you the information associated with your network's defined targeting keys and values.

Impressions with key/value targeting will serve and be reported only for those impressions that were logged by a placement tag containing the kw_ prefix on the key name. For example, a placement tag containing keyname=value1 will not serve and therefore not be logged, whereas a placement tag containing kw_keyname=value1 will serve and be logged. This applies to GET-based query-string ad calls with the following tag types: /tt, /ttj, /fpt, /jpt, /pt, /ptv, /ssptv, /mtj, /map, /mob, /prebid/amp, /vmap, /ssvmap.

Not all impressions from key/value targets will be included in reports. To be included, the targets must meet the following criteria:

• Key must be pre-defined. For more information, see the Pre-Defining Targeting Keys and Values page in the UI.
• Value must be pre-defined OR Value must be targeted by at least one line item or campaign.
• Value is not a numeric range (greater than or less than).
• Value does not include a wildcard.

Time frame

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

• today
• yesterday
• last_24_hours
• last_48_hours
• last_7_days
• last_month
• month_to_date
• quarter_to_date

Dates occurring greater than 45 days ago

If you create a Key Value Analytics report with the Range field set to Custom (where the end date is greater than 45 days from today), your report (regardless of metrics included) will be added to a special queue for "resource-intensive" reports. As a result, the report may take longer than usual to complete. In addition, this resource-intensive report may, due to the amount of data being requested, fail before being completed. If your report fails to complete, you will receive a notification. If your report request fails, you can:

• Rerun the report at a later time.
• Use a report type other than Key Value Analytics.
• Alter the way you structure your reports (if possible) so they do not include dates greater than 45 days ago.

If you are frequently requesting Key Value Analytics reports which include dates longer than 45 day ago, you may need to consider running these reports via the API, caching the data and using Bulk Reporting Feeds or a Log Level Data Feeds - Archive. For more details on how to alter your reports to avoid these issues, see the Dimensions, Metrics, Filtering, and Grouping page in the UI.

Data retention period

Data in this report is retained for 428 days.

Dimensions

Metrics

Examples

Create the JSON report request

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

{"report":
    {
        "report_type":"key_value_analytics",
        "columns":[
            "hour",
            "seller_member_id",
            "key_name",
            "key_name_label",
            "key_value",
            "key_value_label",
            "imps",
            "clicks",
            "revenue",
            "ctr"
        ],
        "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 @key_value_analytics "https://api.appnexus.com/report?advertiser_id=123"

{
   "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\":\"key_value_analytics\",
             \"columns\":[\"hour\",\"seller_member_id\",
             \"key_name\",\"key_name_label\",\"key_value\",\"key_value_label\",
             \"imps\",\"clicks\",\"revenue\",\"ctr\"],
             \"report_interval\":\"last_48_hours\",\"format\":\"csv\",\"filters\":[{\"advertiser_id\":\"123\"}]}}",
             "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/key_value_analytics.csv