Migrate from v1 to v2

AI-generated Key Takeaways

outlined_flag

• Migrating to v2 requires updating endpoint URLs and adjusting your application for breaking changes.

• Some targeting methods in v2 now use enum values instead of targeting option IDs.

• Several existing methods and fields have been replaced or removed in v2, particularly within the advertisers.lineItems and customBiddingAlgorithms services.

• V2 introduces read-only access to YouTube line items and new methods for bulk operations and duplication within the advertisers.lineItems service to improve performance.

• Partial write access is now available for a subset of targeting settings on Insertion Order resources in v2.

Last update: 2022-12-06

Migrate your application

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

Update your API calls from v1 to v2

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

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

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

For v2, update the URL to the following:

GET https://displayvideo.googleapis.com/v2/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 v2.

Make required changes

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

Update calls to targeting methods

• Some targeting types are now assigned using enum values instead of targeting option IDs. For example, tablet devices are now targeted directly with the DEVICE_TYPE_TABLET DeviceType enum, rather than the targeting option ID from the targetingTypes.targetingOptions service. String versions of these enums are represented in the new assignedTargetingOptionIdAlias field in these AssignedTargetingOption resources and can be used when retrieving or deleting existing targeting. The assignedTargetingOptionId value of these AssignedTargetingOption resources have not changed.

  Update calls managing the following targeting types to use enum values:

  • TARGETING_TYPE_AGE_RANGE
  • TARGETING_TYPE_CONTENT_INSTREAM_POSITION
  • TARGETING_TYPE_CONTENT_OUTSTREAM_POSITION
  • TARGETING_TYPE_DEVICE_TYPE
  • TARGETING_TYPE_DIGITAL_CONTENT_LABEL_EXCLUSION
  • TARGETING_TYPE_ENVIRONMENT
  • TARGETING_TYPE_EXCHANGE
  • TARGETING_TYPE_GENDER
  • TARGETING_TYPE_HOUSEHOLD_INCOME
  • TARGETING_TYPE_NATIVE_CONTENT_POSITION
  • TARGETING_TYPE_OMID
  • TARGETING_TYPE_PARENTAL_STATUS
  • TARGETING_TYPE_SENSITIVE_CATEGORY_EXCLUSION
  • TARGETING_TYPE_VIDEO_PLAYER_SIZE
  • TARGETING_TYPE_VIEWABILITY

• The method advertisers.lineItems.bulkEditLineItemAssignedTargetingOptions has been replaced by the method advertisers.lineItems.bulkEditAssignedTargetingOptions.

• The method advertisers.lineItems.bulkListLineItemAssignedTargetingOptions has been replaced by the method advertisers.lineItems.bulkListAssignedTargetingOptions.

• Update calls managing TARGETING_TYPE_PROXIMITY_LOCATION_LIST to use a set radius size and distance unit instead of a ProximityRadiusRange enum value.

• Targeting methods that retrieve or edit targeting options across multiple targeting types under a single parent resource have been renamed.

  Update calls to the following methods to use their new names:

  • advertisers.bulkEditAdvertiserAssignedTargetingOptions to advertisers.editAssignedTargetingOptions
  • advertisers.bulkListAdvertiserAssignedTargetingOptions to advertisers.listAssignedTargetingOptions
  • advertisers.campaigns.bulkListCampaignAssignedTargetingOptions to advertisers.campaigns.listAssignedTargetingOptions
  • advertisers.insertionOrders.bulkListInsertionOrderAssignedTargetingOptions to advertisers.insertionOrders.listAssignedTargetingOptions
  • partners.bulkEditPartnerAssignedTargetingOptions to partners.editAssignedTargetingOptions

Update calls to advertisers.lineItems service

• The field inventorySourceIds has been removed. Manage inventory source assignment using AssignedTargetingOption resources of TARGETING_TYPE_INVENTORY_SOURCE.

• The following LineItemWarningMessage enum values have been deprecated in v2 and will no longer be surfaced in LineItem.warningMessages:

  • NO_POSITIVE_AUDIENCE_LIST_TARGETED
  • APP_INSTALL_NO_CONVERSION_PIXEL
  • TARGETING_REVOKED_OR_CLOSED_USER_LIST
  • APP_INSTALL_NO_OPTIMAL_BIDDING_STRATEGY
  • CREATIVE_SIZE_NOT_IN_USE_FOR_TARGETED_DEALS
  • NO_CREATIVE_FOR_TARGETED_DEALS
  • TARGETING_DEPRECATED_GEO_TARGET

• The triggerId field has been removed from the LineItemFlight object and the LINE_ITEM_FLIGHT_DATE_TYPE_TRIGGER value has been removed from the LineItemFlightDateType enum type. v2 does not support setting line items to spend based on the activation of manual triggers.

Update calls to customBiddingAlgorithms service

The customBiddingAlgorithmState and modelReadiness fields have been replaced with the modelDetails field, which provides the readiness and suspension states of the existing algorithm model for each advertiser that has access through a list of CustomBiddingModelDetails objects.

Additional changes

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

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

Read-only access to YouTube line items

In v2, YouTube line items and their targeting settings can be retrieved using the advertisers.lineItems and advertisers.lineItems.targetingTypes.assignedTargetingOptions services, respectively. The API provides read-only access, meaning that any attempted write requests made to these line items will return an error. YouTube line items will be of one of the following LineItemType values:

• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_ACTION
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_AUDIO
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_NON_SKIPPABLE
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_NON_SKIPPABLE_OVER_THE_TOP
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_REACH
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_REACH_OVER_THE_TOP
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_SIMPLE
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_SIMPLE_OVER_THE_TOP
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_VIDEO_SEQUENCE

New methods enabling better performance

In v2, the advertisers.lineItems service provides new methods to use in place of batched requests for better performance and reduced quota consumption:

• You can use advertisers.lineItems.bulkUpdate to set the same field values for multiple line items. Only updates to the entityStatus field are currently supported.
• You can use advertisers.lineItems.bulkEditAssignedTargetingOptions to add or remove the same assigned targeting options across multiple line items.
• You can use advertisers.lineItems.bulkListAssignedTargetingOptions to list assigned targeting options across multiple line items.
• You can use advertisers.lineItems.duplicate to create a duplicate of an existing line item within the same insertion order, copying over all configurations and targeting settings.

Partial write access for insertion order targeting

In v2, you can edit a subset targeting settings for InsertionOrder resources using new create and delete methods in the advertisers.insertionOrders.targetingTypes.assignedTargetingOptions service. The following targeting types can be fully managed at the insertion order level:

• TARGETING_TYPE_AGE_RANGE
• TARGETING_TYPE_BROWSER
• TARGETING_TYPE_CATEGORY
• TARGETING_TYPE_CHANNEL
• TARGETING_TYPE_DEVICE_MAKE_MODEL
• TARGETING_TYPE_DIGITAL_CONTENT_LABEL_EXCLUSION
• TARGETING_TYPE_ENVIRONMENT
• TARGETING_TYPE_GENDER
• TARGETING_TYPE_KEYWORD
• TARGETING_TYPE_LANGUAGE
• TARGETING_TYPE_NEGATIVE_KEYWORD_LIST
• TARGETING_TYPE_OPERATING_SYSTEM
• TARGETING_TYPE_PARENTAL_STATUS
• TARGETING_TYPE_SENSITIVE_CATEGORY_EXCLUSION
• TARGETING_TYPE_VIEWABILITY