--- updatedAt: 2025-10-07T11:53:52.000Z agentTools: projectIndex: https://docs.scope3.com/llms.txt --- # 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](https://scope3.com/integrate/overview) tool in the CSP. Once data has been uploaded and approved, it will be processed through the [measurement](https://docs.scope3.com/reference/measure-1) 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](media-delivery-schema) and the [Data Dictionary](https://docs.scope3.com/docs/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:
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** and needed for screen identification when inventory_id is provided.
`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_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. | 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` | The marketing channel | `search` | πŸ’‘ **Recommended** | | `country` | The country in which the impression was served | `US` | πŸ’‘ **Strongly Recommended** | | `inventory_id` | The domain or app ID where the search originates from | `google.com` | βœ… **Required** | | `impressions` | The number of impressions | `182821` | βœ… **Required** | | `click` | The number of clicks | `914` | | | `spend` | The media cost in USD | `1142` | βœ… **Required** if pricing defined as % of media. | | `currency` | The 3-letter code representing the currency the spend attributed is reported in. If not specified, we assume USD | `EUR` | | | `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** |
### Classic OOH input format For classic OOH, we recommend using the following channel specific input fields:`campaign_start_date`, `campaign_end_date`, `display_duration_days`, `physical_width_meters` and `physical_height_meters`. | Field | Description | Example | Priority | | :----------------------- | :----------------------------------------------------------------------------------- | :---------------------- | :--------------------------------------------------------------------------- | | `country` | The country where the DOOH screen is located | `GB` | βœ… **Required** | | `channel` | The marketing channel | `classic-ooh` | πŸ’‘ **Strongly Recommended** | | `campaign_start_date` | The start date of the OOH campaign | `2025-11-03` | βœ… **Required** if `display_duration_days` is not provided. | | `campaign_end_date` | The end date of the OOH campaign | `2025-11-16` | βœ… **Required** if `display_duration_days` is not provided. | | `display_duration_days` | The number of days | `14` | βœ… **Required** if `campaignStartDate` and `campaignEndDate`are not provided. | | `share_of_time_pct` | The percentage of time the ad is displayed on the panel. | `100` | πŸ’‘ **Recommended** | | `venue_category` | The venue in which the panel is located - used for panels that have incomplete data. | `airport` | πŸ’‘ **Recommended** | | `inventory_id` | The identifier of the panel | `heathrow-terminal2-18` | πŸ’‘ **Recommended** | | `media_owner` | The media owner who owns the rights to display ads on the panel | `JCDecaux GB` | βœ… **Required** if `inventory_id` is provided. | | `physical_width_meters` | The width of the ad | `3.0` | πŸ’‘ **Recommended** | | `physical_height_meters` | The height of the ad | `4.0` | πŸ’‘ **Recommended** | | `impressions` | The number of people reached behind the panel | `5982` | πŸ’‘ **Strongly Recommended** | | `campaign_id` | The ID of the campaign to report on | `1234` | πŸ’‘ **Recommended** | | `campaign_name` | The name of the campaign to report on | `Big Q4 promotion` | πŸ’‘ **Recommended** | | `grp` | The gross rating point of the campaign | `78.5` | πŸ’‘ **Recommended** |
### Print input format For Print, we recommend passing the below input fields. | Field | Description | Example | Priority | | :------------------- | :------------------------------------------------------------ | :----------------- | :------------------------------------------------ | | `utc_datetime` | The date of issue of the print publication. | `2025-11-16` | βœ… **Required** | | `channel` | The marketing channel | `print` | πŸ’‘ **Strongly Recommended** | | `country` | The country where the publication is circulated | `US` | πŸ’‘ **Recommended** | | `inventory_id` | The name of the publication | `Vogue US` | πŸ’‘ **Recommended** | | `media_owner` | The publisher of the publication | `Conde Nast` | βœ… **Required** if `inventory_id` is provided. | | `print_medium` | The type of print publication (newspaper, magazine, leaflet) | `magazine` | πŸ’‘ **Recommended** | | `ad_format` | The type of ad | `Full Page` | πŸ’‘ **Recommended** | | `print_circulations` | The number of print publication copies that were distributed. | `500000` | βœ… **Required** if `impressions` is not provided. | | `impressions` | The number of readers | `5982` | βœ… **Required** if `inventory_id` 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 Q4 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 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
`}