Digital Platform API - Offline Attribution report

Artigo
03/05/2024

The Offline Attribution report is used to analyze your line item's performance in influencing in-store purchases among your target audiences. The Offline Attribution report is only accessible to clients who have Offline Sales Attribution enabled for their line items.

For instructions on retrieving a report, please see Report Service or the example below. This report requires specifying the advertiser ID as part of the URL, for example:

 https://api.appnexus.com/report?advertiser_id=ADVERTISER_ID

Time frame

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

custom
last_7_available_days
last_14_available_days
last_30_available_days
last_365_days

Data retention period

This report has a daily time granularity and can retrieve data from the past 120 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.
You can't make a specific time zone selection because NCS data uses the time zone(s) from where sales take place.

Dimensions

Column	Type	Filter?	Example	Description
`day`	date		`"2021-10-10"`	The day on which NCS generated the report. The date displayed for this dimension will match the date displayed for the `analysis_start_date`.
`insertion_order_id`	string	Yes	`"5533431"`	The ID of the insertion order.
`insertion_order_name`	string	Yes	`"My IO"`	The name of the insertion order.
`line_item_id`	string	Yes	`"14545960"`	The ID of the line item.
`line_item_name`	string	Yes	`"NCS Line Item"`	The name of the line item.
`flight_id`	string		`"12396335"`	The ID of the flight.
`flight.start_date`	date		`"2021-04-16 00:00:00 UTC"`	The start date of the flight.
`flight.end_date`	date		`"2021-04-30 23:59:59 UTC"`	The end date of the flight.
`split_id`	string	Yes	`"1234"`	The ID of a split.
`split_name`	string	Yes	`"my split"`	The name of a split.
`analysis_end_date`	date		`"2021-10-10"`	The last day of the purchase interval being reported for each cohort.
`analysis_rejection_reason`	string		`"DMA minimum not met, Retailer minimum not met"`	The error that identifies which of the requirements for measurement weren't met.
`analysis_start_date`	date		`"2021-10-03"`	The first day of the purchase interval being reported for each cohort.
`frequency_type`	string		`"weekly"`	The reporting frequency selected for this line item or split.
`lookback_hours`	string		`"flight_lifetime"`	The lookback window selected for this line item or split.
`product_id`	string		`"10096"`	The product selection ID used to describe the product or products being reported.
`product`	string		`"BAKING SUPPLIES \\| MARS INCORPORATED \\| M&M MARS"`	The product selection name used to describe the product or products being reported.

Metrics

Column	Type	Description
`imps`	int	The total number of impressions served.
`clicks`	int	The total number of clicks recorded.
`booked_revenue`	int	The revenue received from the advertiser.
`media_cost`	int	The cost to the buying member for this inventory.
`total_cost`	int	The total amount of costs accrued over the reported period of time. This generally includes two types of costs: budgeted costs (media cost, data cost, partner fees, serving fees, commissions) and publisher revenue if you track publisher payouts on the platform.
`imps_viewed`	int	Impressions that are considered viewable as defined by the Interactive Advertising Bureau (IAB): For at least one second, 50% of a creative's pixels (or 30% for a creative with at least 242,500 pixels) must render on a screen.
`all_outlet_adjusted_number_of_trips`	int	The number of trips to the store by households that have been during the analysis's start and end dates. NCS only has data for some stores (outlets) within the US, so it adjusts sales metrics to account for sales that occurred across all outlets in the US.
`all_outlet_adjusted_penetration%`	int	The penetration percentage for the product, category, or brand during the analysis's start and end dates. NCS only has data for some stores (outlets) within the US, so it adjusts sales metrics to account for sales that occurred across all outlets in the US. Note: Penetration measures brand or category popularity. It is calculated by dividing the number of people who've purchased a specific brand or category of goods at least once in a given time period by the size of the relevant market's total population.
`all_outlet_adjusted_total_spend`	int	The number of dollars spent by households on the product, category, or brand during the analysis's start and end dates. NCS only has data for some stores (outlets) within the US, so it adjusts sales metrics to account for sales that occurred across all outlets in the US.
`video_completions`	int	For a video creative, the number of times the video creative was viewed to completion.

Example

Create a JSON formatted report request

The JSON file should include the report_type of "offline_attribution", as well as the columns (dimensions and metrics) and the 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 report-request.json

{
    "report": {
        "report_type": "offline_attribution",
        "format": "csv",
        "report_interval": "last_365_days",
        "columns": [
            "month",
            "member_id",
            "line_item_id",
            "split_id",
            "all_outlet_adjusted_total_spend",
            "imps",
            "analysis_rejection_reason"
        ],
        "orders": [
            "member_id",
            "line_item_id",
            "split_id"
        ],
        "filters": [{
            "line_item_id": [14545960, 14545978]
        }]
    }
}

`POST` the request to the reporting service

In this example, we request execution of the report for advertiser 660.

$ curl -b cookies -c cookies -X POST -d @offline_attribution 'https://api.appnexus.com/report?advertiser_id=660'

{
    "response":{
        "status":"OK",
        "report_id":"07af1282c9485adcef49c95fa5d7496b"
    }
}

Use the report ID to retrieve the report data

The standard response includes the report data and a Download URL that you can use to save the data to a file. If you want to get just the Download URL without the report data, pass "without_data" in the query string.

$ curl -b cookies -c cookies 'https://api.appnexus.com/report?id=07af1282c9485adcef49c95fa5d7496b'

{
    "response": {
        "status": "OK",
        "report": {
            "name": null,
            "created_on": "2011-11-16 23:51:14",
            "cache_hit": false,
            "fact_cache_hit": false,
            "json_request": "{\"report\":{\"report_type\":\"offline_attribution\",\"format\":\"csv\",\"report_interval\":\"last_365_days\",\"columns\":[\"month\",\"member_id\",\"line_item_id\",\"split_id\",\"all_outlet_adjusted_total_spend\",\"imps\",\"analysis_rejection_reason\"],\"orders\":[{\"order_by\":\"member_id\",\"direction\":\"ASC\"},{\"order_by\":\"line_item_id\",\"direction\":\"ASC\"},{\"order_by\":\"split_id\",\"direction\":\"ASC\"}],\"filters\":[{\"line_item_id\":[14545960,14545978]},{\"member_id\":\"958\"}],\"grouping\":{\"additional_grouping_sets\":[],\"unselected_implicit_groupings\":[],\"additional_groups_on_bottom\":true},\"timezone\":\"UTC\",\"reporting_decimal_type\":\"decimal\",\"use_cache\":true},\"extraction_version\":\"refactored\",\"end_date\":1622678400,\"start_date\":1591142400,\"user_id\":\"46052\"}",
            "header_info": "Report type: offline_attributions\nReport ID: 5dd162b83a0417e13859e5e243844329\n",
            "data": "day,campaign,booked_revenue,imps,clicks,click_thru_pct,site_domain\u000d\u000a2011-11-12,ExampleCampaign - 1
             (123456),.000000,24,0,.000000000000000000%,aaaa.com\u000d\u000a2011-11-13,ExampleCampaign - 2 (789012),.000000,9,0,
             .000000000000000000%,bbbb.net\u000d\u000a2011-11-12,ExampleCampaign - 3 (345678),.000000,2,0,.000000000000000000%,
             ccc.com\u000d\u000a2011-11-13,ExampleCampaign - 3 (345678),.000000,2,0,.000000000000000000%,cccc.de\u000du000a
             2011-11-14,ExampleCampaign - 3 (345678),.000000,10,0,.000000000000000000%,dddd.com\u000d\u000a2011-11-13,
             ExampleCampaign - 4 (901234), 2.574900,22,3,13.636363636363636364%,aaaa.com\u000d\u000a2011-11-15,ExampleCampaign - 3
             (345678),8.583000,2431,10,.411353352529823118%,abab.com\
             ...
            "url": "report-download?id=495d03a7667bac467bb488043ae336e9"
        },
        "execution_status": "ready"
    }
}

Use the download URL to save the report data to a file

You use the "url" field in the response to save the report data to a file. Simply make another GET call and identify the location and file that you want to save to. Be sure to use the file the extension of the "format" that you specified in your initial POST request.

$ curl -b cookies -c cookies 'https://api.appnexus.com/report-download?id=495d03a7667bac467bb488043ae336e9' > /tmp/site_domain.csv

Partilhar via

Digital Platform API - Offline Attribution report

Time frame

Data retention period

Dimensions

Metrics

Example

Create a JSON formatted report request

`POST` the request to the reporting service

Use the report ID to retrieve the report data

Use the download URL to save the report data to a file

Recursos adicionais

Partilhar via

Digital Platform API - Offline Attribution report

Time frame

Data retention period

Dimensions

Metrics

Example

Create a JSON formatted report request

POST the request to the reporting service

Use the report ID to retrieve the report data

Use the download URL to save the report data to a file

Recursos adicionais

`POST` the request to the reporting service