Migrate from v2 to v3

AI-generated Key Takeaways

• Display & Video 360 API v3 has sunset and users should now use v4.

• Migrating from v2 to v3 requires updating API calls to use new v3 endpoints and accounting for breaking changes.

• Breaking changes in v3 include updates to YouTube resource retrieval and targeting, required billing configurations for advertisers, changes to optimized targeting control, and updates to insertion order KPI fields.

• V3 introduces additional changes such as proximity location list management and the ability to build rule-based custom bidding algorithms.

Display & Video 360 API v3 has sunset. Use v4 instead.

Last update: 2023-10-31

Migrate your application

Migrating from v2 to v3 requires updating your endpoint URLs to call v3 and updating your application to account for breaking changes.

Update your API calls from v2 to v3

To use v3 instead of v2, you need to update your requests to use new v3 endpoints.

For example, to call the advertisers.get method with v2, you would use the following URL:

GET https://displayvideo.googleapis.com/v2/advertisers/advertiserId

For v3, update the URL to the following:

GET https://displayvideo.googleapis.com/v3/advertisers/advertiserId

If you are using a client library to make requests to the API, use the most recent version of the client library and update your configuration to use v3.

Make required changes

We're introducing a number of breaking changes in v3. Review the following instructions and make the required changes relevant to your existing use of the Display & Video 360 API.

Update calls retrieving YouTube resources and their related targeting

• YoutubeAdGroup and YoutubeAdGroupAd resources have been replaced by AdGroup and AdGroupAd resources. These new resources provide nearly identical information as the v2 resources but may use updated field names or enum types. In your integration, replace your uses of YoutubeAdGroup or YoutubeAdGroupAd resources with AdGroup and AdGroupAd resources and update calls to the following v2 services to the corresponding v3 service:
  • advertisers.youtubeAdGroupAds to advertisers.adGroupAds
  • advertisers.youtubeAdGroups to advertisers.adGroups
  • advertisers.youtubeAdGroups.targetingTypes.assignedTargetingOptions to advertisers.adGroups.targetingTypes.assignedTargetingOptions
• References to YoutubeAndPartnersBiddingStrategy objects have been moved to a new youtubeAndPartnersBid field within the general BiddingStrategy object. The biddingStrategy field has been removed from the YoutubeAndPartnersSettingsobject. Update your integration to retrieve the bidding strategy for YouTube line items or ad groups from the BiddingStrategy object in the bidStrategy field in the LineItem or AdGroup resource.
• The thirdPartyMeasurementSettings field has been renamed to thirdPartyMeasurementConfigs in the YoutubeAndPartnersSettings object and the YoutubeAndPartnersThirdPartyMeasurementSettings object has been renamed to ThirdPartyMeasurementConfigs. Update your integration to retrieve third-party measurement configuration information using the new field and object.

Include required billing configurations when creating advertisers

billingConfig is now a required field in the Advertiser resource. Update your advertisers.create requests to verify that this field is set. The default billing information can be retrieved for the parent partner through the new Partner resource billingConfig field.

Use new field to control optimized targeting

A new boolean enableOptimizedTargeting field has replaced the targetingExpansionLevel field in the TargetingExpansionConfig object.

Update insertion order integration to use new KPI field

A new kpi field has replaced the performanceGoal field in the InsertionOrder resource. This new field uses a Kpi object in place of the PerformanceGoal object and uses new fields and enums.

Remove references to deprecated services and fields

Various entities have been removed in v3 to align with past feature deprecations:

• The advertisers.manualTriggers service has been removed as manual triggers have been deprecated.
• The billableOutcome field has been removed from the InsertionOrder resource as outcome based buying has been deprecated.

Additional changes

In addition to the breaking changes listed above, v3 also introduces new features.

Features added to v3 after the initial launch can be found in our release notes.

Proximity location list management

In v3 you can fully manage proximity location lists, allowing you to use the advertisers.locationLists.assignedLocations service to create and delete locations assigned to TARGETING_LOCATION_TYPE_PROXIMITY LocationList resources. Locations are identified using the ID of TARGETING_TYPE_POI TargetingOption resources. These can be retrieved using targetingTypes.targetingOptions.search.

Ability to build rule-based custom bidding algorithms

In v3, you can build and retrieve rule-based custom bidding algorithms using the customBiddingAlgorithms, media, customBiddingAlgorithms.rules services.

This feature is in beta and only available to allowlisted partners. If your partner is not allowlisted, your request will return an error.