Filtering data

To filter data in the report, use the Filter structure. Each filter is a set of criteria for selecting data. Filters are combined with AND, so the report shows data that meets all the filter criteria. A filter consists of three parameters:

  • Field: Which field to compare the values of.

  • Operator: How to compare.

  • Values: An array of symbols to compare with.

For example, to make the report only show rows that have more than 10 conversions, use the filter

"Filter": [{
  "Field": "Conversions",
  "Operator": "GREATER_THAN",
  "Values": ["10"]
}]

The table below shows how operators correspond to fields.

Field name Operators allowed
AdNetworkType EQUALS, IN
CampaignId
CampaignType
ClientLogin 1
AdFormat EQUALS, IN, NOT_EQUALS, NOT_IN
AdGroupId
AdId
Age 2
AudienceTargetId 3
CarrierType
ClickType
CriteriaType
CriterionType
Device
DynamicTextAdTargetId 3
ExternalNetworkName
Gender
IncomeGrade
LocationOfPresenceId
MatchType
MobilePlatform
Placement
RlAdjustmentId 4
Slot
SmartAdTargetId 3
TargetingCategory
TargetingLocationId
Clicks EQUALS, IN, GREATER_THAN, LESS_THAN
Conversions
ImpressionReach
Impressions
AvgClickPosition GREATER_THAN, LESS_THAN
AvgCpc 5
AvgCpm 5
AvgEffectiveBid 5
AvgImpressionFrequency
AvgImpressionPosition
AvgPageviews
AvgTrafficVolume
BounceRate
ConversionRate
Cost 5
CostPerConversion 5
Ctr
GoalsRoi
Profit 5
Revenue 5
WeightedCtr
WeightedImpressions
Keyword 3 EQUALS, IN, NOT_EQUALS, NOT_IN, STARTS_WITH_IGNORE_CASE, STARTS_WITH_ANY_IGNORE_CASE, DOES_NOT_START_WITH_IGNORE_CASE, DOES_NOT_START_WITH_ALL_IGNORE_CASE
MatchedKeyword
Query
Field name Operators allowed
AdNetworkType EQUALS, IN
CampaignId
CampaignType
ClientLogin 1
AdFormat EQUALS, IN, NOT_EQUALS, NOT_IN
AdGroupId
AdId
Age 2
AudienceTargetId 3
CarrierType
ClickType
CriteriaType
CriterionType
Device
DynamicTextAdTargetId 3
ExternalNetworkName
Gender
IncomeGrade
LocationOfPresenceId
MatchType
MobilePlatform
Placement
RlAdjustmentId 4
Slot
SmartAdTargetId 3
TargetingCategory
TargetingLocationId
Clicks EQUALS, IN, GREATER_THAN, LESS_THAN
Conversions
ImpressionReach
Impressions
AvgClickPosition GREATER_THAN, LESS_THAN
AvgCpc 5
AvgCpm 5
AvgEffectiveBid 5
AvgImpressionFrequency
AvgImpressionPosition
AvgPageviews
AvgTrafficVolume
BounceRate
ConversionRate
Cost 5
CostPerConversion 5
Ctr
GoalsRoi
Profit 5
Revenue 5
WeightedCtr
WeightedImpressions
Keyword 3 EQUALS, IN, NOT_EQUALS, NOT_IN, STARTS_WITH_IGNORE_CASE, STARTS_WITH_ANY_IGNORE_CASE, DOES_NOT_START_WITH_IGNORE_CASE, DOES_NOT_START_WITH_ALL_IGNORE_CASE
MatchedKeyword
Query

1 Filter by ClientLogin

In the ClientLogin filter, you can specify only the client usernames available to the manager account.

  • If the filter is not set for the field, the username from the Client-Login HTTP header is used by default. If the header is missing, the username is taken from the OAuth token.
  • If the filter for the ClientLogin field exists, the maximum number of rows in the report is 500,000 (the same value is used by default).

2 Filter by Age

In the Age field, statistics for periods up through 21.08.2018 output the AGE_45 value, and after this date the values AGE_45_54 and AGE_55 are shown.

To get statistics for all users age 45 and over regardless of the report period, we recommend specifying all three values in the Age filter:

"Filter": [{
  "Field": "Age",
  "Operator": "IN",
  "Values": ["AGE_45", "AGE_45_54", "AGE_55"]
}]

If not all of these age segments are specified in the filter, the statistics for the period that includes the date 21.08.2018 may be incomplete. For example, if only the values AGE_45_54 and AGE_55 are specified, the report will not include users whose age group is defined as AGE_45.

If the filter specifies AGE_45 and does not specify AGE_45_54 and AGE_55, the report won't be generated for a period after 21.08.2018 and an error message will be returned.

3 Filters for targeting criteria

The following fields aren't output to the report. They are only used for filtering data. These fields are mutually exclusive: only one of them can be present in the Filter array.

Field Description Comment
Keyword The keyword text. The keyword text is shown in the Criterion field in the report, and the keyword ID is shown in the CriterionId field.
AudienceTargetId ID of the audience target. See the section Audience targets (AudienceTarget).

The ID of the audience target is shown in the CriterionId field. The Criterion field shows the name of the retargeting list.

Filtering by AudienceTargetId is available for data starting from December 8, 2017.

DynamicTextAdTargetId The ID of the dynamic text ad target, or the ID of the filter for dynamic ads. See the section Ad target for dynamic ads (DynamicTextAdTarget — Webpage). The ID of the dynamic text ad target is shown in the CriterionId field in the report, and the name is shown in the Criterion field.
SmartAdTargetId The ID of the filter for smart banners.

The ID of the smart banner filter is shown in the CriterionId field in the report, and the name is shown in the Criterion field.

Field Description Comment
Keyword The keyword text. The keyword text is shown in the Criterion field in the report, and the keyword ID is shown in the CriterionId field.
AudienceTargetId ID of the audience target. See the section Audience targets (AudienceTarget).

The ID of the audience target is shown in the CriterionId field. The Criterion field shows the name of the retargeting list.

Filtering by AudienceTargetId is available for data starting from December 8, 2017.

DynamicTextAdTargetId The ID of the dynamic text ad target, or the ID of the filter for dynamic ads. See the section Ad target for dynamic ads (DynamicTextAdTarget — Webpage). The ID of the dynamic text ad target is shown in the CriterionId field in the report, and the name is shown in the Criterion field.
SmartAdTargetId The ID of the filter for smart banners.

The ID of the smart banner filter is shown in the CriterionId field in the report, and the name is shown in the Criterion field.

4 Filter for RlAdjustmentId

The RIAdjustmentId filter can have the value NONE, which means that bid adjustments for a target audience weren't applied.

In particular, if you only want the report to show data with bid adjustments for a target audience, use this filter:

"Filter": [{
  "Field": "RlAdjustmentId",
  "Operator": "NOT_EQUALS",
  "Values": ["NONE"]
}]

5 Filters for monetary values

All monetary values in filters should be specified as integers: the amount in the currency, multiplied by 1,000,000 (regardless of the returnMoneyInMicros: false header).