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) 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.
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 stayUNKNOWN
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. TheUNKNOWN
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.