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 levels of granularity, we continued to support our original API fields. While this made our API very flexible, it also made it difficult to explain all of the possible variations. It also meant that fundamental changes, like reimagining channels or ad formats, were effectively not possible.

With the v2 API, we started (more or less) from scratch based on all of our learnings to date. 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 we created a generic, consistent process to push data to the API. We built a mapping layer that can translate proprietary field names to the standardized Scope3 fields, eliminating a bunch of complex and confusing aliasing code. We also laid the groundwork for increased granularity, with particular focus on a move to hourly grid mix data, placement-level models, and support for data sharing from vendors.

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 by far the most comprehensive and accurate emissions model available at the time and quickly became the industry standard.

However, the 2023 emissions model had some obvious 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 do make adjustments to account for unlikely supply paths). Estimated session and traffic data is not universally available and also tends to be quite 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 most important 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 just 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 web site (YouTube, Netflix, etc.) called streaming-video and a non-streaming web site, which we called display-web. This poor choice of names has caused myriad 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 in the near future - 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. Domain and app are no longer supported as separate fields.

Don’t use Measure for GMP or Climate Shield

When we originally 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. Among other issues, 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 be pushed to a cloud bucket for use in deals and campaigns. We recommend integrating the policy output directly into platforms instead of creating inventory lists manually, especially as supporting placements will be a requirement 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 a number of format improvement to simplify managing measure response data. Its 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 a number of capabilities that have been requested by clients 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. Using 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. V2 brings an increased breadth in the type of creatives that can be modeled thanks to ad formats. The currently available ad formats are listed here. For more detail on the underlying updates around creative please see the methodology page.

Metered billing

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