What's New in 2.0

Improved developer experience

When we first created our API in March 2022, Scope3 was three months old. We had just finished our first emissions model based on a crawler that pulled data from websites around the internet, parsing prebid configurations and measuring page weight. Our API was a simple RESTful service with a single endpoint serving a single channel.

As we learned and evolved our model, adding channels and increasing granularity levels, we continued supporting our original API fields. While this made our API very flexible, it also made it difficult to explain all possible variations. It also meant that fundamental changes, like reimagining channels or ad formats, were not possible.

With the v2 API, we started (more or less) from scratch based on what we had learned. We cleaned up our channels to better represent how our clients think about them; we made authorization simpler; we built a UI to help with setup and debugging; and created a generic, consistent process to push data to the API. We built a mapping layer to translate proprietary field names to the standardized Scope3 fields, eliminating complex and confusing aliasing code. We also laid the groundwork for increased granularity, focusing on the move to hourly grid mix data, placement-level models, and vendor data-sharing support.

Foundations for a new emissions model

In January 2023, we released an emissions model based on an open-source methodology, third-party data sources like data.ai and SimilarWeb, and public ads.txt/sellers.json data. This was the most comprehensive and accurate emissions model and quickly became the industry standard.

However, the 2023 emissions model had some apparent limitations. Ads.txt data is limited to programmatic channels, doesn't model proprietary ad servers or direct ad serving, and is generally a worst-case view of the supply chain (though we make adjustments to account for unlikely supply paths). Estimated session and traffic data is not universally available and tends to be inaccurate.

The "right" way to model emissions is to use contributed data from each company in the supply chain. With 70+ customers using the Scope3 platform as of January 2024, it's now possible to imagine that a significant portion of the emissions model could be based on dynamic, directly contributed data. But where to put it? API v2 provides schemas for the critical parts of the emissions model for partners and third-party vendors to integrate session, traffic shaping, and corporate sustainability directly into the Scope3 platform.

Another key evolution of the v2 emissions model is to operate at the placement level, not the property. This is critical in the web channel where different placements on the same site may have dramatically different emissions and effectiveness. As we move to the v2 emissions model in Q2 2024, we strongly recommend that partners start using gpid as a primary identifier.

Breaking changes

Simplified authorization

The v1 API used two keys for authorization. v2 has one key and uses standard bearer authorization. You can use v1 keys in v2 by concatenating them like:

Authorization: Bearer scope3_accessClientId_accessClientSecret

API keys are now self-serve for customers at scope3.com.

Channels are now (we hope) less confusing

The original concept of channels was to differentiate between a streaming video website (YouTube, Netflix, etc.) called streaming-video and a non-streaming website, which we called display-web. This poor choice of names has caused questions like “If I want to run a video ad on a website, which channel is it? It’s not display.” and “Why don’t you have a CTV channel?”

The new channels are simpler: If it’s a website, it’s channel web regardless of the ad format. If it’s a CTV property, it’s channel ctv/bvod. If it’s an app, it’s app. If it’s a social property, social. You might notice a problem here - what if it’s a social app? We have a mapping so that if you request, say, Snap as app, we’ll return the same thing as if you request Snap as social.

To migrate:

• Replace display-web with web and replace display-app with app
• If you are using streaming-video for video formats on web/app properties, switch to using the outstream video ad format with web or app as the channel
• If you are using streaming-video for CTV, switch to ctv/bvod

UTC dates

In v1, it was unclear what timezone was expected for the date field. In v2, this field is renamed utcDateDateTime to clarify that all dates are UTC. Both date (2023-08-14) or date time (2023-08-14 01:00:00) values are supported by this new field.

Providing a date and time means we will use hourly grid mix data when we add support for this soon - if possible, we suggest starting to use this now.

Inventory ID replaces domain and app

The inventoryId field has been available and recommended for some time and is now the preferred way to identify a property.

Don’t use Measure for GMP or Climate Shield

When we initially shipped GMPs in 2022 and Climate Shield in 2023, the only way to get the climate risk or GMP eligibility for a property was to query the Measure API. This made it impossible to create a different policy—for instance, setting the emissions cutoff to 10% instead of 7% or using a different MFA provider.

The v2 API introduces the concept of a Policy: a set of rules that determine which properties and placements are eligible for a particular use case. GMP eligibility is now expressed as a platform-wide policy.

Clients can subscribe to bespoke, client, and platform-wide policies and have the resulting properties and placements pushed to a cloud bucket for use in deals and campaigns. We recommend integrating the policy output directly into platforms instead of manually creating inventory lists, especially as supporting placements will be required for upcoming capabilities.

New response format for Measure

The Measure API has been growing out of hand as we added new functionality over the past two years. There have been several format improvements to simplify managing measure response data. It's now possible to select the specific output fields using the fields parameter. Measure can be supplied with an emissions framework for increased choice over underlying framework. Currently, available frameworks are scope-3 and scope3-consumer-device. The v2 measure output has also been reorganized to make it easy to understand the emissions breakdown and the coverage of the request.

Migrate from GMP Upload to Media Delivery API

The GMP upload API has been replaced by the Media Delivery API. The Media Delivery schema supports variable carbon compensation using the compensation_pct field, including values over 100% if desired. It also supports sending a blend of GMP and non-GMP impressions with the is_gmp field. The Media Delivery API has many capabilities that clients have requested including support for deals, campaigns, line items, and insertion orders. These fields, as well as client, can be used to split invoices (for instance, to create a separate invoice line per client or per insertion order).

Cloud storage buckets are the preferred integration method

The v2 API has first-class support for the major public clouds (Amazon, GCP, and Azure) for bidirectional integration to cloud storage buckets. A cloud storage bucket has no throttling or file size limitations, like the Measure API, and allows us to process data in parallel for much higher throughput.

Ad Formats

The supported v1 creative formats were banner, video, text, and audio. Thanks to ad formats, V2 brings an increased breadth in the type of creatives that can be modeled and measured. The currently available default ad formats are listed here. Custom ad formats can be explored in CSP in the explore ad format section. For more detail on the underlying updates around creative, please see the methodology page.

Metered billing

For customers with usage-based contracts, impression volumes on the Media Delivery API can now be used as the source of truth for monthly billing. Reprocessed and failed files are not included in the billable count. If you want to switch to metered billing, please contact your Scope3 account team.