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

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 Campaign 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

The key fields for the Media Delivery schema are below. There are many fields that can be added to refine the measurement - see full input schema documentation and the Data Dictionary for more information.

Field	Example	Comments
`row_identifier`	`asdfa823`	This will be used on the response to map back to this row, eliminating the need to pass back all of the fields. Must be unique.
`utc_datetime`	`2023-08-14 01:00:00`	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 enables reporting on local timezones.
`inventory_id`	`nytimes.com`	The domain or app ID (see below for DOOH)
`global_placement_id`	`top_left_300_250`	The global placement ID provided by the publisher. Important because the ad stack and formats often vary significantly across placements
`country`	`FR`	The two-letter country code where the impression was delivered
`device_type`	`phone`	The type of device that viewed the impression
`network`	`fixed`	The network that the consumer device used to view the impression
`campaign_id`	`1234`	The ID of the campaign to report on
`campaign_name`	`Big Q1 promotion`	The name of the campaign to report on
`impressions`	`1823821`	The number of impressions delivered with these characteristics

DOOH Input Format

For DOOH, media owner is a required field to properly map screen IDs. Venue category is recommended as well. Plays or impressions are both accepted inputs.

Field	Example	Comments
`utc_datetime`	`2023-08-14 01:00:00`	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 enables reporting on local timezones.
`inventory_id`	`sydney-north-18`	The screen ID
`media_owner`	`JC Decaux AU`	The media owner that owns the screen
`venue_category`	`bus-shelter`	The type of screen, used for screens that have incomplete data
`campaign_id`	`1234`	The ID of the campaign to report on
`campaign_name`	`Big Q1 promotion`	The name of the campaign to report on
`plays`	`182821`	The number of plays delivered with these characteristics (can also be impressions)

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

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	Example	Comments
`row_identifier`	`asdfa823`	The same row identifier that was passed into the request
`modeled`	true	Has the row successfully been modeled. If `false` then no emissions results will be available for this row.
`total_emissions_grams`	0.012	Total emissions in grams using the selected framework
`compensated_emissions_grams`	0.0028	The number of emissions compensated based on GMP rules
`ad_selection_emissions_grams`	0.005	Ad tech including servers and cloud computing; analytics; network traffic; storage; data providers; and vendor overhead. In grams of CO₂e.
`media_distribution_emissions_grams`	0.0012	Media delivery including CMS; CDNs and hosting services; publishing overhead including employee and office expenses; data transfer. In grams of CO₂e.
`creative_delivery_emissions_grams`	0.0065	The emissions related to delivering the creative to a display surface.
`emissions_framework`	`scope3`	The underlying framework used to calculate emissions values.
`compensation_provider`	`carbon direct`	Applicable we compensating for delivered media
`climate_risk_compliant`	`true`	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
`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"}`	JSON data containing full emissions breakdown
`coverage`	{"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}}	JSON data containgin full coverage information. Here it is possible to see what channel and property where matched.
`policies`	[{"compliant":true,"policy":"climateRisk","policyOwner":"Scope3"}]
`calculation_error`	{"message":"Invalid Date. unsupported date: 2024-03-20 00:00 UTC. dates must be on or before: 2024-03-19 00:00 UTC"}	Correct data has been provided but a calculation of emissions was not possible.
`parser_error`	`Invalid country code: CURACAO`	Input values are invalid
`report_id`