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](https://developers.google.com/adsense/management/metrics-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](https://developers.google.com/adsense/management/reporting/date_ranges) instead.

## Filter Operators

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

<br />

| 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` |

<br />

## 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.
**Example:**

Country code is (US OR UK) AND product code is AFC:  

`filters=COUNTRY_CODE%3D%3DUS,COUNTRY_CODE%3D%3DUK&filters=PRODUCT_CODE%3D%3DAFC`

## Next steps

- [Choosing the Right Dimension](https://developers.google.com/adsense/management/reporting/right_dimension)
- [Running Large Reports](https://developers.google.com/adsense/management/reporting/large_reports)
- [List of Metrics and Dimensions](https://developers.google.com/adsense/management/metrics-dimensions)