https://developers.google.com/google-ads/api/docs/reporting/overview
This guide describes the steps necessary to create and submit a query to the Google Ads API to get back data. To get started, jump to the section that best fits your use case:
- Try a quick example
- Retrieve criteria performance metrics
- Learn about segmentation
- Find out how to handle zero impressions
- Learn about using labels to report on your data
- Learn about streaming your reporting data
- Learn about paging your data
- Learn about mapping UI reports to API usage
- Learn the syntax of the Google Ads Query Language
https://developers.google.com/google-ads/api/docs/reporting/criteria-metrics
In the AdWords API, you can retrieve performance data (metrics) for different criteria from various reports (e.g., the Keywords Performance Report or the Age Range Performance Report).
To provide similar functionality in Google Ads API, each criteria report is represented by a separate resource. For example, data similar to the Keywords Performance Report is available in the keyword_view resource. Unless absolutely necessary, *_view resources will only contain a resource_name field.
Google Ads API clients will need to specify corresponding ad_group_criterion or campaign_criterion fields if any criteria specific data needs to be fetched. This will allow Google Ads API clients to request ad_group_criterion or campaign_criterion fields and the *_view resource in the same request to the GoogleAdsService.SearchStream method.
SELECT
ad_group_criterion.keyword.text,
ad_group.name,
campaign.name,
metrics.impressions,
metrics.clicks,
metrics.ctr,
metrics.average_cpc
FROM keyword_view
WHERE segments.date DURING LAST_30_DAYS
https://developers.google.com/google-ads/api/docs/reporting/example
We now take a look at a common use case: summarizing the performance of an account over the last 30 days by campaign, segmented by device. The query for this report is as follows:
SELECT
campaign.name,
campaign.status,
segments.device,
metrics.impressions,
metrics.clicks,
metrics.ctr,
metrics.average_cpc,
metrics.cost_micros
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
To issue this request, pass the Google Ads Query Language statement above to the GoogleAdsService.SearchStream interface.
HTTP request URL
The request consists of an HTTP POST to the Google Ads API server at the following URL:
https://googleads.googleapis.com/v9/customers/{customer_id}/googleAds:searchStream
Complete HTTP request sample
Here is a complete example of the report definition above, enclosed in an HTTP POST request.
POST /v9/customers/{customer_id}/googleAds:searchStream HTTP/1.1
Host: googleads.googleapis.com
User-Agent: curl
Content-Type: application/json
Accept: application/json
Authorization: Bearer [Enter OAuth 2.0 access token here]
developer-token: [Enter developerToken here]
Parameters:
{
"query" : "SELECT campaign.name, campaign.status, segments.device,
metrics.impressions, metrics.clicks, metrics.ctr,
metrics.average_cpc, metrics.cost_micros
FROM campaign
WHERE segments.date DURING LAST_30_DAYS"
}
https://developers.google.com/google-ads/api/docs/query/overview
Here is the Google Ads Query Language grammar reference (in regular expression notation):
Query -> SelectClause FromClause WhereClause? OrderByClause? LimitClause? ParametersClause?
SelectClause -> SELECT FieldName (, FieldName)*
FromClause -> FROM ResourceName
WhereClause -> WHERE Condition (AND Condition)*
OrderByClause -> ORDER BY Ordering (, Ordering)*
LimitClause -> LIMIT PositiveInteger
ParametersClause -> PARAMETERS Literal = Value (, Literal = Value)*
Condition -> FieldName Operator Value
Operator -> = | != | > | >= | < | <= | IN | NOT IN |
LIKE | NOT LIKE | CONTAINS ANY | CONTAINS ALL |
CONTAINS NONE | IS NULL | IS NOT NULL | DURING |
BETWEEN | REGEXP_MATCH | NOT REGEXP_MATCH
Value -> Literal | LiteralList | Number | NumberList | String |
StringList | Function
Ordering -> FieldName (ASC | DESC)?
FieldName -> [a-z] ([a-zA-Z0-9._])*
ResourceName -> [a-z] ([a-zA-Z_])*
StringList -> ( String (, String)* )
LiteralList ->