Retrieving Objects

Objective: Understand how to retrieve objects and performance stats using GoogleAdsService.

The 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.

Key Point: If you are migrating from the AdWords API, you can think of GoogleAdsService as a combination of the object management services and the reporting service.

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.
• A page_size to indicate how many objects to return in a single response when using paging.
• An optional page_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

A GoogleAdsService search request returns a SearchGoogleAdsResponse, which consists of the following attributes:

• A results collection of GoogleAdsRow objects.
• A total_results_count that indicates the total number of GoogleAdsRow objects in the query's result set.
• A next_page_token for requesting the next batch of results from the result set.
• A field_mask that indicates which fields you requested in the SELECT clause of your query.

Paging through results

Whenever you are retrieving a large number of objects, you'll want to specify the page_size in your request. This will break up the result set of the query into multiple responses that each contain up to page_size objects.

For example, if your account contains 50,000 keywords, the result set for the following query will contain 50,000 GoogleAdsRow objects:

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 page_size of 1000 so that the Google Ads API will return only the first one thousand rows in the first response, along with a next_page_token. To retrieve the next one thousand rows, simply send the request again, but update the request's page_token to the response's next_page_token.

Note: The next_page_token will not be populated on the response that contains the last batch of rows.

Understanding the GoogleAdsRow

A 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.

For example, the response for the criteria query above will contain a collection of GoogleAdsRow objects with the following attributes populated:

ad_group
  id
ad_group_criterion
  type
  criterion_id
  keyword
    text
    match_type

Key Point: Attributes not included in the SELECT clause will not be 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 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 the campaign resource.

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

Note: Results are implicitly segmented by each instance of the main resource, not by the values of the individual fields selected. For example, SELECT campaign.status, metrics.impressions FROM campaign WHERE segments.date DURING LAST_14_DAYS will result in one row per campaign, not one row per distinct value of the campaign.status field.

Next steps

• Learn how to retrieve API metadata.
• Continue to the series on the Google Ads Query Language.