Digital Platform API - Vendor Usage report

Article
02/13/2024

This network report provides the details on your usage of data or platform powered by third-party vendors (e.g., user segment providers), the costs of that data or feature usage, and the line items/campaigns where vendor costs were applicable.

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

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

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.

Data retention period

Data retention period for this report is 60 days.

Dimensions

Column	Type	Filter?	Example	Description
`month`	date	yes	`"2010-02"`	The month at which the auction associated with the impression occurred.
`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.
`buyer_member_id`	int	yes	`643`	The ID of the member that used the data provided by the third-party vendor (e.g., user segment providers).
`geo_country`	string	yes	`"US"`	The code of the geographical country associated with the impression.
`geo_country_name`	string	no	`"United States"`	The name of the geographical country associated with the impression.
`geo_country_code`	string	yes	`"CA"`	A two-character string denoting the country associated with the impression.
`campaign_id`	int	yes	`31`	The ID of the campaign associated with the impression that used third-party data targeting.
`campaign_name`	string	no	`"Prospect Campaign"`	The name of the campaign associated with the impression that used third-party data targeting.
`campaign`	string	no	`"Prospect Campaign (31)"`	The name and ID of the campaign associated with the impression.
`campaign_group_type_id`	int	yes	`154`	The ID of the campaign group type which purchased this impression. Used in split reporting.
`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	no	`"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`.
`split`	string	no	`"Mobile Split A (342)"`	The name and ID of the split.
`line_item_name`	string	no	`"Fall Apparel"`	The name of the line item associated with the impression that used third-party data targeting.
`targeted_segment_ids`	string	no	`"935035, 935146"`	The comma-separated list of IDs for each of the segments used when targeting.
`advertiser_currency`	string	yes	`"USD"`	The advertiser's preferred currency. This preference can be set using the Advertiser Service.
`insertion_order_id`	int	yes	`1243`	The ID of the insertion order associated with the impression that used third-party data targeting.
`insertion_order_name`	string	no	`"IO001"`	The name of the insertion order associated with the impression that used third-party data targeting.
`insertion_order_code`	string	no	`"IOABC-1243"`	The user-defined code associated with the insertion-order.
`insertion_order`	string	no	`"IO001 (1243)"`	The name and ID of the insertion order associated with the impression that used third-party data targeting.
`advertiser_id`	int	yes	`9843`	The advertiser ID associated with the impression. If the value is `0`, either the impression was purchased by an external buyer, or a default or PSA was shown.
`advertiser_name`	string	no	`"ADVUS"`	The name of the advertiser associated with the impression.
`advertiser`	string	no	`"ADVUS (9843)"`	The name and ID of the advertiser associated with the impression.
`line_item_id`	int	yes	`9865`	The ID of the line item associated with the impression that used third-party data targeting.
`line_item_code`	string	no	`"LI001"`	The user-defined code associated with the line item.
`line_item`	string	no	`"Fall Apparel (9865)"`	The name and ID of the line item associated with the impression that used third-party data targeting.
`vendor_id`	int	yes	`76`	The ID of the third party vendor (e.g., user segment providers) whose data usage and cost comes in this report.
`vendor_name`	string	no	`"AXM"`	The name of the third party vendor.
`vendor`	string	no	`"AXM (76)"`	The name and ID of the third party vendor.
`vendor_type`	string	no	`"Segment Marketplace"`	The type of the vendor depending on the third party data it provides. Allowed values are: - `Segment Marketplace` - `Cross Device Graph` - `Measurement` - `Offline Attribution` - `Unknown Vendor Type`
`cost_type`	string	no	`"Segment Data Costs"`	The type of cost incurred towards the data usage provided by the third party vendors. Allowed values are: - `Segment Data Costs` - `Feature Costs` - `Unknown Vendor Type`
`buying_currency`	string	yes	`"USD"`	The transaction currency that the buyer used to purchase this impression.
`cpm_usd`	money	yes	`7.8`	Cost per mille, or thousand (mille = thousand in Latin) expressed in USD. A pricing model in which advertisers pay for every 1000 impressions of their advertisement served.

Metrics

Column	Type	Filter	Example	Formula	Description
`imps`	int	yes	`34534`	imps	The total number of impressions that used third-party data to serve the ad.
`third_party_costs`	money	yes	`5.20`	third_party_costs	Total monetary value of data segment costs, feature costs or others.
`sales_tax`	money	no	`.43`	sales_tax	The amount of sales tax collected in USD. 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.
`vendor_costs`	money	no	`5.00`	vendor_costs	The total costs, including but not limited to segment data costs, and feature costs. Feature Costs: Costs incurred when using a platform feature such as Nielsen Digital Ad Ratings (DAR), Nielsen Catalina Solutions (NCS) and Cross Device. Segment Data Costs: All costs related to using segments in the data marketplace. Applicable when specific segments are applied in line items and associated pricing is displayed in the platform.
`vendor_costs_buying_currency`	money	no	`1.50`	vendor_costs_buying_currency	The vendor costs expressed in the transaction currency used by the buyer.

Examples

Create JSON formatted report request

The JSON file should include the report_type of "buyer_vendor_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_vendor_usage_analytics  
{
    "report": {
        "report_type": "buyer_vendor_usage_analytics",
        "format": "csv",
        "report_interval": "last_7_days",
        "columns": [
            "imps",
            "line_item_id",
            "vendor_costs",
            "sales_tax",
            "vendor_type",
            "vendor"
        ],
        "orders": [
            "line_item_id",
            "vendor_costs",
            "vendor_type"
        ]
    }
}

`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_vendor_usage_analytics "https://api.appnexus.com/report"
{
    "response": {
        "report_id": "d89151942729f768dcac4586288ff7eb",
        "status": "OK",
        "dbg_info": {
            "user::read_limit": 100,
            "user::write_limit": 60,
            "read_limit": 100,
            "write_limit": 60,
            "user::read_limit_seconds": 60,
            "user::write_limit_seconds": 60,
            "read_limit_seconds": 60,
            "write_limit_seconds": 60,
            "instance": "50.bm-report-processor.prod.nym2",
            "version": "1.73.238",
            "time": 712.83793449402,
            "start_microtime": 1686106227,
            "warnings": [],
            "api_cache_hit": "0",
            "output_term": null,
            "edge_forwarded_dbg_info": {
                "user::read_limit": 100,
                "user::write_limit": 60,
                "read_limit": 100,
                "write_limit": 60,
                "user::read_limit_seconds": 60,
                "user::write_limit_seconds": 60,
                "read_limit_seconds": 60,
                "write_limit_seconds": 60,
                "instance": "37.report-processor.prod.nym2",
                "version": "1.73.238",
                "time": 708.98699760437,
                "start_microtime": 1686106227,
                "warnings": [],
                "api_cache_hit": "0",
                "output_term": "report_id"
            },
            "edge_forwarded": true,
            "edge_forwarded_by": "50.bm-report-processor.prod.nym2",
            "edge_forwarded_to": "http://report-processor-edge.adnxs.net/report"
        }
    }
}

`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=d89151942729f768dcac4586288ff7eb'
{
    "response": {
        "status": "OK",
        "report": {
            "id": "d89151942729f768dcac4586288ff7eb",
            "name": "",
            "created_on": "2023-06-07 02:50:27",
            "cache_hit": false,
            "fact_cache_hit": false,
            "fact_cache_error": "",
            "json_request": "{\"report\":{\"report_type\":\"buyer_vendor_usage_analytics\",\"format\":\"csv\",\"report_interval\":\"last_7_days\",\"columns\":[\"imps\",\"line_item_id\",\"vendor_costs\",\"sales_tax\",\"vendor_type\",\"vendor\"],\"orders\":[{\"order_by\":\"line_item_id\",\"direction\":\"ASC\"},{\"order_by\":\"vendor_costs\",\"direction\":\"ASC\"},{\"order_by\":\"vendor_type\",\"direction\":\"ASC\"}],\"grouping\":{\"additional_grouping_sets\":[],\"unselected_implicit_groupings\":[],\"additional_groups_on_bottom\":true},\"timezone\":\"UTC\",\"filters\":[{\"buyer_member_id\":\"958\"}],\"reporting_decimal_type\":\"decimal\",\"use_cache\":true},\"extraction_version\":\"refactored\",\"end_date\":1686096000,\"start_date\":1685491200,\"user_id\":\"4814\"}",
            "header_info": "Report type: buyer_vendor_usage_analyticss\nReport ID: d89151942729f768dcac4586288ff7eb\nRun at: 2023-06-07 04:08:58 UTC\nRequested Start date: 2023-05-31 00:00:00 UTC\nRequested End date: 2023-06-07 00:00:00 UTC\nTimezone: UTC\n",
            "user_id": "4814",
            "member_id": "958",
            "bidder_id": "2",
            "entity_id": "958",
            "row_count": 0,
            "report_size": 61,
            "url": "report-download?id=d89151942729f768dcac4586288ff7eb"
        },
        "execution_status": "ready",
        "_was_this_status_cached_": 0,
        "dbg_info": {
            "user::read_limit": 100,
            "user::write_limit": 60,
            "read_limit": 100,
            "write_limit": 60,
            "user::read_limit_seconds": 60,
            "user::write_limit_seconds": 60,
            "read_limit_seconds": 60,
            "write_limit_seconds": 60,
            "instance": "50.bm-report-processor.prod.nym2",
            "version": "1.73.238",
            "time": 454.48088645935,
            "start_microtime": 1686110938,
            "warnings": [],
            "api_cache_hit": "0",
            "output_term": null,
            "edge_forwarded_dbg_info": {
                "user::read_limit": 100,
                "user::write_limit": 60,
                "read_limit": 100,
                "write_limit": 60,
                "user::read_limit_seconds": 60,
                "user::write_limit_seconds": 60,
                "read_limit_seconds": 60,
                "write_limit_seconds": 60,
                "instance": "37.report-processor.prod.nym2",
                "version": "1.73.238",
                "time": 448.82392883301,
                "start_microtime": 1686110938,
                "warnings": [],
                "api_cache_hit": "0",
                "output_term": "report"
            },
            "edge_forwarded": true,
            "edge_forwarded_by": "50.bm-report-processor.prod.nym2",
            "edge_forwarded_to": "http://report-processor-edge.adnxs.net/report"
        }
    }
}

`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, be sure to use the file extension of the file "format" that you specified in your initial POST call, for example, CSV.

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

Tip

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.

Note

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

Share via

Digital Platform API - Vendor Usage report

Time frame

Data retention period

Dimensions

Metrics

Examples

Create JSON formatted report request

`POST` the request to the Report service

`GET` the report status from the Report service

`GET` the report data from the Report Download service

Additional resources

Share via

Digital Platform API - Vendor Usage report

Time frame

Data retention period

Dimensions

Metrics

Examples

Create JSON formatted report request

POST the request to the Report service

GET the report status from the Report service

GET the report data from the Report Download service

Additional resources

`POST` the request to the Report service

`GET` the report status from the Report service

`GET` the report data from the Report Download service