Digital Platform API - Data Usage report

This report provides gives details related to your usage of data provided by third parties (e.g., user segment providers), the costs of that data usage and line items/campaigns in which that data was used to target users.

This report's data is retained for 60 days. The time_granularity of the data is hourly. 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:

• today
• yesterday
• last_7_days
• last_30_days
• month_to_date
• quarter_to_date
• last_month
• lifetime

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
geo_country_code	string	yes	"CA"	A two-character string denoting the country associated with the impression.
campaign	string	no	"Prospect Campaign (31)"	Deprecated (as of October 17, 2016).
data_provider	string	no	"Peer 39 (Data Provider) (517)"	Deprecated (as of October 17, 2016).
geo_country	string	yes	"US"	The code of the geographical country associated with the impression.
targeted_segment_ids	string	no	"935035, 935146"	The comma-separated list of IDs for each of the segments used when targeting.
day	date	yes	"2010-02-01"	The day at which the auction associated with the impression occurred
hour	date	yes	"2010-02-01 05:00:00"	The hour at which the auction associated with the impression occurred.
campaign_id	int	yes	31	The ID of the campaign associated with the impression that used third-party data targeting.
buyer_member_id	int	yes	643	The ID of the member that used the third-party data.
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.
data_provider_id	int	yes	517	The ID of the third-party that provided the targeting data.
month	date	yes	"2010-02"	The month at which the auction associated with the impression occurred
data_provider_name	string	no	"Peer 39 (Data Provider)"	The name and ID of the third-party that provided the targeting data.
campaign_name	string	no	"Prospect Campaign"	The name of the campaign associated with the impression that used third-party data targeting.
geo_country_name	string	no	"United States"	The name of the geographical country associated with the impression.
line_item_name	string	no	"Fall Apparel"	The name of the line item associated with the impression that used third-party data targeting.
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.

Metrics

Column	Type	Example	Formula	Description
imps	int	34534	imps	The total number of impressions that used third-party data to serve the ad.
data_costs	money	3.50		The monetary value of the data segments that were purchased from third-party data providers.
sales_tax	money	.43		The amount of sales tax collected. This field is only populated when the Buyer's billing address is located in one of the following U.S. states: NY, TX or NJ. Xandr is required (by the relevant local state regulator) to collect this tax.
data_type	string	Segment		The available choices are Segment and Cross Device
Metrics available in local currency
data_costs_buying_currency	money	3.50		The monetary value of the data segments that were purchased from third-party data providers. Represented in the Advertiser's currency

Example

Create a JSON report request

The JSON file should include the report_type of "buyer_data_usage_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 (month, day, hour), 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_data_usage_analytics

{"report":
    {
        "format": "csv",
        "report_interval": "yesterday",
        "row_per": ["geo_country"],
        "columns": ["imps","campaign_id","geo_country"],
        "report_type": "buyer_data_usage_analytics"
    }
}

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\":[\"imps\",\"campaign_id\",\"geo_country\"],\"report_type\":\"buyer_data_usage_analytics\",\"filters\":[{\"buyer_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.

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=c445bca183a3d338dc1c5b85a3d484f5' > /tmp/buyer_data_usage_analytics.csv

Note

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