Release notes

This page provides release notes for the Google Bid Manager API.

Version 2

Made structural changes to the API, including updating the service endpoint and renaming services and methods.

Significantly updated Query and Report resources by removing unnecessary fields, reorganizing existing fields, and changing field types. This includes changing field types to use named objects instead of a general "nested object" definition.

Required running ad-hoc queries using the queries.run method instead of having them run automatically after creation.

Replaced the queries.run query parameter asynchronous with synchronous.

Simplified report retrieval through the following changes:

• The addition of a queries.reports.get method.
• The addition of an orderBy query parameter to queries.reports.list.
• The update of the queries.run response body from an empty object to an instance of the generated Report resource.

Updated error messages returned by the API to be more specific and provide more prescriptive solutions.

Follow the instructions presented in the v2 Migration Guide to migrate from v1.1 to v2.

New features

• The service endpoint has been changed:

  v1 service endpoint	v2 service endpoint
  https://www.googleapis.com/doubleclickbidmanager	https://doubleclickbidmanager.googleapis.com

• Services have been renamed as follows:

  v1 service	v2 service
  Queries	queries
  Reports	queries.reports

• Methods have been renamed as follows:

  v1 method	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

• The following methods have been added:

  Service	Method(s)
  queries.reports	get

• The following methods have a new response body:

  Method	New response body object
  queries.run	Report

• The following fields have been removed:

  Resource	Field(s)
  queries.list Response Body	kind
  queries.reports.list Response Body	kind
  Query	kind reportDataEndTimeMs reportDataStartTimeMs timezoneCode
  RunQueryRequest	reportDataEndTimeMs reportDataStartTimeMs timezoneCode

• The object type of the following fields have been changed to the following:

  Resource	Field(s)	Object Type
  Query	metadata params schedule	QueryMetadata Parameters QuerySchedule
  Report	key metadata params	ReportKey ReportMetadata Parameters
  RunQueryRequest	dataRange	DataRange

• The following method query parameters have been added:

  Method	Query Parameter(s)
  queries.list	orderBy
  queries.reports.list	orderBy
  queries.run	synchronous

• The following method query parameters have been removed:

  Method	Query Parameter(s)
  queries.create	asynchronous
  queries.run	asynchronous

• The following Filter values have been added:

  Filter value
  FILTER_INVENTORY_MEDIA_COST_TYPE
  FILTER_TARGETING_EXPANSION

• The following Filter values have been removed:

  Filter value
  FILTER_TRUEVIEW_IAR_REGION

• The following Metric values have been added:

  Metric value
  METRIC_STORE_VISIT_VIEW_THROUGH_CONVERSIONS
  METRIC_UNIQUE_REACH_AVERAGE_VIEWABLE_IMPRESSION_FREQUENCY
  METRIC_UNIQUE_REACH_IMPRESSION_REACH_ADDED_WITH_CROSS_STACK_FCAP
  METRIC_UNIQUE_REACH_IMPRESSION_REACH_ADDED_WITH_PG_FMGMT
  METRIC_UNIQUE_REACH_INCREMENTAL_CLICK_REACH
  METRIC_UNIQUE_REACH_INCREMENTAL_IMPRESSION_REACH
  METRIC_UNIQUE_REACH_INCREMENTAL_TOTAL_REACH
  METRIC_UNIQUE_REACH_INCREMENTAL_VIEWABLE_IMPRESSION_REACH
  METRIC_UNIQUE_REACH_VIEWABLE_IMPRESSION_REACH

Known issues

None.

Version 1.1

Note: All changes introduced in v1.1 only affect Queries and Reports.

One-to-one filter to report column mapping

Filters that mapped to multiple report columns now map to single columns.

For example, in v1, including the filter FILTER_ADVERTISER yields a report with columns "Advertiser" in addition to "Advertiser ID". In v1.1, all report columns have their own filters. For example, a new filter FILTER_ADVERTISER_NAME maps to "Advertiser". To get both "Advertiser ID" and "Advertiser" columns in reports, both filters FILTER_ADVERTISER and FILTER_ADVERTISER_NAME, respectively, will have to be included in Queries.createquery requests.

More concretely, the createquery request:

{
...
"params": {
  ...
  "groupBys": ["FILTER_ADVERTISER"],
  "metrics": ["METRIC_IMPRESSIONS"],
  ...
}
...
}

generates a report file with the following headers in v1:

Advertiser,Advertiser ID,Advertiser Status,Advertiser Integration Code,Impressions

and the following headers in v1.1:

Advertiser,Impressions

The following v1 code used to get report columns in the example above:

List<String> groupBys = new ArrayList<>();
groupBys.add("FILTER_ADVERTISER");
List<String> metrics = new ArrayList<>();
metrics.add("METRIC_IMPRESSIONS");
com.google.api.services.doubleclickbidmanager.model.Parameters createQueryParameters =
    new com.google.api.services.doubleclickbidmanager.model.Parameters()
        .setGroupBys(groupBys)
        .setMetrics(metrics);

will have to be modified similar to the following in v1.1 (note filter ordering):

List<String> groupBys = new ArrayList<>();
groupBys.add("FILTER_ADVERTISER_NAME");
groupBys.add("FILTER_ADVERTISER");
groupBys.add("FILTER_ADVERTISER_INTEGRATION_STATUS");
groupBys.add("FILTER_ADVERTISER_INTEGRATION_CODE");
List<String> metrics = new ArrayList<>();
metrics.add("METRIC_IMPRESSIONS");
com.google.api.services.doubleclickbidmanager.model.Parameters createQueryParameters =
    new com.google.api.services.doubleclickbidmanager.model.Parameters()
        .setGroupBys(groupBys)
        .setMetrics(metrics);

Note: Other API methods and existing queries are not affected by this change. See the table below for newly added filters.

Original filter	Added filters
FILTER_ADVERTISER	FILTER_ADVERTISER_NAME FILTER_ADVERTISER_INTEGRATION_CODE FILTER_ADVERTISER_INTEGRATION_STATUS
FILTER_AD_POSITION	FILTER_AD_POSITION_NAME
FILTER_CARRIER	FILTER_CARRIER_NAME
FILTER_CHANNEL_ID	FILTER_CHANNEL_NAME
FILTER_CITY	FILTER_CITY_NAME
FILTER_COMPANION_CREATIVE_ID	FILTER_COMPANION_CREATIVE_NAME
FILTER_DMA	FILTER_DMA_NAME
FILTER_INSERTION_ORDER	FILTER_INSERTION_ORDER_NAME
FILTER_PARTNER	FILTER_PARTNER_NAME FILTER_PARTNER_STATUS
FILTER_REGION	FILTER_REGION_NAME
FILTER_TRUEVIEW_DMA	FILTER_TRUEVIEW_DMA_NAME
FILTER_TRUEVIEW_IAR_REGION	FILTER_TRUEVIEW_IAR_REGION_NAME
FILTER_USER_LIST_FIRST_PARTY	FILTER_USER_LIST_FIRST_PARTY_NAME
FILTER_USER_LIST_THIRD_PARTY	FILTER_USER_LIST_THIRD_PARTY_NAME

Pagination

v1.1 adds pagination to methods Queries.listqueries and Reports.listreports.

In v1.1, the number of results returned by these methods is equal to a newly added parameter pageSize (it defaults to 100 if not specified). Responses contain a newly added nextPageToken field that can be used to retrieve the next set of results. This field is blank if results have been exhausted.

The following v1 code to retrieve all reports belonging to a specific query:

public class GetReports {
  public List<Report> getReports(DoubleClickBidManager service, long queryId) throws IOException {
    ListReportsResponse reportListResponse = service.reports().listreports(queryId).execute();

    return reportListResponse.getReports();
  }
}

will have to be modified similar to the following in v1.1, in order to continue retrieving all reports:

public class GetReports {
  public List<Report> getReports(DoubleClickBidManager service, long queryId) throws IOException {
    ListReportsResponse reportListResponse = service.reports().listreports(queryId).execute();

    List<Report> reports = new ArrayList<>(reportListResponse.getReports());
    while (reportListResponse.getNextPageToken() != null
        && reportListResponse.getNextPageToken().length() > 0) {
      // Get next set of results, aka page.
      reportListResponse =
          service
              .reports()
              .listreports(queryId)
              .setPageToken(reportListResponse.getNextPageToken())
              .execute();
      reports.addAll(reportListResponse.getReports());
    }

    return reports;
  }
}

See Queries.listqueries and Reports.listreports method documentation for more details.

Known issues

None.

Version 1

This is the initial version of the API.

Known issues

None.