Filtering

The filters query string parameter restricts the data returned in an AdSense Management API report. When you use the filters parameter, you supply a dimension you want to filter on, followed by the filter expression.

Filtered queries restrict the rows that get included in the result. Each row in the result is tested against the filter: if the filter matches, the row is retained and if it doesn't match, the row is dropped.

URL Encoding: The client libraries automatically encode the filter operators. However, if you make requests directly to the protocol, you must explicitly encode filter operators as indicated in the table below.
Filtering priority: Filtering occurs before any dimensions are aggregated, so that the returned metrics represent the total for only the relevant dimensions.

Filter Syntax

A single filter uses the form:

name operator expression

In this syntax:

name — the name of the dimension on which to filter. For example: AD_CLIENT_ID will filter on the ad client ID.
operator — defines the type of filter match to use.
expression — states the values included in the results.

All dimensions that apply to the metrics being reported on can be used as filters, with the exception of the date-related dimensions (DATE, WEEK, and MONTH). To filter by date, specify the date range for the report instead.

Filter Operators

There are two filter operators. The operators must be URL encoded in order to be included in URL query strings.

Operator	Description	URL Encoded Form	Example
`==`	Exact match	`%3D%3D`	Aggregate metrics where the country name is Canada: `filters=COUNTRY_NAME%3D%3DCanada`
`=@`	Contains substring	`%3D@`	Aggregate metrics where the country name contains United, this matches United States and United Kingdom for example: `filters=COUNTRY_NAME%3D@United`

Filter Expressions

There are a couple of important rules for filter expressions:

URL-reserved characters — Characters such as & must be url-encoded in the usual way. Client libraries take care of this for you, so you only have to worry about this encoding if you are making direct calls to the protocol.
Reserved characters — The comma and backslash must be backslash escaped when they appear in an expression.
- backslash \\
- comma \,

Note: Make sure you escape backslashes before commas, in order to avoid double escaping.

Combining Filters

Filters can be combined using OR and AND boolean logic.

OR logic

OR logic is defined using a comma (,) inside the filter expression.

Example: (each must be URL encoded)

Country code is either (US OR UK):
COUNTRY_CODE==US,COUNTRY_CODE==UK

AND logic

AND logic is achieved by providing multiple filter parameters, which translates into providing an array of filters in the client libraries.

Example:

Country code is US AND product code is AFC:
filters=COUNTRY_CODE%3D%3DUS&filters=PRODUCT_CODE%3D%3DAFC

Combining AND and OR logic

It's possible to combine AND and OR logic into a single expression.

Note: Each filter is evaluated individually before all filters are combined into an AND logical expression.