In March 2022, we released [version 2](https://developers.google.com/bid-manager/reference/rest) 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`](https://developers.google.com/bid-manager/v1.1/queries) and [`Reports`](https://developers.google.com/bid-manager/v1.1/reports) in v1.1 are known as [`queries`](https://developers.google.com/bid-manager/reference/rest/v2/queries) and [`queries.reports`](https://developers.google.com/bid-manager/reference/rest/v2/queries.reports) in v2.
- Methods have been renamed as follows in v2:

  | v1.1 method name | Equivalent v2 method |
  |---|---|
  | [`Queries.createquery`](https://developers.google.com/bid-manager/v1.1/queries/createquery) | [`queries.create`](https://developers.google.com/bid-manager/reference/rest/v2/queries/create) |
  | [`Queries.deletequery`](https://developers.google.com/bid-manager/v1.1/queries/deletequery) | [`queries.delete`](https://developers.google.com/bid-manager/reference/rest/v2/queries/delete) |
  | [`Queries.getquery`](https://developers.google.com/bid-manager/v1.1/queries/getquery) | [`queries.get`](https://developers.google.com/bid-manager/reference/rest/v2/queries/get) |
  | [`Queries.listqueries`](https://developers.google.com/bid-manager/v1.1/queries/listqueries) | [`queries.list`](https://developers.google.com/bid-manager/reference/rest/v2/queries/list) |
  | [`Queries.runquery`](https://developers.google.com/bid-manager/v1.1/queries/runquery) | [`queries.run`](https://developers.google.com/bid-manager/reference/rest/v2/queries/run) |
  | [`Reports.listreports`](https://developers.google.com/bid-manager/v1.1/reports/listreports) | [`queries.reports.list`](https://developers.google.com/bid-manager/reference/rest/v2/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`](https://developers.google.com/bid-manager/v1.1/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`](https://developers.google.com/bid-manager/reference/rest/v2/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`](https://developers.google.com/bid-manager/v1.1/queries#metadata) | [`QueryMetadata`](https://developers.google.com/bid-manager/reference/rest/v2/queries#QueryMetadata) |
  | [`params`](https://developers.google.com/bid-manager/v1.1/queries#params) | [`Parameters`](https://developers.google.com/bid-manager/reference/rest/v2/Parameters) |
  | [`params.options`](https://developers.google.com/bid-manager/v1.1/queries#params.options) | [`Options`](https://developers.google.com/bid-manager/reference/rest/v2/Parameters#Options) |
  | [`params.options.pathQueryOptions`](https://developers.google.com/bid-manager/v1.1/queries#params.options.pathQueryOptions) | Removed |
  | [`params.options.pathQueryOptions.channelGrouping`](https://developers.google.com/bid-manager/v1.1/queries#params.options.pathQueryOptions.channelGrouping) | Removed |
  | [`params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter`](https://developers.google.com/bid-manager/v1.1/queries#params.options.pathQueryOptions.channelGrouping.rules.disjunctiveMatchStatements.eventFilters.dimensionFilter) | Removed |
  | [`params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter`](https://developers.google.com/bid-manager/v1.1/queries#params.options.pathQueryOptions.pathFilters.eventFilters.dimensionFilter) | Removed |
  | [`schedule`](https://developers.google.com/bid-manager/v1.1/queries#schedule) | [`QuerySchedule`](https://developers.google.com/bid-manager/reference/rest/v2/queries#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[]`](https://developers.google.com/bid-manager/v1.1/queries#params.filters) | [`FilterPair`](https://developers.google.com/bid-manager/reference/rest/v2/Parameters#FilterPair) |
  | [`params.options.pathQueryOptions.channelGrouping.rules[]`](https://developers.google.com/bid-manager/v1.1/queries#params.options.pathQueryOptions.channelGrouping.rules) | Removed |
  | [`params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[]`](https://developers.google.com/bid-manager/v1.1/queries#params.options.pathQueryOptions.channelGrouping.rules.disjunctiveMatchStatements) | Removed |
  | [`params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[]`](https://developers.google.com/bid-manager/v1.1/queries#params.options.pathQueryOptions.channelGrouping.rules.disjunctiveMatchStatements.eventFilters) | Removed |
  | [`params.options.pathQueryOptions.pathFilters[]`](https://developers.google.com/bid-manager/v1.1/queries#params.options.pathQueryOptions.pathFilters) | Removed |
  | [`params.options.pathQueryOptions.pathFilters[].eventFilters[]`](https://developers.google.com/bid-manager/v1.1/queries#params.options.pathQueryOptions.pathFilters.eventFilters) | Removed |

- 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`](https://developers.google.com/bid-manager/reference/rest/v2/queries#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`](https://developers.google.com/bid-manager/reference/rest/v2/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`](https://developers.google.com/bid-manager/reference/rest/v2/queries#Frequency) enum. In converting to this enum, the value `FREQUENCY_UNSPECIFIED` has been added.
  - `params.type` now uses the [`ReportType`](https://developers.google.com/bid-manager/reference/rest/v2/Parameters#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`](https://developers.google.com/bid-manager/reference/rest/v2/Parameters#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`](https://developers.google.com/bid-manager/v1.1/queries#metadata.dataRange), [`reportDataStartTimeMs`](https://developers.google.com/bid-manager/v1.1/queries#reportDataStartTimeMs), and [`reportDataEndTimeMs`](https://developers.google.com/bid-manager/v1.1/queries#reportDataEndTimeMs) have been replaced with fields [`range`](https://developers.google.com/bid-manager/reference/rest/v2/queries#DataRange.FIELDS.range), [`customStartDate`](https://developers.google.com/bid-manager/reference/rest/v2/queries#DataRange.FIELDS.custom_start_date), and [`customEndDate`](https://developers.google.com/bid-manager/reference/rest/v2/queries#DataRange.FIELDS.custom_end_date). The new date fields use [`Date`](https://developers.google.com/bid-manager/reference/rest/v2/Date) objects instead of milliseconds since Unix Epoch. These replacement fields have been moved into the [`DataRange`](https://developers.google.com/bid-manager/reference/rest/v2/queries#DataRange) object assigned to the [`dataRange`](https://developers.google.com/bid-manager/reference/rest/v2/queries#QueryMetadata.FIELDS.data_range) field in the [`QueryMetadata`](https://developers.google.com/bid-manager/reference/rest/v2/queries#QueryMetadata) object.
- Fields [`schedule.startTimeMs`](https://developers.google.com/bid-manager/v1.1/queries#schedule.startTimeMs) and [`schedule.endTimeMs`](https://developers.google.com/bid-manager/v1.1/queries#schedule.endTimeMs) have been replaced with fields [`startDate`](https://developers.google.com/bid-manager/reference/rest/v2/queries#QuerySchedule.FIELDS.start_date) and [`endDate`](https://developers.google.com/bid-manager/reference/rest/v2/queries#QuerySchedule.FIELDS.end_date) in the [`QuerySchedule`](https://developers.google.com/bid-manager/reference/rest/v2/queries#QuerySchedule) object. The new date fields use [`Date`](https://developers.google.com/bid-manager/reference/rest/v2/Date) objects instead of milliseconds since Unix Epoch.
- Fields [`metadata.running`](https://developers.google.com/bid-manager/v1.1/queries#metadata.running), [`metadata.reportCount`](https://developers.google.com/bid-manager/v1.1/queries#metadata.reportCount), [`metadata.googleCloudStoragePathForLatestReport`](https://developers.google.com/bid-manager/v1.1/queries#metadata.googleCloudStoragePathForLatestReport), [`metadata.googleDrivePathForLatestReport`](https://developers.google.com/bid-manager/v1.1/queries#metadata.googleDrivePathForLatestReport), and [`metadata.latestReportRunTimeMs`](https://developers.google.com/bid-manager/v1.1/queries#metadata.latestReportRunTimeMs) have been removed. Information regarding the most recent generated reports of a query should instead be retrieved using the [`queries.reports.list`](https://developers.google.com/bid-manager/reference/rest/v2/queries.reports/list) method with the [`orderBy`](https://developers.google.com/bid-manager/reference/rest/v2/queries.reports/list#body.QUERY_PARAMETERS.order_by) query parameter of "key.reportId desc" to guarantee that the request lists the most recent reports first.
- Fields [`kind`](https://developers.google.com/bid-manager/v1.1/queries#kind), [`timezoneCode`](https://developers.google.com/bid-manager/v1.1/queries#timezoneCode), [`metadata.locale`](https://developers.google.com/bid-manager/v1.1/queries#metadata.locale), [`params.includeInviteData`](https://developers.google.com/bid-manager/v1.1/queries#params.includeInviteData), and [`schedule.nextRunMinuteOfDay`](https://developers.google.com/bid-manager/v1.1/queries#schedule.nextRunMinuteOfDay) have been removed.
- [`queries.create`](https://developers.google.com/bid-manager/reference/rest/v2/queries/create) no longer automatically runs queries after creation and the [`asynchronous`](https://developers.google.com/bid-manager/v1.1/queries/createquery#asynchronous) query parameter has been removed. Call [`queries.run`](https://developers.google.com/bid-manager/reference/rest/v2/queries/run) after [`queries.create`](https://developers.google.com/bid-manager/reference/rest/v2/queries/create) to generate reports for new queries.
- The [`queries.run`](https://developers.google.com/bid-manager/reference/rest/v2/queries/run) method has been updated in the following ways:
  - The [`asynchronous`](https://developers.google.com/bid-manager/v1.1/queries/runquery#asynchronous) query parameter has been replaced with the [`synchronous`](https://developers.google.com/bid-manager/reference/rest/v2/queries/run#body.QUERY_PARAMETERS.synchronous) query parameter. The new query parameter operates with inverse logic and is considered false if not specified. Given this, [`queries.run`](https://developers.google.com/bid-manager/reference/rest/v2/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`](https://developers.google.com/bid-manager/v1.1/queries/runquery#timezoneCode) field and replace [`dataRange`](https://developers.google.com/bid-manager/v1.1/queries/runquery#dataRange), [`reportDataStartTimeMs`](https://developers.google.com/bid-manager/v1.1/queries/runquery#reportDataStartTimeMs), [`reportDataEndTimeMs`](https://developers.google.com/bid-manager/v1.1/queries/runquery#reportDataEndTimeMs) fields with a [`DataRange`](https://developers.google.com/bid-manager/reference/rest/v2/queries#DataRange) object assigned to the [`dataRange`](https://developers.google.com/bid-manager/reference/rest/v2/queries/run#RunQueryRequest.FIELDS.data_range) field.
  - The method returns the resulting [`Report`](https://developers.google.com/bid-manager/reference/rest/v2/queries.reports) object instead of an empty response body.
- The [`kind`](https://developers.google.com/bid-manager/v1.1/queries/listqueries#kind) field in the [`queries.list`](https://developers.google.com/bid-manager/reference/rest/v2/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`](https://developers.google.com/bid-manager/v1.1/reports#key) | [`ReportKey`](https://developers.google.com/bid-manager/reference/rest/v2/queries.reports#ReportKey) |
  | [`metadata`](https://developers.google.com/bid-manager/v1.1/reports#metadata) | [`ReportMetadata`](https://developers.google.com/bid-manager/reference/rest/v2/queries.reports#ReportMetadata) |
  | [`metadata.status`](https://developers.google.com/bid-manager/v1.1/reports#metadata.status) | [`ReportStatus`](https://developers.google.com/bid-manager/reference/rest/v2/queries.reports#ReportStatus) |
  | [`params`](https://developers.google.com/bid-manager/v1.1/reports#params) | [`Parameters`](https://developers.google.com/bid-manager/reference/rest/v2/Parameters) |
  | [`params.options`](https://developers.google.com/bid-manager/v1.1/reports#params.options) | [`Options`](https://developers.google.com/bid-manager/reference/rest/v2/Parameters#Options) |
  | [`params.options.pathQueryOptions`](https://developers.google.com/bid-manager/v1.1/reports#params.options.pathQueryOptions) | Removed |
  | [`params.options.pathQueryOptions.channelGrouping`](https://developers.google.com/bid-manager/v1.1/reports#params.options.pathQueryOptions.channelGrouping) | Removed |
  | [`params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter`](https://developers.google.com/bid-manager/v1.1/reports#params.options.pathQueryOptions.channelGrouping.rules.disjunctiveMatchStatements.eventFilters.dimensionFilter) | Removed |
  | [`params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter`](https://developers.google.com/bid-manager/v1.1/reports#params.options.pathQueryOptions.pathFilters.eventFilters.dimensionFilter) | Removed |

- 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[]`](https://developers.google.com/bid-manager/v1.1/reports#params.filters) | [`FilterPair`](https://developers.google.com/bid-manager/reference/rest/v2/Parameters#FilterPair) |
  | [`params.options.pathQueryOptions.channelGrouping.rules[]`](https://developers.google.com/bid-manager/v1.1/reports#params.options.pathQueryOptions.channelGrouping.rules) | Removed |
  | [`params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[]`](https://developers.google.com/bid-manager/v1.1/reports#params.options.pathQueryOptions.channelGrouping.rules.disjunctiveMatchStatements) | Removed |
  | [`params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[]`](https://developers.google.com/bid-manager/v1.1/reports#params.options.pathQueryOptions.channelGrouping.rules.disjunctiveMatchStatements.eventFilters) | Removed |
  | [`params.options.pathQueryOptions.pathFilters[]`](https://developers.google.com/bid-manager/v1.1/reports#params.options.pathQueryOptions.pathFilters) | Removed |
  | [`params.options.pathQueryOptions.pathFilters[].eventFilters[]`](https://developers.google.com/bid-manager/v1.1/reports#params.options.pathQueryOptions.pathFilters.eventFilters) | Removed |

- 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`](https://developers.google.com/bid-manager/reference/rest/v2/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`](https://developers.google.com/bid-manager/reference/rest/v2/queries.reports#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`](https://developers.google.com/bid-manager/reference/rest/v2/Parameters#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`](https://developers.google.com/bid-manager/v1.1/reports#metadata.reportDataStartTimeMs) and [`metadata.reportDataEndTimeMs`](https://developers.google.com/bid-manager/v1.1/reports#metadata.reportDataEndTimeMs) have been replaced with fields [`reportDataStartDate`](https://developers.google.com/bid-manager/reference/rest/v2/queries.reports#ReportMetadata.FIELDS.report_data_start_date) and [`reportDataEndDate`](https://developers.google.com/bid-manager/reference/rest/v2/queries.reports#ReportMetadata.FIELDS.report_data_end_date) in the [`ReportMetadata`](https://developers.google.com/bid-manager/reference/rest/v2/queries.reports#ReportMetadata) object. The new fields use [`Date`](https://developers.google.com/bid-manager/reference/rest/v2/Date) objects instead of milliseconds since Unix Epoch.
- [`metadata.status.finishTimeMs`](https://developers.google.com/bid-manager/v1.1/reports#metadata.status.finishTimeMs) has been replaced by the [`finishTime`](https://developers.google.com/bid-manager/reference/rest/v2/queries.reports#ReportStatus.FIELDS.finish_time) field in the [`ReportStatus`](https://developers.google.com/bid-manager/reference/rest/v2/queries.reports#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`](https://developers.google.com/bid-manager/v1.1/reports#metadata.status.failure) and [`params.includeInviteData`](https://developers.google.com/bid-manager/v1.1/queries#params.includeInviteData) fields have been removed.
- The [`kind`](https://developers.google.com/bid-manager/v1.1/reports/listreports#kind) field in the [`reports.list`](https://developers.google.com/bid-manager/reference/rest/v2/queries.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.