GoogleAdsService is the unified object
retrieval and reporting service of the Google Ads API. The service has methods that:
- Retrieve specific attributes of objects.
- Retrieve performance metrics for objects based on a date range.
- Order objects based on their attributes.
- Use conditions to indicate which objects you want returned in the response.
- Limit the number of objects returned.
GoogleAdsService can return results in two
GoogleAdsService.SearchStreamreturns all rows in a single streaming response which is more efficient for large (greater than 10,000 rows) result sets. This may be more appropriate if your batch application wants to download as much data as fast as possible.
GoogleAdsService.Searchwill break up large responses into manageable pages of results. This may be more appropriate if your interactive application displays a page of results at a time.
Learn more about paging vs. streaming.
Making a request
The search method requires a
SearchGoogleAdsRequest, which consists of the
- 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.
GoogleAdsService.Searchonly) 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
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 collection
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 from
GoogleAdsRow may have different attributes and metrics from another row
in the same result set. Since each row is an object, the set of rows should not
be considered like a table with a fixed structure.
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
segments.date in the
SELECT clause will
contain one row for each combination of the following: