API Structure

Objective: Get introduced to the primary components that make up the Google Ads API.

Resources

The Google Ads API consists of resources and services. A resource represents a Google Ads entity.

Examples of resources:

• Customer
• Campaign
• AdGroup

Each resource is uniquely identified by a resource_name string, that concatenates the resource and its parents into a path. For instance, campaign resource names have the form:

customers/customer_id/campaigns/campaign_id

So for a campaign with ID 987654 in the Google Ads account with customer ID 1234567, the resource_name would be:

customers/1234567/campaigns/987654

Services

Services retrieve and manipulate Google Ads entities. There are three types:

Modify (mutate) objects

These services modify instances of an associated resource type using a mutate request. They also supply a get request that retrieves a single resource instance, which can be useful for examining the structure of a resource.

Examples of services:

• CustomerService for modifying customers.

• CampaignService for modifying campaigns.

• AdGroupService for modifying ad groups.

Get objects and performance stats

GoogleAdsService is the single, unified service for retrieving objects and performance statistics.

Key Point: This is an important difference between the Google Ads API and the AdWords API.

In the AdWords API, you had to use one set of services to retrieve objects, and another service to retrieve performance statistics.

In the Google Ads API, this functionality is combined under GoogleAdsService.

All Search and SearchStream requests for GoogleAdsService require a query that specifies the resource to query, the resource attributes and performance metrics to retrieve, the predicates to use for filtering the request, and the segments to use to further break down your performance statistics. For more information about the format of the query, check out the Google Ads Query Language guide.

Retrieve metadata

GoogleAdsFieldService retrieves metadata about resources in the Google Ads API, such as the available attributes for a resource and its data type.

This service provides information you'll need in constructing a query to GoogleAdsService. For convenience, the information returned by GoogleAdsFieldService is also available in the fields reference documentation.

Key Point: If you are migrating from the AdWords API, think of GoogleAdsFieldService as a combination of ReportDefinitionService and the list of selector fields in the AdWords API.

Note: Check out this talk about Services and Resources from the Google Ads API Spring 2019 Workshop.