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).
| 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
You can filter and organize the data in your reports.
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, split the data by segments. For example, suppose you want to see the number of impressions specific to the Google Search Network separately from the Google Display Network. In that case, segment your report by network. See Segmentation on how to include segment fields in the SELECT clause.
Pagination
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.
Download formats
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 have to perform some post-processing. See this code example that shows how to implement CSV formatting in a client.
Schedule and email reports
You can schedule and email a report from the UI, but these features are 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 preceding table, 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"