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 is recommended if your application downloads full result sets or processes rows as a stream.
  • GoogleAdsService.Search breaks up large responses into manageable pages of results. This is useful if your interactive application displays a page of results at a time.

Learn more about paging versus streaming.

Make a request

GoogleAdsService.SearchStream expects a SearchGoogleAdsStreamRequest, and GoogleAdsService.Search expects a SearchGoogleAdsRequest. Both request types include:

  • 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

Depending on the method, the request also supports method-specific fields:

  • SearchGoogleAdsStreamRequest (SearchStream only):
  • SearchGoogleAdsRequest (Search only):
    • An optional page_token to retrieve the next batch of results when using paging (page_size is fixed at 10,000 rows; setting page_size in the request throws a RequestError.PAGE_SIZE_NOT_SUPPORTED error)
    • An optional search_settings message to configure return_summary_row, return_total_results_count, and omit_results
    • An optional validate_only boolean to validate the query without executing it

For more information on Google Ads Query Language, check out the Google Ads Query Language guide.

Process a response

The GoogleAdsService returns a list of GoogleAdsRow objects (either inside streamed SearchGoogleAdsStreamResponse batches or in a paged SearchGoogleAdsResponse).

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 and UNSPECIFIED enum types

Resources that are returned with an enum value of UNKNOWN are not fully supported in that API version, whereas UNSPECIFIED indicates that an enum field has not been set or was not requested in the SELECT clause. Resources with an UNKNOWN enum value 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 campaign or ad type available in the UI that is 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 in a later API version or stay UNKNOWN indefinitely.
  • New objects with type UNKNOWN can appear at any time. These objects are backward-compatible because the UNKNOWN enum value is present on every enum in the API. Resources are returned with UNKNOWN so that you have an accurate view of your account's overall performance metrics.
  • 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 through the API.

Segmentation

The response contains one GoogleAdsRow for each combination of the following:

  • Instance of the main resource specified in the FROM clause
  • Value of each selected segments 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 contains 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