The 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.
The GoogleAdsService
can return results in two
ways:
GoogleAdsService.SearchStream
returns 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.Search
will 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 versus streaming.
Making a request
The search method requires a
SearchGoogleAdsRequest
, which consists of the
following attributes:
- A
customer_id
. - A Google Ads Query Language
query
that indicates which resource to query, the attributes, segments, and metrics to retrieve, and the conditions to use to restrict which objects are returned. - (
GoogleAdsService.Search
only) Apage_size
to indicate how many objects to return in a single response when using paging. - (
GoogleAdsService.Search
only) An optionalpage_token
to 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
The GoogleAdsService
returns a list of
GoogleAdsRow
objects.
Each 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
SELECT
clause. Attributes not included in the SELECT
clause are not
populated on the GoogleAdsRow
objects in the response.
For example, although an ad_group_criterion
has a status
attribute, the
status
field of the row's ad_group_criterion
attribute is not populated
in a response for a query where the SELECT
clause does not include
ad_group_criterion.status
. Similarly, the campaign
attribute of the row is
not populated if the SELECT
clause does not include any fields from the
campaign
resource.
Each GoogleAdsRow
can have different attributes and metrics from another row
in the same result set; so the rows should be viewed as objects rather than
fixed rows of a table.
Segmentation
The response will contain one GoogleAdsRow
for each combination of the
following:
- instance of the main resource specified in the
FROM
clause - value of each selected
segment
field
For example, the response for a query that selects FROM campaign
and has
segments.ad_network_type
and segments.date
in the SELECT
clause will
contain one row for each combination of the following:
campaign
segments.ad_network_type
segments.date