The Inventory Intelligence API allows ad tech platforms to map Scope3 data onto the supply that they see on a daily basis. The ATP will send Scope3 a file with the inventory keys and volume that they see on a daily basis. Scope3 will map these keys to inventory metrics and send the data back to the ATP through either a flat file or through a real-time data provider integration.

Supply (inbound)

Managing Cardinality

The objective should be to send 99% of total volume but a fraction of the total cardinality, ideally with no more than 100M rows of data per day.

Suggestions for reducing cardinality:

Set a threshold (a HAVING clause or equivalent) to remove the long tail of low-volume tuples (for instance, having fewer than 10 impressions per row)
Combine low-volume countries into the default WW country, or exclude them entirely
Check for publishers that implement placements or GPIDs incorrectly

Placement IDs

Scope3 uses global_placement_id as its primary key to identify placements. However, due to sparse and inconsistent support for GPID, we also request the placement ID that is sent through the supply chain. If these are the same, that's great; if not, we can use gpid-placement as a map to increase coverage.

Domain and App Store Aliases

Scope3 maintains various mappings of domains, subdomains, ad serving domains, masked domains, and App Store aliases. When we receive an inventory_id we will attempt to find a good match to a property.

Traffic Metrics

The required metric is ad_opportunities which should represent the total number of unique ad slots available for auction from a particular inventory key.

If there is throttling logic that rejects traffic (for instance, a QPS threshold), this can be modeled by adding the ad_opportunities_processed metric.

ATP Supply File Format (sent to Scope3)

Both the cloud bucket and File Upload API methods accept a CSV file. See here for full CSV schema details.

Field	Required	Example	Comments
`utc_datetime`	✅	`2023-08-01`	YYYY-MM-DD for monthly aggregation
`atp`		`adtech.ai`	The ad tech platform this data applies to—defaults to the uploading organization.
`country`	✅	`US`	Two-letter country code (may use WW for long-tail / low-volume countries)
`seller_id`		`45dc99ba`	The seller's schain identifier (should exactly match your sellers.json file)
`inventory_id`	✅	`nytimes.com`	The domain or app ID of the property
`is_app`		`true`	Is this inventory ID an app?
`global_placement_id`		`topleft_300_250`	The GPID of the placement on the property
`seller_placement_id`		`2342810`	The placement ID sent by the seller (may be the same as GPID)
`max_placement_size`		`300x600`	Helpful to map placements to page geometry
`device_type`		`phone`	One of: phone, tablet, pc, tv, smart-speaker
`integration_method`		`openrtb`	One of: `openrtb`, `mediation`, `sdk`, `tag`, `prebid`, `google-ob`
`ad_opportunities`	✅	`123456789`	Number of auctioned ad slots received (requests x ad slots per request)
`ad_opportunities_processed`		`22321322`	Number of ad slots processed, for instance, that pass QPS throttling logic

Flat file (outbound)

Inventory Intelligence File Format (sent to ATP)

This file will have a row for each unique {seller_id, inventory_id, is_app, global_placement_id, seller_placement_id, country} tuple in the input file.

Field	Example	Comments
`seller_id`	`45dc99ba`	Maps to supply input
`inventory_id`	`nytimes.com`	Maps to supply input
`is_app`	`true`	Maps to supply input
`seller_placement_id`	`2342810`	Maps to supply input
`global_placement_id`	`topleft_300_250`	Maps to supply input
`country`	`US`	Maps to supply input
`segments`	`gmp_eligible, gmp_plus_eligible, ok_buyer_policy_1`	A comma-separated list of all the segments for this tuple
`value_map`	`{"climate_risk_percentile": 26}`	A JSON object with key:value pairs
`modeled`	`true`	If the inventory or seller does not match a property or ATP, this will be false. This is an important QA metric to ensure coverage and full delivery.

Real-time data provider (outbound)

The Scope3 RTDP is a RESTful API that provides low latency (sub 10 ms) access to the Inventory Intelligence dataset.

Authentication

You will need an authentication key to use the real-time data provider (RTDP). This is different than the API keys used for the primary Scope3 API. Pass this key into a header with the key x-scope3-auth.

Endpoints

We operate servers in several geographical regions globally. We suggest testing latencies from each of your data centers by hitting our /status endpoint.

Endpoint	Location
`rtdp.scope3.com`	Global

Regional-specific endpoints are available if needed.

Input Parameters

The RTDP takes in parameters using query string key-value pairs or through a JSON body that confines to the ORTB spec.
When sending an ORTB-compliant body, not all fields are required. We will only parse out the following parameters.

Key	Example Value	ORTB Field
domain	yahoo.com	site.domain
appId	com.accuweather.android	app.bundle
sellerId	ifW4ft3g	app.publisher.id OR site.publisher.id
sellerPlacementId	rKbSuikdwy9UPfEwBcR8Pf6z	site.id
gpid	/22888152279/us/yhp/main/dt/us_yhp_main_dt_top_center	imp[].ext.gpid
country	US	device.geo.country

Output Response

Key	Example Value	Comment
segments	["gmp_plus_eligible", "gmp_eligible"]	The array of segments.
ttlSeconds	86400	How long the RTDP client should cache this response
status	modeled	Options: `modeled`, `missing`, `error`

Custom endpoints

Scope3 may be able to support custom parameters. Please get in touch with us to discuss thisfurther.

Segments

Custom segments may be defined through Policies (business rules that set the logic for inclusion) in the CSP user interface. Based on the configured segment identifier, these segments will be added to the response.

Segments may also be generated directly from datasets available on the Scope3 platform.

Platform Segments

Segment	Description
`gmp_eligible`	Is this inventory key below the climate risk threshold? (Equivalent to the `gmp_eligible` flag in the v1 measure API)
`gmp_plus_eligible`	Does this inventory meet the GMP+ standard (coming Q2 2024)

Platform Key-Values

Key	Value Range	Description
`climate_risk_percentile`	0-99	The climate risk percentile vs benchmark