Migrating to Authorized Buyers' Real-time Bidding API

Enable the API

Similar to the Ad Exchange Buyer and Ad Exchange Buyer II APIs, you will need to enable the Real-time Bidding API before you can start working with it. You can do so with the following steps:

  1. Go to the Google API Console Enabled APIs page, and select the project you use for accessing the Ad Exchange Buyer or Ad Exchange Buyer II APIs.
  2. Click the + ENABLE APIS AND SERVICES link.
  3. In the search box, type "Real-time Bidding API", and press Enter.
  4. In the search results, select Real-time Bidding API.
  5. Click the ENABLE button to enable the Real-time Bidding API.
  6. You should now be able to access the Real-time Bidding API with credentials created under this project.

Update your OAuth 2.0 credentials

Existing OAuth 2.0 workflows configured with the API scope for the existing Ad Exchange Buyer APIs will need to be adjusted for use with the Real-time Bidding API, which has the following new scope:

https://www.googleapis.com/auth/realtime-bidding

It is recommended that the Service Account OAuth 2.0 flow is used to access the API. All supported OAuth 2.0 flows will need to specify the new API scope when requesting a token from Google in order for the tokens to have permission to access the Real-time Bidding API.

Mapping Ad Exchange Buyer API resources to the Real-time Bidding API

Bidder and Buyer-level resources

The Real-time Bidding API has been restructured to better align with Google API design practices and more clearly define the API calls available to bidders and the buyers that they bid on behalf of. All resources will exist either under the bidders or buyers root-level resources.

In general, API calls made under bidders will involve configuration of real-time bidding settings, or viewing results for a particular resource across all buyer accounts associated with the bidder—as a concrete example, the bidders.creatives.list method could return creatives for all buyer accounts associated with the bidder. In contrast, API calls made under buyers will be on behalf of an individual buyer—the buyers.creatives.list method would return all creatives for an individual buyer.

Resource names

Similar to the Ad Exchange Buyer II API, this API will use resource names as unique identifiers. The resource ID specified for a bidder or buyer will be their Authorized Buyers account ID.

Creatives

Both the Ad Exchange Buyer and Real-time Bidding APIs have a creatives resource that is used for similar purposes. The tables below describe the mapping of fields and methods between both.

Resource methods

Ad Exchange Buyer API method name Real-time Bidding API equivalent
addDeal N/A: A creative will be associated with a deal when it is specified in a bid response for a deal.
get buyers.creatives.get
insert buyers.creatives.create
list bidders.creatives.list or buyers.creatives.list
listDeals N/A: Deals are now listed in the Creative.dealIds[] field.
removeDeal N/A

Resource fields

Ad Exchange Buyer API field name Real-time Bidding API equivalent
accountId Creative.accountId
buyerCreativeId Creative.creativeId
creativeStatusIdentityType N/A: This field has been sunset.
agencyId Creative.agencyId
version Creative.version
apiUploadTimestamp Creative.apiUpdateTime
HTMLSnippet Creative.html.snippet
nativeAd Creative.native
videoURL Creative.video.videoUrl
videoVastXML Creative.video.videoVastXml
clickThroughUrl Creative.declaredClickThroughUrls
adChoicesDestinationUrl Creative.adChoicesDestinationUrl
impressionTrackingUrl Creative.impressionTrackingUrls
vendorType Creative.declaredVendorIds and Creative.creativeServingDecision.detectedVendorIds
attribute Creative.declaredAttributes
width Creative.html.width
height Creative.html.height
advertiserName Creative.advertiserName
dealsStatus Creative.creativeServingDecision.dealsPolicyCompliance
openAuctionStatus Creative.creativeServingDecision.networkPolicyCompliance
servingRestrictions Creative.creativeServingDecision
advertiserId Creative.creativeServingDecision.detectedAdvertisers.advertiserId
sensitiveCategories Creative.creativeServingDecision.detectedSensitiveCategories
restrictedCategories Creative.restrictedCategories
productCategories Creative.creativeServingDecision.detectedProductCategories
languages Creative.creativeServingDecision.detectedLanguages
detectedDomains Creative.creativeServingDecision.detectedDomains
corrections N/A: Detected fields now describe corrections.
filteringReasons N/A: This should be obtained from either the RTB Breakout UI, or RTB Troubleshooting API.

PretargetingConfig

The Ad Exchange Buyer API uses a pretargetingConfig resource to manage pretargeting configurations, whereas the Real-time Bidding API uses a resource named pretargetingConfigs. The tables below describe the mapping of fields and methods between both.

Resource methods

Ad Exchange Buyer API method name Real-time Bidding API equivalent
delete bidders.pretargetingConfigs.delete
get bidders.pretargetingConfigs.get
insert bidders.pretargetingConfigs.create
list bidders.pretargetingConfigs.list
patch bidders.pretargetingConfigs.patch
update bidders.pretargetingConfigs.patch

Resource fields

Ad Exchange Buyer API field name Real-time Bidding API equivalent
configId PretargetingConfig.name
billingId PretargetingConfig.billingId
configName PretargetingConfig.displayName
isActive PretargetingConfig.state
creativeType PretargetingConfig.includedFormats
dimensions PretargetingConfig.includedCreativeDimensions
languages PretargetingConfig.includedLanguages
geoCriteriaIds PretargetingConfig.geoTargeting
excludedGeoCriteriaIds PretargetingConfig.geoTargeting
supportedCreativeAttributes PretargetingConfig.interstitialTargeting and PretargetingConfig.allowedUserTargetingModes. All other targetable creative attributes have been sunset.
vendorTypes N/A
placements PretargetingConfig.appTargeting, PretargetingConfig.includedEnvironments, and PretargetingConfig.webTargeting.
excludedPlacements N/A
verticals PretargetingConfig.verticalTargeting
excludedVerticals PretargetingConfig.verticalTargeting
userLists PretargetingConfig.userListTargeting
excludedUserLists PretargetingConfig.userListTargeting
excludedContentLabels PretargetingConfig.excludedContentLabelIds
platforms PretargetingConfig.includedPlatforms
mobileCarriers N/A
mobileDevices N/A
mobileOperatingSystemVersions PretargetingConfig.includedMobileOperatingSystemIds
videoPlayerSizes N/A
userIdentifierDataRequired PretargetingConfig.includedUserIdTypes
minimumViewabilityDecile PretargetingConfig.minimumViewabilityDecile
maximumQps PretargetingConfig.maximumQps

Accounts and BillingInfo

The Ad Exchange Buyer API doesn't distinguish between bidder and buyer accounts, using an Accounts resource to represent both. Additionally, it uses a separate BillingInfo resource to represent the billing IDs associated with a given buyer. The Real-time Bidding API has restructured these to remove ambiguity and further simplify the API with the bidders, bidders.endpoints, and buyers resources. The tables below describe the mapping of fields and methods between both APIs.

Resource methods

Ad Exchange Buyer API method name Real-time Bidding API equivalent
accounts.get bidders.get, bidders.endpoints.get, and buyers.get.
accounts.list bidders.list, bidders.endpoints.list, and buyers.list.
accounts.patch bidders.endpoints.patch and bidders.endpoints.setEndpointUrl
accounts.update bidders.endpoints.patch and bidders.endpoints.setEndpointUrl
billingInfo.get buyers.get
billingInfo.list buyers.list

Resource fields

Ad Exchange Buyer API field name Real-time Bidding API equivalent
accounts.id bidders.name or buyers.name
accounts.cookieMatchingUrl bidders.cookieMatchingUrl
accounts.cookieMatchingNid bidders.cookieMatchingNetworkId
accounts.bidderLocation.url bidders.endpoints.url
accounts.bidderLocation.maximumQps bidders.endpoints.maximumQps
accounts.bidderLocation.region bidders.endpoints.tradingLocation
accounts.bidderLocation.bidProtocol bidders.endpoints.bidProtocol
accounts.maximumTotalQps N/A: This is no longer exposed in the API.
accounts.maximumActiveCreatives buyers.maximumActiveCreativeCount
accounts.numberActiveCreatives buyers.activeCreativeCount
accounts.applyPretargetingToNonGuaranteedDeals buyers.bypassNonguaranteedDealsPretargeting: This signal has been inverted.
billingInfo.billingId buyers.billingIds