Reports in the UI

This guide maps the concepts and naming conventions for reports in the Google Ads UI to the reports that you can generate using Google Ads Query Language (GAQL) and the Google Ads API.

Common UI terms

The following table summarizes some of the common terms used in the UI and their mappings to the Google Ads Query Language (GAQL).

UI GAQL
Columns Any resource, segment field or metric in the SELECT clause of a GAQL query.
Date Range Date ranges map to a WHERE clause filtering on segments.date.
Filters One or more conditions in the WHERE clause.
Segment fields Apply segmentation by including segment fields in your GAQL query.
Pagination Paging breaks up the result set of the query into multiple pages.

Columns

Columns in the UI are equivalent to Resource fields, Segment fields, and Metrics in GAQL.

Filtering

Date ranges

The Google Ads UI has a table displaying account statistics, and a drop-down menu to control the date range of these statistics. You have the same control in GAQL by filtering on segments.date in the WHERE clause of a GAQL query.

Filters

Filters in the UI are equivalent to one or more conditions in the WHERE clause of GAQL.

Segmentation

For more detailed statistics, you can split the data by segments. For example, you might be interested in seeing the number of impressions specific to the Google Search Network separately from the Google Display Network. In this case, you'll want to segment your report by network. See Segmentation on how to include segment fields in the SELECT clause.

Pagination

You navigate through your reports in the UI using the controls available at the bottom of each table of data, that let you switch pages and select the number of results to display from a defined set of sizes.

Retrieving reports with GoogleAdsService.Search lets to page through results using next_page_token in a manner similar to the UI.

However, you can also use GoogleAdsService.SearchStream to fetch entire result sets without using pagination.

Ordering

In the UI, you order results by a particular column by selecting a column. In GAQL, you can use the ORDER BY clause and LIMIT clause to modify your query result.

Download formats

Reports can be downloaded in the UI in various formats (csv, tsv, xml, etc.). The API does not support formatting or file output, you may want to extend either one of the following Reporting examples for your use case:

Here is an example in Ruby that shows how you can implement CSV formatting in your client:

Schedule and email reports

Scheduling and emailing a report is available in the UI, but is not supported in the API.

Predefined Reports

You can create a list of predefined reports in the Google Ads UI. Here's a list of the basic predefined reports and their matching GAQL Resource Name.

Basic Predefined Reports GAQL Resource Name
(Specify in the FROM clause)
Account customer
Campaign,
Campaign details		 campaign
Ad group,
Ad group details		 ad_group
Ad,
Final URL		 ad_group_ad
Search keyword keyword_view
Search terms search_term_view
Paid and organic paid_organic_search_term_view
Landing page landing_page_view
Expanded Landing page expanded_landing_page_view

As an example from the table above, you can use the following GAQL to generate the Account report:

SELECT
  customer.descriptive_name,
  customer.id,
  metrics.clicks,
  metrics.impressions,
  metrics.ctr,
  metrics.average_cpc,
  metrics.cost_micros,
  metrics.absolute_top_impression_percentage,
  metrics.top_impression_percentage,
  metrics.average_cpm
FROM customer
WHERE segments.date DURING LAST_7_DAYS

To run the above GAQL in the API, refer to either one of the following Reporting examples:

Common differences

When comparing UI reports to API reports, one of the most common differences is that the UI implicitly filters out removed entities, whereas the API does not.

In order to replicate a default UI view, you need to add a filter (typically using a status field) to exclude removed rows.

For example, if fetching campaigns, you could use a query like this:

SELECT campaign.name
FROM campaign
WHERE campaign.status != "REMOVED"