GoogleAdsService is the unified object retrieval and reporting service
of the Google Ads API. The service has a single search method that:
- Retrieves specific attributes of objects.
- Retrieves performance statistics for objects based on a date range.
- Orders objects based on their attributes.
- Uses conditions to indicate which objects you want returned in the response.
- Uses paging to break up large responses into manageable pages of results.
- Limits the number of objects returned.
Making a request
The search method requires a
consists of the following attributes:
- A Google Ads Query Language
querythat indicates which resource to query, the attributes, segments, and metrics to retrieve, and the conditions to use to restrict which objects are returned.
page_sizeto indicate how many objects to return in a single response when using paging.
- An optional
page_tokento retrieve the next batch of results when using paging.
For more information on the Google Ads Query Language, check out the Google Ads Query Language guide.
Processing a response
GoogleAdsService search request returns a
SearchGoogleAdsResponse, which consists of
the following attributes:
total_results_countthat indicates the total number of
GoogleAdsRowobjects in the query's result set.
next_page_tokenfor requesting the next batch of results from the result set.
field_maskthat indicates which fields you requested in the
SELECTclause of your query.
Paging through results
Whenever you are retrieving a large number of objects, you'll want to specify
page_size in your request. This will break up the result set of the query
into multiple responses that each contain up to
For example, if your account contains 50,000 keywords, the result set for the
following query will contain 50,000
SELECT ad_group.id, ad_group_criterion.type, ad_group_criterion.criterion_id, ad_group_criterion.keyword.text, ad_group_criterion.keyword.match_type FROM ad_group_criterion WHERE ad_group_criterion.type = KEYWORD
To avoid receiving a single response containing all rows in the result set, you
can specify a
1000 so that the Google Ads API will return only the
first one thousand rows in the first response, along with a
To retrieve the next one thousand rows, simply send the request again, but
update the request's
page_token to the response's
Understanding the GoogleAdsRow
GoogleAdsRow represents an object returned by a query, and consists of a set
of attributes that are populated based on the fields requested in the
For example, the response for the criteria query above will contain a
GoogleAdsRow objects with the following attributes populated:
ad_group id ad_group_criterion type criterion_id keyword text match_type
For example, although an
ad_group_criterion has a
status attribute, the
status field of the row's
ad_group_criterion attribute will not be populated
in a response for the query above because the
SELECT clause does not include
ad_group_criterion.status. Similarly, the
campaign attribute of the row
will not be populated because the
SELECT clause does not include any fields
The response will contain one
GoogleAdsRow for each combination of the
- instance of the main resource specified in the
- value of each selected
For example, the response for a query that selects
FROM campaign and has
date in the
SELECT clause will contain one row for
each combination of the following: