Filtered Reports

The new Search Ads 360 Reporting API is now available. The new API provides enhanced flexibility to build custom reports and integrate the data into your reporting applications and processes. Learn more about migrating to and using the new Search Ads 360 Reporting API.

By default, your report will contain all of the data within the reportScope that your request specifies. If you want a report to contain only the data that matches a set of criteria, you can add one or more filters to a report. Only rows that satisfy all filters are returned.

For example, you can request a report of all the keywords in an agency. Then you can specify a filter so that only keywords with landing page URLs starting with www.example.com and www.another-example.com appear in the report.

"filters": [
  {
    "column" : { "columnName": "keywordLandingPage" },
    "operator" : "startsWith",
    "values" : [
      "http://www.example.com",
      "http://www.another-example.com"
    ]
  }
]

Each filter specifies a column to be filtered, an operator, and a list of values that are expected to be in the specified column:

"filters": [
  {
   "column" : column to filter on,
   "operator" : operator specifying the type of filter,
   "values" : list of values
  },
  { ... another filter can go here ... }
]
Note: Some columns cannot be filtered. In the Types of Reports reference, each column indicates if it is Filterable.

Filter operators

All filters are case sensitive. That is, a filter with "www.Sprockets.com" will not match a column that contains "www.sprockets.com".

Operator Description Number of values supported
equals The column must exactly match the specified value. 1
notEquals The column must not match the specified value. 1
in

The column must exactly match one of the values in the filter's list.

Not valid for list data types (such as String list).

variable
lessThan

The column must contain a value that is less than the specified value.

If you specify this filter for a Boolean column, the Search Ads 360 API converts false to a numeric value of 0 and true to 1. If you specify this filter for a String column, the API compares the lexicographic order.

Not valid for list data types (such as String list).

 1
greaterThan

The column must contain a value that is greater than one of the values in the filter's list.

If you specify this filter for a Boolean column, the API converts false to a numeric value of 0 and true to 1. If you specify this filter for a String column, the API compares the lexicographic order.

Not valid for list data types (such as String list).

1
lessThanOrEqual

The column must contain a value that is less than or equal to one of the values in the filter's list.

If you specify this filter for a Boolean column, the API converts false to a numeric value of 0 and true to 1. If you specify this filter for a String column, the API compares the lexicographic order.

Not valid for list data types (such as String list).

1
greaterThanOrEqual

The column must contain a value that is greater than or equal to one of the values in the filter's list.

If you specify this filter for a Boolean column, the API converts false to a numeric value of 0 and true to 1. If you specify this filter for a String column, the API compares the lexicographic order.

Not valid for list data types (such as String list).

1
isNull The column must be empty. For example, if you specify isNull for the keywordMaxCpc column in a keyword report, the report will contain only keywords that have not specified a Max CPC. 0
isNotNull The column must contain a value. 0
startsWith

The column must start with one of the strings in the filter's list.

Only valid for String columns.

variable
containsSubstring

The column must contain all or part of one of the strings specified in the filter's list.

For example, a containsSubstring filter with the values:
["ham", "cheese"]
would return rows with this value:
hamburger
cheeseburger

but would not return rows with these values:
lobster roll
lettuce
high amplitude (high amplitude includes the substring "h am", but all characters—including spaces—are evaluated by the filter)

Only valid for String columns.

variable
doesNotContainSubstring

The column must not contain any of the strings in the filter's list.

For example, a doesNotContainSubstring filter with the values:
["ham", "cheese"]
would return rows with this value:
lobster roll
lettuce

but would not return rows with these values:
hamburger
cheeseburger

Only valid for String columns.

variable
containsElement

The column must contain at least one of values in the filter's list. Only valid for columns with list data types (such as String list).

For example in a campaign report, a containsElement filter with the values:
["foo", "bar"]
filtering on the effectiveLabels column would only return campaigns labeled with foo, bar, or both.

variable