This guide maps the concepts and naming conventions for reports in the Google Ads UI
to the reports that you can generate using the 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)
.
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 would segment your report by network. See
Segmentation
on how to include segment fields
in the SELECT clause.
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.
Paging through results is available when retrieving reports with
GoogleAdsService.Search
through
next_page_token
. To fetch the entire result set
without any pagination, use
GoogleAdsService.SearchStream
.
Order results
In the UI, you can order results by selecting a column.
In GAQL, you can use the
ORDER BY
clause
and
LIMIT
clause
to order your query result.
In the UI, reports can be downloaded in various formats, such as CSV, TSV, or
XML.
The API doesn't directly support different formats in its output, so you would
need to perform some post-processing. See a
code example showing how to implement CSV formatting in a
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.
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
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:
SELECT campaign.name
FROM campaign
WHERE campaign.status != "REMOVED"