- Resource: Proposal
- Deal
- PrivateData
- MarketplaceTargeting
- CriteriaTargeting
- InventorySizeTargeting
- AdSize
- SizeType
- TechnologyTargeting
- OperatingSystemTargeting
- PlacementTargeting
- UrlTargeting
- MobileApplicationTargeting
- FirstPartyMobileApplicationTargeting
- VideoTargeting
- PositionType
- CreativeRestrictions
- CreativeFormat
- CreativeSpecification
- SkippableAdType
- CreativePreApprovalPolicy
- CreativeSafeFrameCompatibility
- DealServingMetadata
- DealPauseStatus
- BuyerSellerRole
- ProgrammaticCreativeSource
- DeliveryControl
- DeliveryRateType
- FrequencyCap
- TimeUnitType
- CreativeBlockingLevel
- ProposalState
- Note
- Methods
Resource: Proposal
Represents a proposal in the Marketplace. A proposal is the unit of negotiation between a seller and a buyer and contains deals which are served.
Note: You can't update, create, or otherwise modify Private Auction deals through the API.
Fields are updatable unless noted otherwise.
JSON representation | |
---|---|
{ "proposalId": string, "updateTime": string, "proposalRevision": string, "deals": [ { object ( |
Fields | |
---|---|
proposalId |
Output only. The unique ID of the proposal. |
updateTime |
Output only. The time when the proposal was last revised. A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: |
proposalRevision |
Output only. The revision number for the proposal. Each update to the proposal or the deal causes the proposal revision number to auto-increment. The buyer keeps track of the last revision number they know of and pass it in when making an update. If the head revision number on the server has since incremented, then an ABORTED error is returned during the update operation to let the buyer know that a subsequent update was made. |
deals[] |
The deals associated with this proposal. For Private Auction proposals (whose deals have NonGuaranteedAuctionTerms), there will only be one deal. |
originatorRole |
Output only. Indicates whether the buyer/seller created the proposal. |
seller |
Reference to the seller on the proposal. Note: This field may be set only when creating the resource. Modifying this field while updating the resource will result in an error. |
buyer |
Reference to the buyer on the proposal. Note: This field may be set only when creating the resource. Modifying this field while updating the resource will result in an error. |
billedBuyer |
Output only. Reference to the buyer that will get billed for this proposal. |
displayName |
The name for the proposal. |
proposalState |
Output only. The current state of the proposal. |
isRenegotiating |
Output only. True if the proposal is being renegotiated. |
buyerPrivateData |
Private data for buyer. (hidden from seller). |
sellerContacts[] |
Output only. Contact information for the seller. |
buyerContacts[] |
Contact information for the buyer. |
privateAuctionId |
Output only. Private auction ID if this proposal is a private auction proposal. |
isSetupComplete |
Output only. True, if the buyside inventory setup is complete for this proposal. |
lastUpdaterOrCommentorRole |
Output only. The role of the last user that either updated the proposal or left a comment. |
notes[] |
Output only. The notes associated with this proposal. |
termsAndConditions |
Output only. The terms and conditions set by the publisher for this proposal. |
Deal
A deal represents a segment of inventory for displaying ads on. A proposal can contain multiple deals. A deal contains the terms and targeting information that is used for serving.
JSON representation | |
---|---|
{ "dealId": string, "proposalId": string, "createTime": string, "updateTime": string, "createProductId": string, "createProductRevision": string, "displayName": string, "buyerPrivateData": { object ( |
Fields | |
---|---|
dealId |
Output only. A unique deal ID for the deal (server-assigned). |
proposalId |
Output only. ID of the proposal that this deal is part of. |
createTime |
Output only. The time of the deal creation. A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: |
updateTime |
Output only. The time when the deal was last updated. A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: |
createProductId |
The product ID from which this deal was created. Note: This field may be set only when creating the resource. Modifying this field while updating the resource will result in an error. |
createProductRevision |
Optional. Revision number of the product that the deal was created from. If present on create, and the server Note: This field may be set only when creating the resource. Modifying this field while updating the resource will result in an error. |
displayName |
The name of the deal. |
buyerPrivateData |
Buyer private data (hidden from seller). |
dealTerms |
The negotiable terms of the deal. |
webPropertyCode |
The web property code for the seller copied over from the product. |
sellerContacts[] |
Output only. Seller contact information for the deal. |
availableStartTime |
Optional. Proposed flight start time of the deal. This will generally be stored in the granularity of one second since deal serving starts at seconds boundary. Any time specified with more granularity (for example, in milliseconds) will be truncated towards the start of time in seconds. A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: |
availableEndTime |
Proposed flight end time of the deal. This will generally be stored in a granularity of a second. A value is not required for Private Auction deals or Preferred Deals. A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: |
description |
Description for the deal terms. |
targetingCriterion[] |
The shared targeting visible to buyers and sellers. Each shared targeting entity is AND'd together. |
targeting |
Output only. Specifies the subset of inventory targeted by the deal. |
creativeRestrictions |
Output only. Restricitions about the creatives associated with the deal (for example, size) This is available for Programmatic Guaranteed/Preferred Deals in Ad Manager. |
externalDealId |
Output only. The external deal ID assigned to this deal once the deal is finalized. This is the deal ID that shows up in serving/reporting etc. |
syndicationProduct |
The syndication product associated with the deal. Note: This field may be set only when creating the resource. Modifying this field while updating the resource will result in an error. |
creativePreApprovalPolicy |
Output only. Specifies the creative pre-approval policy. |
creativeSafeFrameCompatibility |
Output only. Specifies whether the creative is safeFrame compatible. |
dealServingMetadata |
Output only. Metadata about the serving status of this deal. |
programmaticCreativeSource |
Output only. Specifies the creative source for programmatic deals. PUBLISHER means creative is provided by seller and ADVERTISER means creative is provided by buyer. |
deliveryControl |
The set of fields around delivery control that are interesting for a buyer to see but are non-negotiable. These are set by the publisher. |
isSetupComplete |
Output only. True, if the buyside inventory setup is complete for this deal. |
PrivateData
Buyers are allowed to store certain types of private data in a proposal/deal.
JSON representation | |
---|---|
{ "referenceId": string } |
Fields | |
---|---|
referenceId |
A buyer or seller specified reference ID. This can be queried in the list operations (max-length: 1024 unicode code units). |
MarketplaceTargeting
Targeting represents different criteria that can be used by advertisers to target ad inventory. For example, they can choose to target ad requests only if the user is in the US. Multiple types of targeting are always applied as a logical AND, unless noted otherwise.
JSON representation | |
---|---|
{ "geoTargeting": { object ( |
Fields | |
---|---|
geoTargeting |
Geo criteria IDs to be included/excluded. |
inventorySizeTargeting |
Inventory sizes to be included/excluded. |
technologyTargeting |
Technology targeting information, for example, operating system, device category. |
placementTargeting |
Placement targeting information, for example, URL, mobile applications. |
videoTargeting |
Video targeting information. |
CriteriaTargeting
Generic targeting used for targeting dimensions that contains a list of included and excluded numeric IDs.
JSON representation | |
---|---|
{ "targetedCriteriaIds": [ string ], "excludedCriteriaIds": [ string ] } |
Fields | |
---|---|
targetedCriteriaIds[] |
A list of numeric IDs to be included. |
excludedCriteriaIds[] |
A list of numeric IDs to be excluded. |
InventorySizeTargeting
Represents the size of an ad unit that can be targeted on an ad request. It only applies to Private Auction, AdX Preferred Deals and Auction Packages. This targeting does not apply to Programmatic Guaranteed and Preferred Deals in Ad Manager.
JSON representation | |
---|---|
{ "targetedInventorySizes": [ { object ( |
Fields | |
---|---|
targetedInventorySizes[] |
A list of inventory sizes to be included. |
excludedInventorySizes[] |
A list of inventory sizes to be excluded. |
AdSize
Represents size of a single ad slot, or a creative.
JSON representation | |
---|---|
{
"width": string,
"height": string,
"sizeType": enum ( |
Fields | |
---|---|
width |
The width of the ad slot in pixels. This field will be present only when size type is |
height |
The height of the ad slot in pixels. This field will be present only when size type is |
sizeType |
The size type of the ad slot. |
SizeType
Represents different types of ad slot/creative sizing.
Enums | |
---|---|
SIZE_TYPE_UNSPECIFIED |
A placeholder for an undefined size type. |
PIXEL |
Ad slot with size specified by height and width in pixels. |
INTERSTITIAL |
Special size to describe an interstitial ad slot. |
NATIVE |
Native (mobile) ads rendered by the publisher. |
FLUID |
Fluid size (for example, responsive size) can be resized automatically with the change of outside environment. |
TechnologyTargeting
Represents targeting about various types of technology.
JSON representation | |
---|---|
{ "deviceCategoryTargeting": { object ( |
Fields | |
---|---|
deviceCategoryTargeting |
IDs of device categories to be included/excluded. |
deviceCapabilityTargeting |
IDs of device capabilities to be included/excluded. |
operatingSystemTargeting |
Operating system related targeting information. |
OperatingSystemTargeting
Represents targeting information for operating systems.
JSON representation | |
---|---|
{ "operatingSystemCriteria": { object ( |
Fields | |
---|---|
operatingSystemCriteria |
IDs of operating systems to be included/excluded. |
operatingSystemVersionCriteria |
IDs of operating system versions to be included/excluded. |
PlacementTargeting
Represents targeting about where the ads can appear, for example, certain sites or mobile applications. Different placement targeting types will be logically OR'ed.
JSON representation | |
---|---|
{ "urlTargeting": { object ( |
Fields | |
---|---|
urlTargeting |
URLs to be included/excluded. |
mobileApplicationTargeting |
Mobile application targeting information in a deal. This doesn't apply to Auction Packages. |
UrlTargeting
Represents a list of targeted and excluded URLs (for example, google.com). For Private Auction and AdX Preferred Deals, URLs are either included or excluded. For Programmatic Guaranteed and Preferred Deals, this doesn't apply.
JSON representation | |
---|---|
{ "targetedUrls": [ string ], "excludedUrls": [ string ] } |
Fields | |
---|---|
targetedUrls[] |
A list of URLs to be included. |
excludedUrls[] |
A list of URLs to be excluded. |
MobileApplicationTargeting
Mobile application targeting settings.
JSON representation | |
---|---|
{
"firstPartyTargeting": {
object ( |
Fields | |
---|---|
firstPartyTargeting |
Publisher owned apps to be targeted or excluded by the publisher to display the ads in. |
FirstPartyMobileApplicationTargeting
Represents a list of targeted and excluded mobile application IDs that publishers own. Mobile application IDs are from App Store and Google Play Store. Android App ID, for example, com.google.android.apps.maps, can be found in Google Play Store URL. iOS App ID (which is a number) can be found at the end of iTunes store URL. First party mobile applications is either included or excluded.
JSON representation | |
---|---|
{ "targetedAppIds": [ string ], "excludedAppIds": [ string ] } |
Fields | |
---|---|
targetedAppIds[] |
A list of application IDs to be included. |
excludedAppIds[] |
A list of application IDs to be excluded. |
VideoTargeting
Represents targeting information about video.
JSON representation | |
---|---|
{ "targetedPositionTypes": [ enum ( |
Fields | |
---|---|
targetedPositionTypes[] |
A list of video positions to be included. When the included list is present, the excluded list must be empty. When the excluded list is present, the included list must be empty. |
excludedPositionTypes[] |
A list of video positions to be excluded. Position types can either be included or excluded (XOR). |
PositionType
Represents a targetable position within a video.
Enums | |
---|---|
POSITION_TYPE_UNSPECIFIED |
A placeholder for an undefined video position. |
PREROLL |
Ad is played before the video. |
MIDROLL |
Ad is played during the video. |
POSTROLL |
Ad is played after the video. |
CreativeRestrictions
Represents creative restrictions associated to Programmatic Guaranteed/ Preferred Deal in Ad Manager. This doesn't apply to Private Auction and AdX Preferred Deals.
JSON representation | |
---|---|
{ "creativeFormat": enum ( |
Fields | |
---|---|
creativeFormat |
The format of the environment that the creatives will be displayed in. |
creativeSpecifications[] |
|
skippableAdType |
Skippable video ads allow viewers to skip ads after 5 seconds. |
CreativeFormat
Represents the format of a creative.
Enums | |
---|---|
CREATIVE_FORMAT_UNSPECIFIED |
A placeholder for an undefined creative format. |
DISPLAY |
A creative that will be displayed in environments such as a browser. |
VIDEO |
A video creative that will be displayed in environments such as a video player. |
CreativeSpecification
Represents information for a creative that is associated with a Programmatic Guaranteed/Preferred Deal in Ad Manager.
JSON representation | |
---|---|
{ "creativeSize": { object ( |
Fields | |
---|---|
creativeSize |
The size of the creative. |
creativeCompanionSizes[] |
Companion sizes may be filled in only when this is a video creative. |
SkippableAdType
The type of skippable ad for video creatives.
Enums | |
---|---|
SKIPPABLE_AD_TYPE_UNSPECIFIED |
A placeholder for an undefined skippable ad type. |
SKIPPABLE |
This video ad can be skipped after 5 seconds. |
INSTREAM_SELECT |
This video ad can be skipped after 5 seconds, and is counted as engaged view after 30 seconds. The creative is hosted on YouTube only, and viewcount of the YouTube video increments after the engaged view. |
NOT_SKIPPABLE |
This video ad is not skippable. |
CreativePreApprovalPolicy
Specifies the creative pre-approval policy requirements.
Enums | |
---|---|
CREATIVE_PRE_APPROVAL_POLICY_UNSPECIFIED |
A placeholder for an undefined creative pre-approval policy. |
SELLER_PRE_APPROVAL_REQUIRED |
The seller needs to approve each creative before it can serve. |
SELLER_PRE_APPROVAL_NOT_REQUIRED |
The seller does not need to approve each creative before it can serve. |
CreativeSafeFrameCompatibility
Specifies whether the creative needs to be safe-frame compatible or not.
Enums | |
---|---|
CREATIVE_SAFE_FRAME_COMPATIBILITY_UNSPECIFIED |
A placeholder for an undefined creative safe-frame compatibility. |
COMPATIBLE |
The creatives need to be compatible with the safe frame option. |
INCOMPATIBLE |
The creatives can be incompatible with the safe frame option. |
DealServingMetadata
Message captures metadata about the serving status of a deal.
JSON representation | |
---|---|
{
"dealPauseStatus": {
object ( |
Fields | |
---|---|
dealPauseStatus |
Output only. Tracks which parties (if any) have paused a deal. |
DealPauseStatus
Tracks which parties (if any) have paused a deal. The deal is considered paused if either hasBuyerPaused or hasSellPaused is true.
JSON representation | |
---|---|
{
"hasBuyerPaused": boolean,
"hasSellerPaused": boolean,
"firstPausedBy": enum ( |
Fields | |
---|---|
hasBuyerPaused |
True, if the buyer has paused the deal unilaterally. |
hasSellerPaused |
True, if the seller has paused the deal unilaterally. |
firstPausedBy |
The role of the person who first paused this deal. |
buyerPauseReason |
The buyer's reason for pausing, if the buyer paused the deal. |
sellerPauseReason |
The seller's reason for pausing, if the seller paused the deal. |
BuyerSellerRole
Indicates which party performed a given operation.
Enums | |
---|---|
BUYER_SELLER_ROLE_UNSPECIFIED |
A placeholder for an undefined buyer/seller role. |
BUYER |
Specifies the role as buyer. |
SELLER |
Specifies the role as seller. |
ProgrammaticCreativeSource
Specifies the creative source for the programmatic deal.
Enums | |
---|---|
PROGRAMMATIC_CREATIVE_SOURCE_UNSPECIFIED |
A placeholder for an undefined programmatic creative source. |
ADVERTISER |
The advertiser provides the creatives. |
PUBLISHER |
The publisher provides the creatives to be served. |
DeliveryControl
Message contains details about how the deals will be paced.
JSON representation | |
---|---|
{ "deliveryRateType": enum ( |
Fields | |
---|---|
deliveryRateType |
Output only. Specifies how the impression delivery will be paced. |
frequencyCaps[] |
Output only. Specifies any frequency caps. |
creativeBlockingLevel |
Output only. Specified the creative blocking levels to be applied. |
DeliveryRateType
Specifies how the impression delivery will be paced.
Enums | |
---|---|
DELIVERY_RATE_TYPE_UNSPECIFIED |
A placeholder for an undefined delivery rate type. |
EVENLY |
Impressions are served uniformly over the life of the deal. |
FRONT_LOADED |
Impressions are served front-loaded. |
AS_FAST_AS_POSSIBLE |
Impressions are served as fast as possible. |
FrequencyCap
Frequency cap.
JSON representation | |
---|---|
{
"maxImpressions": integer,
"numTimeUnits": integer,
"timeUnitType": enum ( |
Fields | |
---|---|
maxImpressions |
The maximum number of impressions that can be served to a user within the specified time period. |
numTimeUnits |
The amount of time, in the units specified by timeUnitType. Defines the amount of time over which impressions per user are counted and capped. |
timeUnitType |
The time unit. Along with numTimeUnits defines the amount of time over which impressions per user are counted and capped. |
TimeUnitType
Specifies the time-unit type for delivery control.
Enums | |
---|---|
TIME_UNIT_TYPE_UNSPECIFIED |
A placeholder for an undefined time unit type. This just indicates the variable with this value hasn't been initialized. |
MINUTE |
Minute |
HOUR |
Hour |
DAY |
Day |
WEEK |
Week |
MONTH |
Month |
LIFETIME |
Lifetime |
POD |
Pod |
STREAM |
Stream |
CreativeBlockingLevel
Indicates which of the creative blocking rules are applied to bids on this deal.
Enums | |
---|---|
CREATIVE_BLOCKING_LEVEL_UNSPECIFIED |
A placeholder for an undefined creative blocking level. |
PUBLISHER_BLOCKING_RULES |
Publisher blocking rules will be applied. |
ADX_POLICY_BLOCKING_ONLY |
The Ad Exchange policy blocking rules will be applied. |
ProposalState
The state of the proposal.
Enums | |
---|---|
PROPOSAL_STATE_UNSPECIFIED |
A placeholder for an undefined proposal state. |
PROPOSED |
The proposal is under negotiation or renegotiation. |
BUYER_ACCEPTED |
The proposal has been accepted by the buyer. |
SELLER_ACCEPTED |
The proposal has been accepted by the seller. |
CANCELED |
The negotiations on the proposal were canceled and the proposal was never finalized. |
FINALIZED |
The proposal is finalized. During renegotiation, the proposal may not be in this state. |
Note
A proposal may be associated to several notes.
JSON representation | |
---|---|
{
"proposalRevision": string,
"noteId": string,
"createTime": string,
"creatorRole": enum ( |
Fields | |
---|---|
proposalRevision |
Output only. The revision number of the proposal when the note is created. |
noteId |
Output only. The unique ID for the note. |
createTime |
Output only. The timestamp for when this note was created. A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: |
creatorRole |
Output only. The role of the person (buyer/seller) creating the note. |
note |
The actual note to attach. (max-length: 1024 unicode code units) Note: This field may be set only when creating the resource. Modifying this field while updating the resource will result in an error. |
Methods |
|
---|---|
|
Mark the proposal as accepted at the given revision number. |
|
Create a new note and attach it to the proposal. |
|
Cancel an ongoing negotiation on a proposal. |
|
Update the given proposal to indicate that setup has been completed. |
|
Create the given proposal. |
|
Gets a proposal given its ID. |
|
List proposals. |
|
Update the given proposal to pause serving. |
|
Update the given proposal to resume serving. |
|
Update the given proposal at the client known revision number. |