Media Delivery

Use Cases for the Media Delivery Schema

The Media Delivery API uploads information about transacted impressions into the Scope3 system for modeling and inclusion in reports, dashboards, and other analytic tools.

The Media Delivery guide can also be used effectively for Creative Measurement.

Advertiser Reporting

Advertisers that have delivery logs from their DSP (for instance, REDS from TTD), ad server (for instance, GCM logs), or other source of exposure data can use the Media Delivery API to add these campaigns to their Scope3 dashboard, the emissions simulator, and other Scope3 tools.

Client Campaign Reporting

Publishers, media owners, and platforms can use the Media Delivery API to upload delivery logs from their ad server to create dashboards and reports for their internal teams and (if desired) their clients.

Getting Started

To use the Media Delivery schema, you will need to gather delivery data, configure field mappings, and send the data to Scope3. This process can be managed using the Integrate tool in the CSP.

Once data has been uploaded and approved, it will be processed through the measurement API. The results will be available for reporting in the CSP and can also (through a configuration in the Integrate tool) be pushed back into a cloud bucket for use in your proprietary systems.

Overview of the Input Format

Below are the key fields for the Media Delivery schema. Many fields can be added to refine the measurement—see the full input schema documentation and the Data Dictionary for more information.

Field	Description	Example
`row_identifier`	This will be used on the response to map back to this row, eliminating the need to pass back all fields. The field must be unique.	asdfa823
`utc_datetime`	The date and hour of the impression. We recommend sending hourly data to enable accurate emissions calculations, as the grid mix changes significantly throughout the day. Hourly data also allows reporting on local time zones.	`2023-08-14 01:00:00`
`inventory_id`	The domain or app ID (see below for DOOH)	`nytimes.com`
`global_placement_id`	The global placement ID provided by the publisher. This is important because ad stack and formats often vary significantly across placements	`top_left_300_250`
`country`	The two-letter country code where the impression was delivered	`FR`
`device_type`	The type of device that viewed the impression	`phone`
`network`	The network that the consumer device used to view the impression	`fixed`
`campaign_id`	The ID of the campaign to report on	`1234`
`campaign_name`	The name of the campaign to report on	`Big Q1 promotion`
`impressions`	The number of impressions delivered with these characteristics	`1823821`
`video_size`	The dimensions of the provided input video
`video_duration`	The duration of the provided input video

Channel Specificities

DOOH Input Format

For DOOH, media_owner is a required field to map screen IDs properly. The venue_category is recommended as well. Plays or impressions are both accepted inputs. Below is a list of recommended fields:

Field	Description	Example	Priority
`utc_datetime`	The date and hour of the impression. We recommend sending hourly data to enable accurate emissions calculations, as the grid mix changes significantly throughout the day. Hourly data also allows reporting on local time zones.	`2023-08-14 01:00:00`	✅ Required
`channel`		`dooh`	💡 Recommended
`inventory_id`	The screen ID	`sydney-north-18`	💡 Strongly Recommended
`country`	The country where the DOOH screen is located	`AU`	✅ Required
`media_owner`	The media owner that owns the screen	`JC Decaux AU`	💡 Strongly Recommended
`venue_category`	The type of screen — used for screens that have incomplete data	`bus-shelter`	💡 Recommended
`campaign_id`	The ID of the campaign to report on	`1234`	💡 Recommended
`campaign_name`	The name of the campaign to report on	`Big Q1 promotion`	💡 Recommended
`plays`	The number of plays delivered with these characteristics (can also be impressions)	`467`	💡 Strongly Recommended
`impressions`	The number of people reached behind the DOOH screens	`5982`	💡 Strongly Recommended

Linear TV Input Format

For Linear TV campaigns, we recommend passing the below input fields.

Field	Description	Example	Priority
`utc_datetime`	The date and hour of the TV spot. We recommend sending hourly data to enable accurate emissions calculations, as the grid mix changes significantly throughout the day. Hourly data also allows reporting on local time zones.	`2023-08-14 01:00:00`	✅ Required
`channel`	The marketing channel	`linear-tv`	💡 Strongly Recommended
`country`	The country in which the TV spot is viewed	`US`	✅ Required
`media_owner`	The media owner that owns the TV channel	`Paramount`	💡 Strongly Recommended
`inventory_id`	The TV channel	`Nickeledeon`	💡 Recommended
`plays`	The number of TV spots that aired	`3`	✅ Required
`playDuration`	The duration (in seconds) of the TV spot	`30`	💡 Strongly Recommended
`impressions`	The number of household impressions	`182821`	✅ Required if `unique_reach`and `average_frequency` are not provided
`unique_reach`	The number of unique individuals reached	`245907`	✅ Required if `impressions` is not provided
`average_frequency`	The average number of times a unique individual has been exposed to the TV spot	`2.4`	✅ Required if `impressions` is not provided
`campaign_id`	The ID of the campaign to report on	`1234`	💡 Recommended
`campaign_name`	The name of the campaign to report on	`Big Q1 promotion`	💡 Recommended
`grp`	The gross rating point of the campaign (unique_reach * average_frequency / target_audience_size)	`176`
`tv_distribution_method`	The distribution method used to transmit the TV broadcast signal. I unknown, leave null.	`satellite`

Search Input Format

For Search campaigns, we recommend passing the below input fields.

Field	Description	Example	Priority
`utc_datetime`	The date and hour of the TV spot. We recommend sending hourly data to enable accurate emissions calculations, as the grid mix changes significantly throughout the day. Hourly data also allows reporting on local time zones.	`2023-08-14 01:00:00`	✅ Required
`channel`	The marketing channel	`search`	💡 Recommended
`country`	The country in which the TV spot is viewed	`US`	💡 Strongly Recommended
`inventory_id`	The TV channel	`google.com`	✅ Required
`impressions`	The number of impressions	`182821`	✅ Required
`click`	The number of clicks	`914`
`spend`	The number of	`1142`	✅ Required if pricing defined as % of media.
`campaign_id`	The ID of the campaign to report on	`1234`	💡 Recommended
`campaign_name`	The name of the campaign to report on	`Big Q1 promotion`	💡 Recommended

Green Media Product fields

To designate an impression as a GMP, use the is_gmp field. Optionally, set the compensation rate using gmp_compensation_rate (0 means "no compensation"; 1 means "compensate for 100% of emissions; greater than 1 would over-compensate).

Field	Type	Description	Example	For GMP reporting
`utc_datetime`	`string`	The date of the impression. The hour is not required, but hourly data enables reporting on local time zones. We recommend sending hourly data for the most accurate emissions calculations, as the grid mix changes significantly throughout the day. Example: `2023-08-14 01:00:00`.	2023-08-14	Needed
`impressions`	`integer`	Number of delivered impressions	1000	Needed
`inventory_id`	`string`	The domain, app ID, screen identifier, or podcast name	http://nytimes.com/	At least one of: inventory_id, app, or domain
`app`	`string`		com.nytimes.android	At least one of: inventory_id, app, or domain
`domain`	`string`		http://nytimes.com/	At least one of: inventory_id, app, or domain
`country`	`string`	This is the country ISO 3166-2 Alpha-2- or an Alpha-3 code, e.g., USA or a country name	US	Needed
`deal_id`	`string`	Required if `deal_name` is provided	deal_id	Needed
`brand`	`string`	Brand name	Hasbro	Needed
`is_gmp`	`boolean`	Designate an impression as a GMP. It can optionally be set at the account level	true	Needed if not set at account level
`gmp_compensation_rate`	`float`	GMP compensation rate. `0` means no compensation; `1` means compensate for 100% of emissions; `greater than 1` would over-compensate. It can optionally be set at the account level	1	Needed if not set at account level
`device_type`	`string`	The type of device		Highly recommended
`seller_domain`	`string`	Canonical seller domain		Highly recommended
`global_placement_id`	`string`	Primary key to identify placements	/1111/homepage#728x90	Highly recommended

Overview of the Output Format

Output responses are configurable. Media Delivery responses can contain supplied input fields and emissions measurement fields. Response configuration is done in the Integrate UI.

Available measurement response fields are:

Field	Description	Example
`row_identifier`	The same row identifier that was passed into the request	asdfa823
`inventory_coverage`	Has the row successfully been modeled. If `false` then no emissions results will be available for this row.	modeled
`total_emissions_grams`	Total emissions in grams is the sum of `ad_selection_emissions_grams`, `media_distribution_emissions_grams` and `creative_delivery_emissions_grams` In grams of CO₂e.	0.012
`compensated_emissions_grams`	The number of emissions compensated based on GMP rules	0.0028
`ad_selection_emissions_grams`	Ad tech including servers and cloud computing; analytics; network traffic; storage; data providers; and vendor overhead. In grams of CO₂e.	0.005
`media_distribution_emissions_grams`	Media delivery including CMS; CDNs and hosting services; publishing overhead including employee and office expenses; data transfer. In grams of CO₂e.	0.0012
`media_distribution_consumer_device_emissions_grams`	Media delivery consumer device emissions. In grams of CO₂e. These emissions are not included in the `total_emissions_grams`	0.012
`creative_delivery_emissions_grams`	The emissions related to delivering the creative to a display surface.	0.0065
`creative_delivery_consumer_device_emissions_grams`	Creative delivery of consumer device emissions. In grams of CO₂e. These emissions are not included in the `total_emissions_grams`	0.012
`compensation_provider`	Applicable when compensating for delivered media	carbon direct
`climate_risk_compliant`	Impressions are marked climate risk if inventory either has extremely high gCO₂e when compared to geo and channel benchmarks or has been flagged as proliferating practices that contribute to high emissions	true
`emissions_breakdown`	JSON data containing full emissions breakdown	{"breakdown":{"adSelection":{"breakdown":{"adPlatform":{"emissions":144.14783646188533}},"total":144.14783646188533},"creativeDelivery":{"breakdown":{"adPlatform":{"emissions":0},"dataTransfer":{"emissions":0.4699678050999183}},"total":0.4699678050999183},"mediaDistribution":{"breakdown":{"corporate":{"emissions":49.018915},"dataTransfer":{"emissions":0.5310414263298526}},"total":49.54995642632985}},"framework":"scope3"}`
`coverage`	JSON data containing full coverage information. Here, it is possible to see what channel and property were matched.	{"adFormat":{"value":"leaderboard-728x90-banner","verified":true},"channel":{"value":"web"},"impressions":{"modeled":1000,"processed":0,"skipped":0},"property":{"value":"cnn.com"},"supplyGraph":{"logical":{"averageDepth":3.2,"maxDepth":5,"minDepth":2},"technical":{"averageDepth":3.1,"maxDepth":5,"minDepth":2},"totalCount":256}}
`policies`		[{"compliant":true,"policy":"climateRisk","policyOwner":"Scope3"}]
`calculation_error`	Correct data has been provided but a calculation of emissions was not possible.	{"message":"Invalid Date. unsupported date: 2024-03-20 00:00 UTC. dates must be on or before: 2024-03-19 00:00 UTC"}
`parser_error`	Input values are invalid	`Invalid country code: CURACAO`
`report_id`