Reports

For a list of methods for this resource, see the end of this page.

Resource representations

A DoubleClick Search report. This object contains the report request, some report metadata such as currency code, and the generated report rows or report files.

{
  "kind": "doubleclicksearch#report",
  "id": string,
  "isReportReady": boolean,
  "request": {
    "reportScope": {
      "agencyId": long,
      "advertiserId": long,
      "engineAccountId": long,
      "campaignId": long,
      "adGroupId": long,
      "keywordId": long,
      "adId": long
    },
    "reportType": string,
    "columns": [
      {
        "columnName": string,
        "savedColumnName": string,
        "customDimensionName": string,
        "customMetricName": string,
        "headerText": string,
        "startDate": string,
        "endDate": string,
        "groupByColumn": boolean,
        "platformSource": string,
        "productReportPerspective": string
      }
    ],
    "timeRange": {
      "startDate": string,
      "endDate": string,
      "changedMetricsSinceTimestamp": datetime,
      "changedAttributesSinceTimestamp": datetime
    },
    "filters": [
      {
        "column": {
          "columnName": string,
          "savedColumnName": string,
          "customDimensionName": string,
          "customMetricName": string,
          "headerText": string,
          "startDate": string,
          "endDate": string,
          "groupByColumn": boolean,
          "platformSource": string,
          "productReportPerspective": string
        },
        "operator": string,
        "values": [
          (value)
        ]
      }
    ],
    "orderBy": [
      {
        "column": {
          "columnName": string,
          "savedColumnName": string,
          "customDimensionName": string,
          "customMetricName": string,
          "headerText": string,
          "startDate": string,
          "endDate": string,
          "groupByColumn": boolean,
          "platformSource": string,
          "productReportPerspective": string
        },
        "sortOrder": string
      }
    ],
    "includeDeletedEntities": boolean,
    "includeRemovedEntities": boolean,
    "verifySingleTimeZone": boolean,
    "downloadFormat": string,
    "statisticsCurrency": string,
    "startRow": integer,
    "rowCount": integer,
    "maxRowsPerFile": integer
  },
  "statisticsCurrencyCode": string,
  "statisticsTimeZone": string,
  "rowCount": integer,
  "files": [
    {
      "url": string,
      "byteCount": long
    }
  ],
  "rows": [
    {
      (key): (value)
    }
  ]
}
Property name Value Description Notes
files[] list Asynchronous report only. Contains a list of generated report files once the report has successfully completed.
files[].byteCount long The size of this report file in bytes.
files[].url string Use this url to download the report file.
id string Asynchronous report only. Id of the report.
isReportReady boolean Asynchronous report only. True if and only if the report has completed successfully and the report files are ready to be downloaded.
kind string Identifies this as a Report resource. Value: the fixed string doubleclicksearch#report.
request nested object The request that created the report. Optional fields not specified in the original request are filled with default values.
request.columns[] list The columns to include in the report. This includes both DoubleClick Search columns and saved columns. For DoubleClick Search columns, only the columnName parameter is required. For saved columns only the savedColumnName parameter is required. Both columnName and savedColumnName cannot be set in the same stanza.

The maximum number of columns per request is 300.

request.columns[].columnName string Name of a DoubleClick Search column to include in the report.
request.columns[].customDimensionName string Segments a report by a custom dimension. The report must be scoped to an advertiser or lower, and the custom dimension must already be set up in DoubleClick Search. The custom dimension name, which appears in DoubleClick Search, is case sensitive.

If used in a conversion report, returns the value of the specified custom dimension for the given conversion, if set. This column does not segment the conversion report.

request.columns[].customMetricName string Name of a custom metric to include in the report. The report must be scoped to an advertiser or lower, and the custom metric must already be set up in DoubleClick Search. The custom metric name, which appears in DoubleClick Search, is case sensitive.
request.columns[].endDate string Inclusive day in YYYY-MM-DD format. When provided, this overrides the overall time range of the report for this column only. Must be provided together with startDate.
request.columns[].groupByColumn boolean Synchronous report only. Set to true to group by this column. Defaults to false.
request.columns[].headerText string Text used to identify this column in the report output; defaults to columnName or savedColumnName when not specified. This can be used to prevent collisions between DoubleClick Search columns and saved columns with the same name.
request.columns[].platformSource string The platform that is used to provide data for the custom dimension. Acceptable values are "floodlight".
request.columns[].productReportPerspective string Returns metrics only for a specific type of product activity. Accepted values are:
  • "sold": returns metrics only for products that were sold
  • "advertised": returns metrics only for products that were advertised in a Shopping campaign, and that might or might not have been sold
request.columns[].savedColumnName string Name of a saved column to include in the report. The report must be scoped at advertiser or lower, and this saved column must already be created in the DoubleClick Search UI.
request.columns[].startDate string Inclusive date in YYYY-MM-DD format. When provided, this overrides the overall time range of the report for this column only. Must be provided together with endDate.
request.downloadFormat string Format that the report should be returned in. Currently csv or tsv is supported.
request.filters[] list A list of filters to be applied to the report.

The maximum number of filters per request is 300.

request.filters[].column nested object Column to perform the filter on. This can be a DoubleClick Search column or a saved column.
request.filters[].column.columnName string Name of a DoubleClick Search column to include in the report.
request.filters[].column.customDimensionName string Segments a report by a custom dimension. The report must be scoped to an advertiser or lower, and the custom dimension must already be set up in DoubleClick Search. The custom dimension name, which appears in DoubleClick Search, is case sensitive.

If used in a conversion report, returns the value of the specified custom dimension for the given conversion, if set. This column does not segment the conversion report.

request.filters[].column.customMetricName string Name of a custom metric to include in the report. The report must be scoped to an advertiser or lower, and the custom metric must already be set up in DoubleClick Search. The custom metric name, which appears in DoubleClick Search, is case sensitive.
request.filters[].column.endDate string Inclusive day in YYYY-MM-DD format. When provided, this overrides the overall time range of the report for this column only. Must be provided together with startDate.
request.filters[].column.groupByColumn boolean Synchronous report only. Set to true to group by this column. Defaults to false.
request.filters[].column.headerText string Text used to identify this column in the report output; defaults to columnName or savedColumnName when not specified. This can be used to prevent collisions between DoubleClick Search columns and saved columns with the same name.
request.filters[].column.platformSource string The platform that is used to provide data for the custom dimension. Acceptable values are "floodlight".
request.filters[].column.productReportPerspective string Returns metrics only for a specific type of product activity. Accepted values are:
  • "sold": returns metrics only for products that were sold
  • "advertised": returns metrics only for products that were advertised in a Shopping campaign, and that might or might not have been sold
request.filters[].column.savedColumnName string Name of a saved column to include in the report. The report must be scoped at advertiser or lower, and this saved column must already be created in the DoubleClick Search UI.
request.filters[].column.startDate string Inclusive date in YYYY-MM-DD format. When provided, this overrides the overall time range of the report for this column only. Must be provided together with endDate.
request.filters[].operator string Operator to use in the filter. See the filter reference for a list of available operators.
request.filters[].values[] list A list of values to filter the column value against.

The maximum number of filter values per request is 300.

request.includeDeletedEntities boolean Determines if removed entities should be included in the report. Defaults to false. Deprecated, please use includeRemovedEntities instead.
request.includeRemovedEntities boolean Determines if removed entities should be included in the report. Defaults to false.
request.maxRowsPerFile integer Asynchronous report only. The maximum number of rows per report file. A large report is split into many files based on this field. Acceptable values are 1000000 to 100000000, inclusive.
request.orderBy[] list Synchronous report only. A list of columns and directions defining sorting to be performed on the report rows.

The maximum number of orderings per request is 300.

request.orderBy[].column nested object Column to perform the sort on. This can be a DoubleClick Search-defined column or a saved column.
request.orderBy[].column.columnName string Name of a DoubleClick Search column to include in the report.
request.orderBy[].column.customDimensionName string Segments a report by a custom dimension. The report must be scoped to an advertiser or lower, and the custom dimension must already be set up in DoubleClick Search. The custom dimension name, which appears in DoubleClick Search, is case sensitive.

If used in a conversion report, returns the value of the specified custom dimension for the given conversion, if set. This column does not segment the conversion report.

request.orderBy[].column.customMetricName string Name of a custom metric to include in the report. The report must be scoped to an advertiser or lower, and the custom metric must already be set up in DoubleClick Search. The custom metric name, which appears in DoubleClick Search, is case sensitive.
request.orderBy[].column.endDate string Inclusive day in YYYY-MM-DD format. When provided, this overrides the overall time range of the report for this column only. Must be provided together with startDate.
request.orderBy[].column.groupByColumn boolean Synchronous report only. Set to true to group by this column. Defaults to false.
request.orderBy[].column.headerText string Text used to identify this column in the report output; defaults to columnName or savedColumnName when not specified. This can be used to prevent collisions between DoubleClick Search columns and saved columns with the same name.
request.orderBy[].column.platformSource string The platform that is used to provide data for the custom dimension. Acceptable values are "floodlight".
request.orderBy[].column.productReportPerspective string Returns metrics only for a specific type of product activity. Accepted values are:
  • "sold": returns metrics only for products that were sold
  • "advertised": returns metrics only for products that were advertised in a Shopping campaign, and that might or might not have been sold
request.orderBy[].column.savedColumnName string Name of a saved column to include in the report. The report must be scoped at advertiser or lower, and this saved column must already be created in the DoubleClick Search UI.
request.orderBy[].column.startDate string Inclusive date in YYYY-MM-DD format. When provided, this overrides the overall time range of the report for this column only. Must be provided together with endDate.
request.orderBy[].sortOrder string The sort direction, which is either ascending or descending.
request.reportScope object The reportScope is a set of IDs that are used to determine which subset of entities will be returned in the report. The full lineage of IDs from the lowest scoped level desired up through agency is required.
request.reportScope.adGroupId long DS ad group ID.
request.reportScope.adId long DS ad ID.
request.reportScope.advertiserId long DS advertiser ID.
request.reportScope.agencyId long DS agency ID.
request.reportScope.campaignId long DS campaign ID.
request.reportScope.engineAccountId long DS engine account ID.
request.reportScope.keywordId long DS keyword ID.
request.reportType string Determines the type of rows that are returned in the report. For example, if you specify reportType: keyword, each row in the report will contain data about a keyword. See the Types of Reports reference for the columns that are available for each type.
request.rowCount integer Synchronous report only. The maximum number of rows to return; additional rows are dropped. Acceptable values are 0 to 10000, inclusive. Defaults to 10000.
request.startRow integer Synchronous report only. Zero-based index of the first row to return. Acceptable values are 0 to 50000, inclusive. Defaults to 0.
request.statisticsCurrency string Specifies the currency in which monetary will be returned. Possible values are: usd, agency (valid if the report is scoped to agency or lower), advertiser (valid if the report is scoped to * advertiser or lower), or account (valid if the report is scoped to engine account or lower).
request.timeRange object If metrics are requested in a report, this argument will be used to restrict the metrics to a specific time range.
request.timeRange.changedAttributesSinceTimestamp datetime Inclusive UTC timestamp in RFC format, e.g., 2013-07-16T10:16:23.555Z. See additional references on how changed attribute reports work.
request.timeRange.changedMetricsSinceTimestamp datetime Inclusive UTC timestamp in RFC format, e.g., 2013-07-16T10:16:23.555Z. See additional references on how changed metrics reports work.
request.timeRange.endDate string Inclusive date in YYYY-MM-DD format.
request.timeRange.startDate string Inclusive date in YYYY-MM-DD format.
request.verifySingleTimeZone boolean If true, the report would only be created if all the requested stat data are sourced from a single timezone. Defaults to false.
rowCount integer The number of report rows generated by the report, not including headers.
rows[] list Synchronous report only. Generated report rows.
rows[].(key) any value Indicates the columns that are represented in this row. That is, each key corresponds to a column with a non-empty cell in this row.
statisticsCurrencyCode string The currency code of all monetary values produced in the report, including values that are set by users (e.g., keyword bid settings) and metrics (e.g., cost and revenue). The currency code of a report is determined by the statisticsCurrency field of the report request.
statisticsTimeZone string If all statistics of the report are sourced from the same time zone, this would be it. Otherwise the field is unset.

Methods

generate
Generates and returns a report immediately.
get
Polls for the status of a report request.
getFile
Downloads a report file encoded in UTF-8.
getIdMappingFile
Downloads a CSV file (encoded in UTF-8) that contains ID mappings between the previous Search Ads 360 and the new Search Ads 360. For the requested advertiser, the file includes all children entities (e.g. engine accounts, campaigns, ad groups, etc.) that exist in both the previous Search Ads 360 and the new Search Ads 360.
request
Inserts a report request into the reporting system.