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.
A single filter uses the form:
name operator expression
In this syntax:
- name — the name of the dimension on which to filter.
AD_CLIENT_IDwill 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 (
MONTH). To filter by date, specify the
date range for the report instead.
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|
||Aggregate metrics where the country name is Canada:
||Aggregate metrics where the country name contains United, this
matches United States and United Kingdom for example:
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.
Note: Make sure you escape backslashes before commas, in order to avoid double escaping.
Filters can be combined using
OR logic is defined using a comma (
,) inside the
Example: (each must be URL encoded)
Country code is either (US OR UK):
AND logic is achieved by providing multiple filter parameters,
which translates into providing an array of filters in the client libraries.
Country code is US AND product code is AFC:
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.
Country code is (US OR UK) AND product code is AFC: