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 thetargetingTypes.targetingOptions
service. String versions of these enums are represented in the newassignedTargetingOptionIdAlias
field in theseAssignedTargetingOption
resources and can be used when retrieving or deleting existing targeting. TheassignedTargetingOptionId
value of theseAssignedTargetingOption
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 methodadvertisers.lineItems.bulkEditAssignedTargetingOptions
.The method
advertisers.lineItems.bulkListLineItemAssignedTargetingOptions
has been replaced by the methodadvertisers.lineItems.bulkListAssignedTargetingOptions
.Update calls managing
TARGETING_TYPE_PROXIMITY_LOCATION_LIST
to use a set radius size and distance unit instead of aProximityRadiusRange
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
toadvertisers.editAssignedTargetingOptions
advertisers.bulkListAdvertiserAssignedTargetingOptions
toadvertisers.listAssignedTargetingOptions
advertisers.campaigns.bulkListCampaignAssignedTargetingOptions
toadvertisers.campaigns.listAssignedTargetingOptions
advertisers.insertionOrders.bulkListInsertionOrderAssignedTargetingOptions
toadvertisers.insertionOrders.listAssignedTargetingOptions
partners.bulkEditPartnerAssignedTargetingOptions
topartners.editAssignedTargetingOptions
Update calls to advertisers.lineItems
service
- The field
inventorySourceIds
has been removed. Manage inventory source assignment usingAssignedTargetingOption
resources ofTARGETING_TYPE_INVENTORY_SOURCE
. The following
LineItemWarningMessage
enum values have been deprecated in v2 and will no longer be surfaced inLineItem.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 theLineItemFlight
object and theLINE_ITEM_FLIGHT_DATE_TYPE_TRIGGER
value has been removed from theLineItemFlightDateType
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 theentityStatus
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