Migrating from the V1 measurement endpoint to the V2 measurement endpoint

This guide outlines the approach to migrating you from the V1 Measurement endpoint to the updated V2 Measurement endpoint. The goal is to ensure a smooth transition with minimal disruptions to your access to Scope3 data.

Please also see this guide that will showcase the changes necessary to switch from V1 to V2 measure endpoint

Key Changes

Endpoint

Below is a mapping of how V1 functionality maps to V2:

V1	V2
`/v1/calculate/daily`	`/v2/measure`

The above endpoints take different parameters and return different data.
Please be sure to review the full V2 API documentation to better understand syntax and expected output.

Input changes

Here are the key changes to the input parameters. To see the full list of V2 parameters visit the new API reference docs.

V1 input name	V2 input name	V2 input value
`date`	`utcDatetime`	`2024-01-05 00:00:00` Hourly information is optional. `2024-01-05` would also be a valid value.
`creative.format`	Creative format is no longer supported. Instead it is suggested you provide the total bytes of the creative e.g. using `totalVideoDataTransferBytes`for a video creative.	Creative measurement is one of the biggest improvements made as part of the V2 API. For a comprehensive guide to V2 creative inputs see here Creative Delivery
`site.domain`	`inventoryId`	`nytimes.com`
`app.storeId`	`inventoryId`	`com.nytimes`
`channel`	`channel`	`app`,`web`,`streaming-video`,`social`,`digital-audio`,`dooh`,`ctv-bvod`
`seller`	`sellerName` or `sellerDomain`	`teads` or `teads.com`

Output changes

Here are the most important changes to relevant output fields. To see the full list of output parameters, please see Media Delivery.

* Please note: consumer device emissions are not included by default. In order to include consumer device emissions, make sure to select framework = scope3-consumer-device.

V1 output field	V2 output field	sample V2 output value
`domain_coverage`	`inventory_coverage`	‘modeled’
`climate_risk`	`climate_risk_compliant`	FALSE
`creative_distribution_emissions`	`creative_delivery_emissions_grams`	13.23
`creative_consumer_device_emissions`	`creative_delivery_consumer_device_emissions_grams`*	123.34
`ad_selection_emissions`	`ad_selection_emissions_grams`	2.362194419
`consumer_device_emissions`	`media_distribution_consumer_device_emissions_grams`*	5.12
`media_distribution_emissions`	`media_distribution_emissions_grams`	2.801564
`total_emissions`	`total_emissions_grams`	65.676433

Migration Steps

Convert your API client access and client ID keys to the new bear token format. See the Access and Authorization guide for more details on how to do that.
Update your requests to use the latest V2 inputs.
Update your integrate to consume the new V2 JSON response.

Support

For any additional questions or issues during the API migration process, please contact [email protected]

FAQ

Should I migrate to the V2 measure endpoint or consider using the new Media Delivery integration?

In most cases it is recommended to migrate to the Media Delivery integration. Media Delivery offers improved scalability, developer experience and deep integration with the CSP. See this guide for steps on migrating to Media Delivery.