Retrieving objects

  • The GoogleAdsService is used to retrieve objects and performance statistics from the Google Ads API.

  • It provides methods to retrieve specific attributes, performance metrics, order objects, apply conditions, and limit results.

  • Results can be returned through streaming (SearchStream) for large datasets or paging (Search) for smaller, manageable pages.

  • Requests require a customer ID and a Google Ads Query Language query.

  • Responses consist of GoogleAdsRow objects, where each row represents an object and contains populated attributes based on the query's SELECT clause.

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 might be more appropriate if your batch application wants to download as much data as fast as possible.
  • GoogleAdsService.Search breaks up large responses into manageable pages of results. This could be more appropriate if your interactive application displays a page of results at a time.

Learn more about paging versus streaming.

Make 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) 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.

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

UNKNOWN enum types

Resources that are returned with a type of UNKNOWN are not fully supported in that API version. These resources could have been created through other interfaces such as the Google Ads UI. You can select metrics when a resource has a type of UNKNOWN, but you cannot mutate the resource through the API. An example of this would be a new campaign or ad being introduced in the UI, but not supported in the API version you are querying.

Here are some considerations to keep in mind:

  • A resource with an UNKNOWN type can be supported later or stay UNKNOWN indefinitely.
  • New objects with type UNKNOWN can appear at any time. These objects are backward compatible because the enum value is already available. Resources are introduced with this change as they're available so that you have an accurate view of your account. The UNKNOWN resource can appear due to new activities in your account through other interfaces, or when a resource is no longer supported.
  • UNKNOWN resources can have detailed metrics attached to them that are queryable.
  • UNKNOWN resources are typically fully visible in the Google Ads UI.
  • UNKNOWN resources generally cannot be mutated.

Segmentation

The response would 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 would contain one row for each combination of the following:

  • campaign
  • segments.ad_network_type
  • segments.date

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

results in one row per campaign, not one row per distinct value of the campaign.status field.

Previous
Changing objects
Next
Resource metadata