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) | 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 |
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.
Field | Description | Example |
---|---|---|
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 screen ID | sydney-north-18 |
media_owner | The media owner that owns the screen | JC Decaux AU |
venue_category | The type of screen — used for screens that have incomplete data | bus-shelter |
campaign_id | The ID of the campaign to report on | 1234 |
campaign_name | The name of the campaign to report on | Big Q1 promotion |
plays | The number of plays delivered with these characteristics (can also be impressions) | 182821 |
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 |
Updated 2 months ago