Note: Version v201902 will be sunset soon. All users of those versions must migrate to a newer one.

type ReportQuery (v201905)

A ReportQuery object allows you to specify the selection criteria for generating a report. Only reports with at least one Column are supported.


Namespace
https://www.google.com/apis/ads/publisher/v201905

Field

dimensions

Dimension[]

The list of break-down types being requested in the report. The generated report will contain the dimensions in the same order as requested. This field is required.


Enumerations
MONTH_AND_YEAR
Breaks down reporting data by month and year in the network time zone. Can be used to filter on month using ISO 4601 format 'YYYY-MM'.

Note: In v201802 and later, this dimension is compatible with the following time zone types:

  • TimeZoneType.PUBLISHER
  • TimeZoneType.PROPOSAL_LOCAL

Corresponds to "Month and year" in the Ad Manager UI. Compatible with any of the following report types: Historical, Future sell-through, Reach, Sales, Partner finance.

WEEK
Breaks down reporting data by week of the year in the network time zone. Cannot be used for filtering.

Note: In v201802 and later, this dimension is compatible with the following time zone types:

  • TimeZoneType.PUBLISHER
  • TimeZoneType.PROPOSAL_LOCAL

Corresponds to "Week" in the Ad Manager UI. Compatible with any of the following report types: Historical, Future sell-through, Reach, Sales, Data protection.

DATE
Breaks down reporting data by date in the network time zone. Can be used to filter by date using ISO 8601's format 'YYYY-MM-DD'".

Note: In v201802 and later, this dimension is compatible with the following time zone types:

  • TimeZoneType.PUBLISHER
  • TimeZoneType.PROPOSAL_LOCAL

Corresponds to "Date" in the Ad Manager UI. Compatible with any of the following report types: Historical, Future sell-through, Reach, Sales.

DAY
Breaks down reporting data by day of the week in the network time zone. Can be used to filter by day of the week using the index of the day (from 1 for Monday is 1 to 7 for Sunday).

Corresponds to "Day of week" in the Ad Manager UI. Compatible with any of the following report types: Historical, Future sell-through, Reach, Sales.

HOUR
Breaks down reporting data by hour of the day in the network time zone. Can be used to filter by hour of the day (from 0 to 23).

Corresponds to "Hour" in the Ad Manager UI. Compatible with any of the following report types: Historical, Reach.

LINE_ITEM_ID
Breaks down reporting data by LineItem.id. Can be used to filter by LineItem.id.

Compatible with any of the following report types: Historical, Future sell-through, Reach, Sales, Data protection.

LINE_ITEM_NAME
Breaks down reporting data by line item. LineItem.name and LineItem.id are automatically included as columns in the report. Can be used to filter by LineItem.name.

Corresponds to "Line item" in the Ad Manager UI. Compatible with any of the following report types: Historical, Future sell-through, Reach, Sales, Data protection.

LINE_ITEM_TYPE
Breaks down reporting data by LineItem.lineItemType. Can be used to filter by line item type using LineItemType enumeration names.

Corresponds to "Line item type" in the Ad Manager UI. Compatible with any of the following report types: Historical, Future sell-through, Reach, Data protection.

ORDER_ID
Breaks down reporting data by Order.id. Can be used to filter by Order.id.

Compatible with any of the following report types: Historical, Future sell-through, Reach, Sales, Data protection.

ORDER_NAME
Breaks down reporting data by order. Order.name and Order.id are automatically included as columns in the report. Can be used to filter by Order.name.

Corresponds to "Order" in the Ad Manager UI. Compatible with any of the following report types: Historical, Future sell-through, Reach, Sales, Data protection.

ORDER_DELIVERY_STATUS
Delivery status of the order. Not available as a dimension to report on, but exists as a dimension in order to filter on it using PQL. Valid values are 'STARTED', 'NOT_STARTED' and 'COMPLETED'.

Compatible with any of the following report types: Historical, Reach.

ADVERTISER_ID
Breaks down reporting data by advertising company Company.id. Can be used to filter by Company.id.

Compatible with any of the following report types: Historical, Future sell-through, Reach, Sales, Data protection.

ADVERTISER_NAME
Breaks down reporting data by advertising company. Company.name and Company.id are automatically included as columns in the report. Can be used to filter by Company.name.

Corresponds to "Advertiser" in the Ad Manager UI. Compatible with any of the following report types: Historical, Future sell-through, Reach, Sales, Data protection.

AD_NETWORK_ID
The network that provided the ad for SDK ad mediation.

If selected for a report, that report will include only SDK mediation ads and will not contain non-SDK mediation ads.

SDK mediation ads are ads for mobile devices. They have a list of ad networks which can provide ads to serve. Not every ad network will have an ad to serve so the device will try each network one-by-one until it finds an ad network with an ad to serve. The ad network that ends up serving the ad will appear here. Note that this id does not correlate to anything in the companies table and is not the same id as is served by ADVERTISER_ID.

Compatible with any of the following report types: Historical, Reach.

AD_NETWORK_NAME
The name of the network defined in AD_NETWORK_ID.

Corresponds to "Ad network name" in the Ad Manager UI. Compatible with any of the following report types: Historical, Reach.

SALESPERSON_ID
Breaks down reporting data by salesperson User.id. Can be used to filter by User.id.

Compatible with any of the following report types: Historical, Future sell-through, Reach, Sales, Data protection.

SALESPERSON_NAME
Breaks down reporting data by salesperson. User.name and User.id of the salesperson are automatically included as columns in the report. Can be used to filter by User.name.

Corresponds to "Salesperson" in the Ad Manager UI. Compatible with any of the following report types: Historical, Future sell-through, Reach, Sales, Data protection.

CREATIVE_ID
Breaks down reporting data by Creative.id or creative set id (master's Creative.id) if the creative is part of a creative set. Can be used to filter by Creative.id.

Compatible with any of the following report types: Historical, Reach, Data protection.

CREATIVE_NAME
Breaks down reporting data by creative. Creative.name and Creative.id are automatically included as columns in the report. Can be used to filter by Creative.name.

Corresponds to "Creative" in the Ad Manager UI. Compatible with any of the following report types: Historical, Reach, Data protection.

CREATIVE_TYPE
Breaks down reporting data by creative type.

Corresponds to "Creative type" in the Ad Manager UI. Compatible with any of the following report types: Historical, Reach.

CREATIVE_BILLING_TYPE
Breaks down reporting data by creative billing type.

Corresponds to "Creative billing type" in the Ad Manager UI. Compatible with any of the following report types: Historical, Reach.

CUSTOM_EVENT_ID
Breaks down reporting data by custom event ID.

Compatible with any of the following report types: Historical, Reach.

CUSTOM_EVENT_NAME
Breaks down reporting data by custom event name.

Corresponds to "Custom event" in the Ad Manager UI. Compatible with any of the following report types: Historical, Reach.

CUSTOM_EVENT_TYPE
Breaks down reporting data by custom event type (timer/exit/counter).

Corresponds to "Custom event type" in the Ad Manager UI. Compatible with any of the following report types: Historical, Reach.

CREATIVE_SIZE
Breaks down reporting data by Creative.size. Cannot be used for filtering.

Corresponds to "Creative size" in the Ad Manager UI. Compatible with any of the following report types: Historical, Reach.

AD_UNIT_ID
Breaks down reporting data by AdUnit.id. Can be used to filter by AdUnit.id. AD_UNIT_NAME, i.e. AdUnit.name, is automatically included as a dimension in the report.

Compatible with any of the following report types: Historical, Future sell-through, Reach, Sales.

AD_UNIT_NAME
Breaks down reporting data by ad unit. AdUnit.name and AdUnit.id are automatically included as columns in the report. Can be used to filter by AdUnit.name.

Corresponds to "Ad unit" in the Ad Manager UI. Compatible with any of the following report types: Historical, Future sell-through, Reach, Sales.

PARENT_AD_UNIT_ID
Used to filter on all the descendants of an ad unit by AdUnit.id. Not available as a dimension to report on.

Compatible with any of the following report types: Historical, Future sell-through, Reach, Sales.

PARENT_AD_UNIT_NAME
Used to filter on all the descendants of an ad unit by AdUnit.name. Not available as a dimension to report on.

Compatible with any of the following report types: Historical, Future sell-through, Reach, Sales.

PLACEMENT_ID
Breaks down reporting data by Placement.id. Can be used to filter by Placement.id.

Compatible with any of the following report types: Historical, Future sell-through, Reach.

PLACEMENT_NAME
Breaks down reporting data by placement. Placement.name and Placement.id are automatically included as columns in the report. Can be used to filter by Placement.name.

Corresponds to "Placement" in the Ad Manager UI. Compatible with any of the following report types: Historical, Future sell-through, Reach.

PLACEMENT_STATUS
Status of the placement. Not available as a dimension to report on, but exists as a dimension in order to filter on it using PQL. Can be used to filter on Placement.status by using InventoryStatus enumeration names.

Compatible with any of the following report types: Historical, Future sell-through, Reach.

TARGETING
Breaks down reporting data by criteria predefined by Ad Manager like the operating system, browser etc. Cannot be used for filtering.

Corresponds to "Targeting" in the Ad Manager UI. Compatible with any of the following report types: Historical, Reach.

DEVICE_CATEGORY_ID
The ID of the device category to which an ad is being targeted. Can be used to filter by device category ID.

Compatible with any of the following report types: Historical, Reach.

DEVICE_CATEGORY_NAME
The category of device (smartphone, feature phone, tablet, or desktop) to which an ad is being targeted. Can be used to filter by device category name.

Corresponds to "Device category" in the Ad Manager UI. Compatible with any of the following report types: Historical, Reach.

COUNTRY_CRITERIA_ID
Breaks down reporting data by country criteria ID. Can be used to filter by country criteria ID.

Compatible with any of the following report types: Historical, Future sell-through, Reach.

COUNTRY_NAME
Breaks down reporting data by country name. The country name and the country criteria ID are automatically included as columns in the report. Can be used to filter by country name using the US English name.

Corresponds to "Country" in the Ad Manager UI. Compatible with any of the following report types: Historical, Future sell-through, Reach.

REGION_CRITERIA_ID
Breaks down reporting data by region criteria ID. Can be used to filter by region criteria ID.

Compatible with any of the following report types: Historical, Reach.

REGION_NAME
Breaks down reporting data by region name. The region name and the region criteria ID are automatically included as columns in the report. Can be used to filter by region name using the US English name.

Corresponds to "Region" in the Ad Manager UI. Compatible with any of the following report types: Historical, Reach.

CITY_CRITERIA_ID
Breaks down reporting data by city criteria ID. Can be used to filter by city criteria ID.

Compatible with any of the following report types: Historical, Reach.

CITY_NAME
Breaks down reporting data by city name. The city name and the city criteria ID are automatically included as columns in the report. Can be used to filter by city name using the US English name.

Corresponds to "City" in the Ad Manager UI. Compatible with any of the following report types: Historical, Reach.

METRO_CRITERIA_ID
Breaks down reporting data by metro criteria ID. Can be used to filter by metro criteria ID.

Compatible with any of the following report types: Historical, Reach.

METRO_NAME
Breaks down reporting data by metro name. The metro name and the metro criteria ID are automatically included as columns in the report. Can be used to filter by metro name using the US English name.

Corresponds to "Metro" in the Ad Manager UI. Compatible with any of the following report types: Historical, Reach.

POSTAL_CODE_CRITERIA_ID
Breaks down reporting data by postal code criteria ID. Can be used to filter by postal code criteria ID.

Compatible with any of the following report types: Historical, Reach.

POSTAL_CODE
Breaks down reporting data by postal code. The postal code and the postal code criteria ID are automatically included as columns in the report. Can be used to filter by postal code.

Corresponds to "Postal code" in the Ad Manager UI. Compatible with any of the following report types: Historical, Reach.

CUSTOM_TARGETING_VALUE_ID
Breaks down reporting data by CustomTargetingValue.id. Can be used to filter by CustomTargetingValue.id.

Compatible with any of the following report types: Historical, Reach, Sales.

CUSTOM_CRITERIA
Breaks down reporting data by custom criteria. The CustomTargetingValue is displayed in the form: CUSTOM_TARGETING_VALUE_ID, i.e. CustomTargetingValue.id is automatically included as a column in the report. Cannot be used for filtering; use CUSTOM_TARGETING_VALUE_ID instead.

When using this Dimension, metrics for freeform key values are only reported on when they are registered with CustomTargetingService.

Corresponds to "Key-values" in the Ad Manager UI. Compatible with any of the following report types: Historical, Reach, Sales.

ACTIVITY_ID
Breaks down reporting data by activity ID. Can be used to filter by activity ID.

Compatible with any of the following report types: Historical, Reach.

ACTIVITY_NAME
Breaks down reporting data by activity. The activity name and the activity ID are automatically included as columns in the report. Can be used to filter by activity name.

Corresponds to "Activity" in the Ad Manager UI. Compatible with any of the following report types: Historical, Reach.

ACTIVITY_GROUP_ID
Breaks down reporting data by activity group ID. Can be used to filter by activity group ID.

Compatible with any of the following report types: Historical, Reach.

ACTIVITY_GROUP_NAME
Breaks down reporting data by activity group. The activity group name and the activity group ID are automatically included as columns in the report. Can be used to filter by activity group name.

Corresponds to "Activity group" in the Ad Manager UI. Compatible with any of the following report types: Historical, Reach.

CONTENT_ID
Breaks down reporting data by Content.id. Can be used to filter by Content.id.

Compatible with any of the following report types: Historical, Future sell-through, Reach.

CONTENT_NAME
Breaks down reporting data by content. Content.name and Content.id are automatically included as columns in the report. Can be used to filter by Content.name.

Corresponds to "Content" in the Ad Manager UI. Compatible with any of the following report types: Historical, Future sell-through, Reach.

CONTENT_BUNDLE_ID
Breaks down reporting data by ContentBundle.id. Can be used to filter by ContentBundle.id.

Compatible with any of the following report types: Historical, Future sell-through, Reach.

CONTENT_BUNDLE_NAME
Breaks down reporting data by content bundle. ContentBundle.name and ContentBundle.id are automatically included as columns in the report. Can be used to filter by ContentBundle.name.

Corresponds to "Content bundle" in the Ad Manager UI. Compatible with any of the following report types: Historical, Future sell-through, Reach.

VIDEO_METADATA_KEY_ID
Breaks down reporting data by CustomTargetingKey.id.

Compatible with any of the following report types: Historical, Reach.

VIDEO_METADATA_KEY_NAME
Breaks down reporting data by custom targeting key. CustomTargetingKey.name and CustomTargetingKey.id are automatically included as columns in the report.

Corresponds to "Metadata key" in the Ad Manager UI. Compatible with any of the following report types: Historical, Reach.

CONTENT_HIERARCHY
Breaks down reporting data by the content hierarchy. To use this dimension, a list of custom targeting key IDs must be specified in ReportQuery.contentMetadataKeyHierarchyCustomTargetingKeyIds.

This dimension can be used as a filter in the Statement in PQL syntax: CONTENT_HIERARCHY_CUSTOM_TARGETING_KEY[keyId]_ID = custom targeting value ID

For example: WHERE CONTENT_HIERARCHY_CUSTOM_TARGETING_KEY[4242]_ID = 53423

VIDEO_FALLBACK_POSITION
Breaks down reporting data by the fallback position of the video ad, i.e., NON_FALLBACK, FALLBACK_POSITION_1, FALLBACK_POSITION_2, etc. Can be used for filtering.

Corresponds to "Fallback position" in the Ad Manager UI. Compatible with any of the following report types: Historical, Reach.

POSITION_OF_POD
Breaks down reporting data by the position of the video ad within the video stream, i.e., UNKNOWN_POSITION, PREROLL, POSTROLL, UNKNOWN_MIDROLL, MIDROLL_1, MIDROLL_2, etc. UNKNOWN_MIDROLL represents a midroll, but which specific midroll is unknown. Can be used for filtering.

Corresponds to "Position of pod" in the Ad Manager UI. Compatible with any of the following report types: Historical, Reach.

POSITION_IN_POD
Breaks down reporting data by the position of the video ad within the pod, i.e., UNKNOWN_POSITION, POSITION_1, POSITION_2, etc. Can be used for filtering.

Corresponds to "Position in pod" in the Ad Manager UI. Compatible with any of the following report types: Historical, Reach.

VIDEO_REDIRECT_THIRD_PARTY
Breaks down reporting data by video redirect vendor.

Corresponds to "Video redirect third party" in the Ad Manager UI. Compatible with any of the following report types: Historical, Reach.

VIDEO_VAST_VERSION
Breaks down reporting data by vast version type name.

Corresponds to "VAST version" in the Ad Manager UI. Compatible with any of the following report types: Historical, Reach.

PARTNER_MANAGEMENT_PARTNER_ID
Breaks down reporting data by partner Company.id.

Compatible with any of the following report types: Historical, Reach, Partner finance.

PARTNER_MANAGEMENT_PARTNER_NAME
Breaks down reporting data by partner Company.name and Company.id are automatically included as columns in the report.

Corresponds to "Partner" in the Ad Manager UI. Compatible with any of the following report types: Historical, Reach, Partner finance.

PARTNER_MANAGEMENT_PARTNER_LABEL_ID
Breaks down reporting data by partner label Label.id.

Compatible with any of the following report types: Historical, Reach, Partner finance.

PARTNER_MANAGEMENT_PARTNER_LABEL_NAME
Breaks down reporting data by partner label. Label.name and Label.id are automatically included as columns in the report.

Corresponds to "Partner label" in the Ad Manager UI. Compatible with any of the following report types: Historical, Reach, Partner finance.

PARTNER_MANAGEMENT_ASSIGNMENT_ID
Breaks down reporting data by partner assignment id.

Compatible with any of the following report types: Historical, Reach, Partner finance.

PARTNER_MANAGEMENT_ASSIGNMENT_NAME
Breaks down reporting data by partner assignment name. ParnterAssignment name and id are automatically included as columns in the report.

Corresponds to "Assignment" in the Ad Manager UI. Compatible with any of the following report types: Historical, Reach, Partner finance.

GRP_DEMOGRAPHICS
Breaks down reporting data by gender and age group, i.e., MALE_13_TO_17, MALE_18_TO_24, MALE_25_TO_34, MALE_35_TO_44, MALE_45_TO_54, MALE_55_TO_64, MALE_65_PLUS, FEMALE_13_TO_17, FEMALE_18_TO_24, FEMALE_25_TO_34, FEMALE_35_TO_44, FEMALE_45_TO_54, FEMALE_55_TO_64, FEMALE_65_PLUS, UNKNOWN_0_TO_17 and UNKNOWN. Whenever this dimension is selected, COUNTRY_NAME must be selected.

This dimension is supported only for GRP columns.

Can correspond to any of the following in the Ad Manager UI: Demographics, comScore vCE demographics. Compatible with any of the following report types: Historical, Reach.

AD_REQUEST_AD_UNIT_SIZES
Breaks down reporting data by the ad unit sizes specified in ad requests.

Formatted as comma separated values, e.g. "300x250,300x250v,300x60".

This dimension is supported only for sell-through columns.

Corresponds to "Ad request sizes" in the Ad Manager UI. Compatible with any of the following report types: Historical, Future sell-through, Reach.

AD_REQUEST_CUSTOM_CRITERIA
Breaks down reporting data by the custom criteria specified in ad requests.

Formatted as comma separated key-values, where a key-value is formatted as key1=value_1|...|value_n,key2=value_1|...|value_n,....

This dimension is supported only for sell-through columns.

Corresponds to "Key-values" in the Ad Manager UI. Compatible with any of the following report types: Historical, Future sell-through, Reach.

IS_FIRST_LOOK_DEAL
Whether the report contains only Ad Exchange traffic fulfilled by First Look Deals or omits it. If this filter isn't included, the report will include First Look Deals traffic in addition to any other traffic. This filter can only be used with the string values "true" and "false". Not available as a dimension to report on.

Compatible with any of the following report types: Historical, Reach.

YIELD_GROUP_ID
Breaks down reporting data by yield group ID.

Compatible with any of the following report types: Historical, Reach.

YIELD_GROUP_NAME
Breaks down reporting data by yield group name.

Corresponds to "Yield group" in the Ad Manager UI. Compatible with any of the following report types: Historical, Reach.

YIELD_PARTNER
Breaks down reporting data by yield partner.

Corresponds to "Yield partner" in the Ad Manager UI. Compatible with any of the following report types: Historical, Reach.

YIELD_PARTNER_TAG
Breaks down reporting data by the tag of a yield partner in a yield group.

Corresponds to "Yield partner tag" in the Ad Manager UI. Compatible with any of the following report types: Historical, Reach.

MEDIATION_TYPE
Breaks down reporting data by mediation type. A mediation type can be web, mobile app or video.

Corresponds to "Mediation type" in the Ad Manager UI. Compatible with any of the following report types: Historical, Reach.

NATIVE_TEMPLATE_ID
Breaks down reporting data by native template (also known as creative template) ID.

Compatible with any of the following report types: Historical, Reach.

NATIVE_TEMPLATE_NAME
Breaks down reporting data by native template (also known as creative template) name.

Corresponds to "Native ad format name" in the Ad Manager UI. Compatible with any of the following report types: Historical, Reach.

NATIVE_STYLE_ID
Breaks down reporting data by native style ID.

Compatible with any of the following report types: Historical, Reach.

NATIVE_STYLE_NAME
Breaks down reporting data by native style name.

Corresponds to "Native style name" in the Ad Manager UI. Compatible with any of the following report types: Historical, Reach.

MOBILE_APP_NAME
Breaks down reporting data by mobile app name. Can be used for filtering.

Corresponds to "App names" in the Ad Manager UI. Compatible with any of the following report types: Historical, Reach.

MOBILE_DEVICE_NAME
Breaks down reporting data by device name. Can be used for filtering.

Corresponds to "Devices" in the Ad Manager UI. Compatible with any of the following report types: Historical, Reach.

MOBILE_INVENTORY_TYPE