--- updatedAt: 2025-08-28T17:15:56.000Z agentTools: projectIndex: https://docs.scope3.com/v1.3/llms.txt --- # Campaign calculation Calculates the carbon footprint for an advertising campaign per day # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "title": "calculator Scope3 Carbon Calculator API", "description": "API to calculate the carbon footprint of a campaign", "version": "1.0.0" }, "servers": [ { "url": "https://api.scope3.com/v1" } ], "paths": { "/calculate/daily": { "post": { "summary": "Campaign calculation", "description": "Calculates the carbon footprint for an advertising campaign per day", "operationId": "dailyCalculateFootprint", "parameters": [ { "in": "query", "name": "includeRows", "description": "if set to a truthy value, include all rows in the response", "schema": { "type": "boolean" } }, { "in": "query", "name": "previewMethodology", "description": "if set to a truthy value, calculate using latest methodology and datasets", "schema": { "type": "boolean" } } ], "requestBody": { "description": "Rows of delivered impressions to measure.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DailyCalculateRequestBody" } } } }, "responses": { "200": { "description": "success response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DailyCalculateOutputSummary" } } } }, "default": { "$ref": "#/components/responses/ErrorResponse" } } } } }, "security": [ {}, { "accessClientId": [], "accessClientSecret": [] } ], "components": { "securitySchemes": { "accessClientId": { "type": "apiKey", "in": "header", "name": "AccessClientId" }, "accessClientSecret": { "type": "apiKey", "in": "header", "name": "AccessClientSecret" } }, "schemas": { "DomainCoverageEnum": { "type": "string", "enum": [ "modeled", "missing", "unknown" ], "description": "modeled - domains/apps are in the dataset with reasonable confidence of accuracy.\nmissing - domains/apps have not been modeled yet and will automatically be queued for analysis.\nunknown - domains/apps appear to have errors. e.g. A site that has an invalid domain name." }, "CreativeFormat": { "type": "string", "enum": [ "banner", "video", "text", "audio" ], "example": "banner", "description": "Banner uses payload size and conventional model.\nVideo and audio use duration and power model.\nText returns 0" }, "DurationSeconds": { "type": "integer", "example": 15, "description": "Time the creative plays. Only used for video format." }, "PayloadSize": { "type": "integer", "example": 150000, "description": "The number of bytes transferred to fully display the creative." }, "Creative": { "type": "object", "required": [ "format" ], "properties": { "width": { "type": "integer", "deprecated": true, "example": 300, "description": "width of creative. only applies to banner creatives" }, "height": { "type": "integer", "deprecated": true, "example": 250, "description": "height of creative. only applies to banner creatives" }, "format": { "$ref": "#/components/schemas/CreativeFormat" }, "durationSeconds": { "$ref": "#/components/schemas/DurationSeconds" }, "bytes": { "deprecated": true, "type": "integer", "example": 150000, "description": "Deprecated. Replaced by payloadSize.\nThe number of bytes transferred to fully display the creative." }, "payloadSize": { "$ref": "#/components/schemas/PayloadSize" } } }, "Domain": { "type": "string", "example": "nytimes.com", "description": "The domain of the property. The domain will be evaluated without http(s), www, port identifier, trailing slash or path. If a subdomain is provided, we will look up by subdomain and fallback to the base domain if we do not have a model for the subdomain." }, "Property": { "type": "string", "example": "nytimes.com", "description": "Name of the property used to calculate the footprint." }, "SiteInput": { "type": "object", "example": { "domain": "nytimes.com" }, "required": [ "domain" ], "properties": { "domain": { "$ref": "#/components/schemas/Domain" } }, "description": "Website details. A request must not contain both a Site and an App object." }, "InventoryIdentifier": { "type": "string", "example": "nytimes.com", "description": "The inventory ID field is an alternative to site.domain and app.storeId. This field can accept either a domain or app ID. When channel is not specified, we will use inventoryId to make an informed guess." }, "StoreId": { "type": "string", "example": "com.nytimes.android", "description": "A platform-specific application identifier intended to be unique to the app and independent of the exchange. On Android, this should be a bundle or package name (e.g., com.foo.mygame). On iOS, it is typically a numeric ID." }, "DateInput": { "type": "string", "description": "Dates must be in the past (i.e. prior to today). Dates should be in the UTC timezone in one of the following formats: YYYY-MM-DD, YYYYMMDD, or YYYY/MM/DD", "example": "2023-03-01" }, "CountryInput": { "type": "string", "description": "This is the country ISO 3166-2 alpha-2 code. e.g. US", "example": "US" }, "RegionInput": { "type": "string", "description": "The 2 or 3 letter region code - only supported for Canada, US, and Australia", "example": "CA" }, "AppInput": { "type": "object", "example": { "storeId": "com.nytimes.android" }, "required": [ "storeId" ], "properties": { "storeId": { "$ref": "#/components/schemas/StoreId" } }, "description": "App details. A request must not contain both a Site and an App object." }, "NetworkInput": { "type": "string", "enum": [ "fixed", "mobile" ], "example": "fixed", "description": "The networking connection used by the end user's device." }, "DeviceTypeInput": { "type": "string", "enum": [ "phone", "tablet", "pc", "tv", "smart-speaker" ], "example": "pc", "description": "\"The consumer’s device: phone, tablet, pc, tv or smart-speaker. If not provided, we’ll infer the device type from the the channel or the device field. smart-speaker is only allowed for digital-audio channel.\"" }, "SellerInput": { "type": "string", "example": "Xandr", "description": "Name of the seller entity that sold the media" }, "VenueCategory": { "type": "string", "example": "transit.airports.arrival", "description": "The inventory venue category. A venue category describes an environment and the audience that may be found there. Applicable only for DOOH properties. The full list of supported values is available on the [OpenOOH venue taxonomy page](https://github.com/openooh/venue-taxonomy/blob/main/specification-1.0.md)" }, "Plays": { "type": "integer", "example": 10, "description": "How many times an ad was shown. Applicable only for DOOH properties" }, "PlayDuration": { "type": "integer", "example": 10, "description": "How long an ad was on screen. Applicable only for DOOH properties" }, "MediaOwner": { "type": "string", "description": "The media owner that owns the screen inventory. Applicable only for DOOH properties" }, "Channel": { "type": "string", "enum": [ "display-app", "display-web", "streaming-video", "social", "digital-audio", "dooh" ], "example": "display-web", "description": "display-web: Display ads, including outstream video, on a website display-app: Display ads, including outstream video, on a mobile app. Excludes streaming and social apps streaming-video: Streaming video including CTV and YouTube. Includes in app or browser based streaming. Currently in a closed beta. digital-audio: Digital audio ads, including podcasts and streaming music. Currently in a closed beta. social: Social media ads, including Facebook, Instagram, Twitter, and Snapchat. Currently in a closed beta. dooh: Digital out of home ads, including billboards, transit, and airports." }, "DailyDeliveryRow": { "type": "object", "required": [ "date" ], "properties": { "identifier": { "type": "string", "example": "nytimes", "description": "An identifier for this row to be used in the response." }, "impressions": { "type": "integer", "example": 13821 }, "date": { "$ref": "#/components/schemas/DateInput" }, "site": { "$ref": "#/components/schemas/SiteInput" }, "app": { "$ref": "#/components/schemas/AppInput" }, "inventoryId": { "$ref": "#/components/schemas/InventoryIdentifier" }, "country": { "$ref": "#/components/schemas/CountryInput" }, "region": { "$ref": "#/components/schemas/RegionInput" }, "device": { "type": "string", "enum": [ "mobile", "desktop" ], "example": "desktop", "description": "Deprecated. Please provide deviceType and/or channel.", "deprecated": true }, "deviceType": { "$ref": "#/components/schemas/DeviceTypeInput" }, "channel": { "$ref": "#/components/schemas/Channel" }, "network": { "$ref": "#/components/schemas/NetworkInput" }, "creative": { "$ref": "#/components/schemas/Creative" }, "seller": { "$ref": "#/components/schemas/SellerInput" }, "buyingMethod": { "type": "string", "enum": [ "programmatic-open", "programmatic-pmp", "programmatic-guaranteed", "direct", "direct-takeover" ], "example": "programmatic-open", "description": "The method used to buy the impressions" }, "dealId": { "type": "string", "description": "Seller deal identifier", "example": "1" }, "venueCategory": { "$ref": "#/components/schemas/VenueCategory" }, "plays": { "$ref": "#/components/schemas/Plays" }, "playDuration": { "$ref": "#/components/schemas/PlayDuration" }, "mediaOwner": { "$ref": "#/components/schemas/MediaOwner" }, "gpid": { "type": "string", "description": "Global placement ID. Currently does not affect the output." } } }, "CalculateOutputRow": { "type": "object", "required": [ "domainCoverage" ], "properties": { "identifier": { "type": "string", "description": "the row identifier associated with these emissions based on the request input", "example": "1" }, "domainCoverage": { "$ref": "#/components/schemas/DomainCoverageEnum" }, "baseEmissions": { "type": "number", "deprecated": true, "format": "double", "example": 0.15, "description": "Deprecated: replaced with mediaDistributionEmissions. The Base Emissions figure is the total emissions of an impression, excluding the AdTech portion. This includes content creation and end-user device emissions. Content creation is the publisher's scope 1,2,3 emissions proportioned and attributed on an ad slot basis. End-User device emissions cover the power consumption (CPU, Networking, etc.) for rendering the publisher's content considering the user's location and power grid mix." }, "supplyPathEmissions": { "type": "number", "format": "double", "example": 0.15, "deprecated": true, "description": "Deprecated: replaced with adSelectionProcess. The supply path emissions figure is the total emissions associated with the supply path from the inventory ad slot and the complete graph of all advertising parties involved. This includes the Scope 1,2,3 emissions data of each party involved broken down into a per impression number." }, "creativeEmissions": { "type": "number", "deprecated": true, "format": "double", "example": 0.15, "description": "Deprecated: replaced with creativeDistributionEmissions and creativeConsumerDeviceEmissions. The creative emissions figure is the total emissions associated with the creative delivery. This includes the networking and CPU costs of delivering and rendering the creative." }, "creativeDistributionEmissions": { "type": "number", "format": "double", "example": 0.15, "description": "Emissions associated with the data transfer of the creative asset in grams of CO₂e." }, "creativeConsumerDeviceEmissions": { "type": "number", "format": "double", "example": 0.05, "description": "Emissions associated with the consumer device during view. Includes both emissions based on the use of the device and embodied emissions of the device. In grams of CO₂e." }, "mediaDistributionEmissions": { "type": "number", "format": "double", "example": 0.1, "description": "Media delivery including CMS; CDNs and hosting services; publishing overhead including employee and office expenses; data transfer. In grams of CO₂e." }, "adSelectionEmissions": { "type": "number", "format": "double", "example": 0.15, "description": "Ad tech including servers and cloud computing; analytics; network traffic; storage; data providers; and vendor overhead. In grams of CO₂e." }, "totalEmissions": { "type": "number", "format": "double", "example": 0.45, "description": "Total footprint of the campaign (sum of above) in grams of CO₂e." }, "matchedSeller": { "type": "string", "example": "Xandr", "description": "Internal name of the seller that was matched" }, "compensationProvider": { "type": "string", "example": "Carbon Direct", "description": "Provider used by the seller to compensate the emissions." }, "compensatedEmissions": { "type": "number", "format": "double", "example": 0.3, "description": "Emissions compensated by the compensationProvider in grams of CO₂e." }, "error": { "$ref": "#/components/schemas/Error" }, "matchedProperty": { "$ref": "#/components/schemas/Property" }, "supplyDirectness": { "deprecated": true, "type": "integer", "example": 3, "description": "Maximum depth of ad selection path to the seller based on buying method [Programmatic Insights customers only]" }, "consumerDeviceEmissions": { "type": "number", "format": "double", "example": 0.05, "description": "Consumer device emissions during consumption in grams of CO₂e." }, "inventoryClassification": { "type": "string", "enum": [ "MASKED", "AD_SERVING" ], "example": "MASKED", "description": "Classification of the inventory within the given property. When populated, ad selection emissions are populated using benchmarked data based on the input country and channel." }, "gmpEligible": { "type": "boolean", "example": true, "deprecated": true, "description": "Impressions are GMP eligible if the gCO₂e ad selection emissions per impression is lower than benchmark emissions data for the associated country and channel. If benchmarks are unavailable for a specific country then worldwide benchmarks will be used. [GMP sellers only]" }, "climateRisk": { "type": "boolean", "example": true, "description": "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 [GMP sellers only]" }, "matchedChannel": { "$ref": "#/components/schemas/Channel" }, "supplyGraph": { "$ref": "#/components/schemas/SupplyGraph" }, "processedImpressions": { "type": "integer", "example": 100, "description": "Number of impressions that were processed for this row. For DOOH channel this is derived from plays if impressions are not provided. For all other channels and cases this is equal to the input impressions." }, "matchedVenueCategory": { "$ref": "#/components/schemas/VenueCategory" }, "matchedMediaOwner": { "$ref": "#/components/schemas/MediaOwner" } } }, "SupplyGraph": { "type": "object", "required": [ "logical", "technical" ], "properties": { "totalCount": { "type": "integer", "example": 8, "description": "Number of times matched seller appears in supply chain emissions graph, or the count of all property ads txt nodes" }, "logical": { "$ref": "#/components/schemas/LogicalSupplyGraph" }, "technical": { "$ref": "#/components/schemas/TechnicalSupplyGraph" } }, "description": "Ad selection graph seller depth information. [Programmatic Insights customers only]" }, "LogicalSupplyGraph": { "type": "object", "properties": { "minDepth": { "type": "integer", "example": 1, "description": "Minimum depth of ad selection path to the matched seller OR the maximum depth of all property ads txt nodes Based on the minimum depth, buying method and seller type." }, "maxDepth": { "type": "integer", "example": 5, "description": "Maximum depth of ad selection path to the matched seller OR the maximum depth of all property ads txt nodes Based on the maximum depth, buying method and seller type." }, "averageDepth": { "type": "number", "format": "double", "example": 3, "description": "Average depth of ad selection path to the matched seller OR the maximum depth of all property ads txt nodes Based on the average depth, buying method and seller type." } }, "description": "Logical information calculates depth based on the full ad selection graph." }, "TechnicalSupplyGraph": { "type": "object", "properties": { "minDepth": { "type": "integer", "example": 1, "description": "Minimum depth of ad selection path to the matched seller OR the maximum depth of all property ads txt nodes Based on the minimum depth, buying method and seller type." }, "maxDepth": { "type": "integer", "example": 5, "description": "Maximum depth of ad selection path to the matched seller OR the maximum depth of all property ads txt nodes Based on the maximum depth, buying method and seller type." }, "averageDepth": { "type": "number", "format": "double", "example": 3, "description": "Average depth of ad selection path to the matched seller OR the maximum depth of all property ads txt nodes Based on the average depth, buying method and seller type." } }, "description": "Technical information ignores ad selection graph passthrough nodes. The calculated depth only uses nodes that very directly involved in the ad selection process." }, "DailyCalculateRequestBody": { "type": "object", "required": [ "rows" ], "properties": { "rows": { "type": "array", "items": { "$ref": "#/components/schemas/DailyDeliveryRow" } } } }, "DailyCalculateOutputSummary": { "type": "object", "required": [ "totalEmissions", "rowsModeled", "rowsSkipped", "impressionsModeled", "impressionsSkipped" ], "properties": { "requestID": { "type": "string", "description": "Request ID auto generated for this request. This can be used to help our support tem debug your requests." }, "totalEmissions": { "type": "number", "format": "double", "example": 2823.9, "description": "The emissions from the submitted campaign excluding consumer device emissions and creative consumer device emissions, in grams CO₂-equivalent" }, "rowsModeled": { "type": "integer", "example": 8132, "description": "Rows successfully modeled (all fields valid, domain not masked, invalid, or missing)" }, "rowsSkipped": { "type": "integer", "example": 48, "description": "Rows not successfully modeled (invalid fields or the domain was masked, invalid, or missing)" }, "impressionsModeled": { "type": "integer", "example": 2832821, "description": "Impressions successfully modeled (all fields valid, domain not masked, invalid, or missing)" }, "impressionsSkipped": { "type": "integer", "example": 282111, "description": "Impressions not successfully modeled (invalid fields or the domain was masked, invalid, or missing)" }, "matchedSellersPercentage": { "type": "number", "format": "double", "example": 78.9, "description": "Percentage of impressions with seller provided that were matched" }, "gmpEligiblePercentage": { "type": "number", "format": "double", "example": 33.9, "deprecated": true, "description": "The percentage of impressions that are gmp eligible [GMP sellers only]" }, "climateRiskPercentage": { "type": "number", "format": "double", "example": 33.9, "description": "The percentage of impressions that are a climate risk [GMP sellers only]" }, "averageSupplyDirectness": { "deprecated": true, "type": "number", "format": "double", "example": 3.1, "description": "A weighted average of modeled rows supply directness by impressions [Programmatic Insights customers only]" }, "totalCompensatedEmissions": { "type": "number", "format": "double", "example": 146.1, "description": "Total compensated emissions in grams of CO₂e" }, "totalAdSelectionEmissions": { "type": "number", "format": "double", "example": 146.1, "description": "Total ad selection emissions in grams of CO₂e" }, "totalMediaDistributionEmissions": { "type": "number", "format": "double", "example": 146.1, "description": "Total media distribution emissions in grams of CO₂e" }, "totalConsumerDeviceEmissions": { "type": "number", "format": "double", "example": 146.1, "description": "Total consumer device emissions in grams of CO₂e" }, "totalCreativeDistributionEmissions": { "type": "number", "format": "double", "example": 146.1, "description": "Total creative distribution emissions in grams of CO₂e" }, "totalCreativeConsumerDeviceEmissions": { "type": "number", "format": "double", "example": 146.1, "description": "Total creative consumer device emissions in grams of CO₂e" }, "rows": { "description": "Only included if the 'include rows' parameter is true.", "type": "array", "items": { "$ref": "#/components/schemas/CalculateOutputRow" } } } }, "Error": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } } }, "responses": { "ErrorResponse": { "description": "unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "x-readme": { "explorer-enabled": true, "proxy-enabled": true } } ```