Media Delivery

Upload media delivery data to share with partners

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 & Linear TV)

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:

FieldDescriptionExamplePriority
utc_datetimeThe 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:00Required
channeldooh💡 Recommended
inventory_idThe screen IDsydney-north-18💡 Strongly Recommended
countryThe country where the DOOH screen is locatedAURequired
media_ownerThe media owner that owns the screenJC Decaux AU💡 Strongly Recommended
venue_categoryThe type of screen — used for screens that have incomplete databus-shelter💡 Recommended
campaign_idThe ID of the campaign to report on1234💡 Recommended
campaign_nameThe name of the campaign to report onBig Q1 promotion💡 Recommended
playsThe number of plays delivered with these characteristics (can also be impressions)467💡 Strongly Recommended
impressionsThe number of people reached behind the DOOH screens5982💡 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_reachand 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

broadcastMethod

The broadcast method used to transmit the TV broadcast signal. I unknown, leave null.

satellite



Traditional Radio Input Format

For Traditional Radio campaigns, we recommend passing the below input fields.

Field Description Example Priority

utc_datetime

The date and hour of the radio 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

traditional-radio

💡 Strongly Recommended

country

The country in which the radio spot is viewed

GB

Required

media_owner

The media owner that owns the radio station

News UK

💡 Strongly Recommended

inventory_id

The radio station

talkSPORT

💡 Recommended

plays

The number of radio spots that aired

3

Required

playDuration

The duration (in seconds) of the radio spot

30

💡 Strongly Recommended

impressions

The number of audience impressions

182821

Required if unique_reachand 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 radio 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

broadcastMethod

The distribution method used to transmit the radio broadcast signal. I unknown, leave null.

FM


Search Input Format

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


FieldDescriptionExamplePriority
utc_datetimeThe 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 zones2023-08-14 01:00:00Required
channelThe marketing channelsearch💡 Recommended
countryThe country in which the impression was servedUS💡 Strongly Recommended
inventory_idThe domain or app ID where the search originates fromgoogle.comRequired
impressionsThe number of impressions182821Required
clickThe number of clicks914
spendThe media cost in USD1142Required if pricing defined as % of media.
currencyThe 3-letter code representing the currency the spend attributed is reported in. If not specified, we assume USDEUR
campaign_idThe ID of the campaign to report on1234💡 Recommended
campaign_nameThe name of the campaign to report onBig 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