Migrate from Bid Manager API v1.1 to v2

AI-generated Key Takeaways

• Bid Manager API v1.1 will be sunset soon following the release of v2 in March 2022; migration to v2 is recommended.

• Migrating to v2 involves updating endpoint URLs and application code to accommodate breaking changes, such as renaming services and methods, and utilizing new object and enum types for specific fields.

• Notable changes in v2 include restructuring Query and Report resources with new object types, replacing string representations with enums, updating date and time formats, and removing or replacing specific fields.

• Error handling logic might need adjustments as error messages in v2 are more detailed and specific.

In March 2022, we released version 2 of Bid Manager API. Given the release of this new version, we plan to announce a sunset date for v1.1 soon. We recommend that you start your migration from v1.1 to v2 as soon as you can.

Migrate your application

Migrating from v1.1 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.1 to v2

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

Identify equivalent methods

In order to update your API calls from using v1.1 to v2, you first must identify the equivalent v1.1 methods in v2.

The following names of all services and methods have changed slightly between v1.1 and v2:

• Services Queries and Reports in v1.1 are known as queries and queries.reports in v2.
• Methods have been renamed as follows in v2:

  v1.1 method name	Equivalent v2 method
  Queries.createquery	queries.create
  Queries.deletequery	queries.delete
  Queries.getquery	queries.get
  Queries.listqueries	queries.list
  Queries.runquery	queries.run
  Reports.listreports	queries.reports.list

Update to new endpoints

Once you've identified equivalent methods, you need to update your requests. For example, to call the queries.getquery method with v1.1, you would use the following URL:

https://www.googleapis.com/doubleclickbidmanager/v1.1/query/queryId

To call the equivalent method in v2, known as queries.get, update the URL to the following:

GET https://doubleclickbidmanager.googleapis.com/v2/queries/queryId

If you're 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 Bid Manager API.

Update calls to queries service

• The following fields in the Query resource originally represented by general nested objects have changed to use the following object types:

  v1.1 field	Equivalent v2 object type
  metadata	QueryMetadata
  params	Parameters
  params.options	Options
  params.options.pathQueryOptions	PathQueryOptions
  params.options.pathQueryOptions.channelGrouping	ChannelGrouping
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter	PathQueryOptionsFilter
  params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter	PathQueryOptionsFilter
  schedule	QuerySchedule

• The following fields in the Query resource originally represented by general list objects have changed to be lists of the following new object types:

  v1.1 list field	v2 object type
  params.filters[]	FilterPair
  params.options.pathQueryOptions.channelGrouping.rules[]	Rule
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[]	DisjunctiveMatchStatement
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[]	EventFilter
  params.options.pathQueryOptions.pathFilters[]	PathFilter
  params.options.pathQueryOptions.pathFilters[].eventFilters[]	EventFilter

• The following fields in the Query resource, originally represented by strings,are represented by enum types in v2, and include the following changes:
  • The v2 equivalent of metadata.dataRange now uses the Range enum. In converting to this enum, the value PREVIOUS_HALF_MONTH has been removed and the value TYPE_NOT_SUPPORTED was changed to RANGE_UNSPECIFIED.
  • metadata.format now uses the Format enum. In converting to this enum, the value EXCEL_CSV has been removed and the value FORMAT_UNSPECIFIED has been added.
  • params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter.match and params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter.match now use the Match enum.
  • params.options.pathQueryOptions.pathFilters[].pathMatchPosition now uses the PathMatchPosition enum. In converting to this enum, the value PATH_MATCH_POSITION_UNSPECIFIED has been added.
  • schedule.frequency now uses the Frequency enum. In converting to this enum, the value FREQUENCY_UNSPECIFIED has been added.
  • params.type now uses the ReportType enum. In converting to this enum, the following changes have been made:
  • The following values have been deprecated:
    • TYPE_ACTIVE_GRP
    • TYPE_AUDIENCE_PERFORMANCE
    • TYPE_CLIENT_SAFE
    • TYPE_COMSCORE_VCE
    • TYPE_CROSS_FEE
    • TYPE_CROSS_PARTNER
    • TYPE_CROSS_PARTNER_THIRD_PARTY_DATA_PROVIDER
    • TYPE_ESTIMATED_CONVERSION
    • TYPE_FEE
    • TYPE_KEYWORD
    • TYPE_LINEAR_TV_SEARCH_LIFT
    • TYPE_NIELSEN_AUDIENCE_PROFILE
    • TYPE_NIELSEN_DAILY_REACH_BUILD
    • TYPE_NIELSEN_ONLINE_GLOBAL_MARKET
    • TYPE_PAGE_CATEGORY
    • TYPE_PETRA_NIELSEN_DAILY_REACH_BUILD
    • TYPE_PETRA_NIELSEN_ONLINE_GLOBAL_MARKET
    • TYPE_PIXEL_LOAD
    • TYPE_THIRD_PARTY_DATA_PROVIDER
    • TYPE_TRUEVIEW_IAR
    • TYPE_VERIFICATION
    • TYPE_YOUTUBE_VERTICAL
  • The remaining values have all been updated to better reflect their equivalent values in the UI:

    v1.1 values	Equivalent ReportType value
    TYPE_NOT_SUPPORTED	REPORT_TYPE_UNSPECIFIED
    TYPE_GENERAL	STANDARD
    TYPE_INVENTORY_AVAILABILITY	INVENTORY_AVAILABILITY
    TYPE_AUDIENCE_COMPOSITION	AUDIENCE_COMPOSITION
    TYPE_ORDER_ID	FLOODLIGHT
    TYPE_TRUEVIEW	YOUTUBE
    TYPE_NIELSEN_SITE	GRP
    TYPE_PETRA_NIELSEN_AUDIENCE_PROFILE	YOUTUBE_PROGRAMMATIC_GUARANTEED
    TYPE_REACH_AND_FREQUENCY	REACH
    TYPE_REACH_AUDIENCE	UNIQUE_REACH_AUDIENCE
    TYPE_PATH	FULL_PATH
    TYPE_PATH_ATTRIBUTION	PATH_ATTRIBUTION

• Fields metadata.dataRange, reportDataStartTimeMs, and reportDataEndTimeMs have been replaced with fields range, customStartDate, and customEndDate. The new date fields use Date objects instead of milliseconds since Unix Epoch. These replacement fields have been moved into the DataRange object assigned to the dataRange field in the QueryMetadata object.
• Fields schedule.startTimeMs and schedule.endTimeMs have been replaced with fields startDate and endDate in the QuerySchedule object. The new date fields use Date objects instead of milliseconds since Unix Epoch.
• Fields metadata.running, metadata.reportCount, metadata.googleCloudStoragePathForLatestReport, metadata.googleDrivePathForLatestReport, and metadata.latestReportRunTimeMs have been removed. Information regarding the most recent generated reports of a query should instead be retrieved using the queries.reports.list method with the orderBy query parameter of “key.reportId desc” to guarantee that the request lists the most recent reports first.
• Fields kind, timezoneCode, metadata.locale, params.includeInviteData, and schedule.nextRunMinuteOfDay have been removed.
• queries.create no longer automatically runs queries after creation and the asynchronous query parameter has been removed. Call queries.run after queries.create to generate reports for new queries.
• The queries.run method has been updated in the following ways:
  • The asynchronous query parameter has been replaced with the synchronous query parameter. The new query parameter operates with inverse logic and is considered false if not specified. Given this, queries.run generates reports asynchronously by default in v2 as opposed to synchronously, which is the default in v1.1.
  • The request body has been updated to remove the timezoneCode field and replace dataRange, reportDataStartTimeMs, reportDataEndTimeMs fields with a DataRange object assigned to the dataRange field.
  • The method returns the resulting Report object instead of an empty response body.
• The kind field in the queries.list response body has been removed.

Update calls to reports service

• The following fields in the Report resource originally represented by general nested objects have changed to use the following object types:

  v1.1 field	Equivalent v2 object type
  key	ReportKey
  metadata	ReportMetadata
  metadata.status	ReportStatus
  params	Parameters
  params.options	Options
  params.options.pathQueryOptions	PathQueryOptions
  params.options.pathQueryOptions.channelGrouping	ChannelGrouping
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter	PathQueryOptionsFilter
  params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter	PathQueryOptionsFilter

• The following fields in the Report resource originally represented by general list objects have changed to be lists of the following new object types:

  v1.1 list field	v2 object type
  params.filters[]	FilterPair
  params.options.pathQueryOptions.channelGrouping.rules[]	Rule
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[]	DisjunctiveMatchStatement
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[]	EventFilter
  params.options.pathQueryOptions.pathFilters[]	PathFilter
  params.options.pathQueryOptions.pathFilters[].eventFilters[]	EventFilter

• The following fields in the Report resource originally represented by strings have changed so their equivalent fields in v2 are represented by new enum types and include changes to acceptable values:
  • metadata.status.format now uses the Format enum. In converting to this enum, the value EXCEL_CSV has been removed and FORMAT_UNSPECIFIED has been added.
  • metadata.status.state now uses the State enum. In converting to this enum, the values QUEUED and STATE_UNSPECIFIED have been added.
  • params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter.match and params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter.match now use the Match enum.
  • params.options.pathQueryOptions.pathFilters[].pathMatchPosition now uses the PathMatchPosition enum. In converting to this enum, the value PATH_MATCH_POSITION_UNSPECIFIED has been added.
  • params.type now uses the ReportType enum. In converting to this enum, numerous changes have been made and are listed in detail in the previous section regarding updating queries service calls.
• Fields metadata.reportDataStartTimeMs and metadata.reportDataEndTimeMs have been replaced with fields reportDataStartDate and reportDataEndDate in the ReportMetadata object. The new fields use Date objects instead of milliseconds since Unix Epoch.
• metadata.status.finishTimeMs has been replaced by the finishTime field in the ReportStatus object. This new time field represents the datetime as a timestamp in RFC3339 UTC "Zulu" format instead of in milliseconds since Unix Epoch.
• metadata.status.failure and params.includeInviteData fields have been removed.
• The kind field in the reports.list response body has been removed.

Update error handling logic

Error messages across the API have been updated in v2. These new error messages are more specific and, in some cases, provide information on the values in the API request that are causing the error to be returned. If your existing error handling logic relies on specific error message text, generalize your error handling before migrating to v2.