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
GoogleAdsService.SearchStreamreturns 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.Searchbreaks 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 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.
Process 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
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
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 may 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 things to keep in mind:
- A resource with an
UNKNOWNtype can be supported later or stay
- New objects with type
UNKNOWNcan 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
UNKNOWNresource may appear because of new activity in your account through other interfaces or because a resource becomes no longer formally supported.
UNKNOWNresources may have detailed metrics attached to them that you can query.
UNKNOWNresources are typically fully visible in the Google Ads UI.
UNKNOWNresources generally cannot be mutated.
The response would 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 would
contain one row for each combination of the following:
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