Workflow Changes in the Google Ads API

Some of the general workflows from the AdWords API are changed in the Google Ads API. For example, searching for entities now uses a separate service from mutating.

Field names

In the AdWords API, there were separate fields for similar concepts on different entities, such as CampaignId and AdGroupId. In the Google Ads API, nested field names are now used, for example campaign.id and ad_group.id. You can nest further as well, for example ad_group.campaign.id.

Service use cases

In the AdWords API, all operations for a given entity type used the same service. The CampaignService was used to get (which included searching and filtering) and mutate.

In the Google Ads API, searching uses its own service, the GoogleAdsService. If you need a list of entities matching some criteria, always use this service to find a list of results. As in the AdWords API, calls to this service populate only the specifically requested fields in the response.

Get requests still exist in Google Ads API, on each entity's specific service. You can get campaign information from the CampaignService. However, this call serves a different purpose from the same call in the AdWords API. You cannot filter as part of a get request, but instead get all the details for a specified entity. You pass the entity's resource name as an identifier, and the response includes every field filled out without needing to list them all.

Mutate requests in the Google Ads API are also on the entity-specific service. You can affect one entity per operation, and can pass multiple operations in a single request, just like in the AdWords API.

Reporting

In the AdWords API, reporting was kept entirely separate from other services. In the Google Ads API, this is no longer the case. Use the GoogleAdsService (the same as is used for searching for entities) and simply include stats fields in your request to generate reports.

Other key differences between AdWords API and Google Ads API reporting are:

• Instead of report types in the AdWords API, you have resources such as campaign and resource views such as keyword_view in the Google Ads API.
• Reports in the Google Ads API do not return plain text or XML. Instead, the GoogleAdsService Search and SearchStream methods return GoogleAdsRows that contain objects. For example, when you retrieve campaign.id, campaign.name and metrics.clicks, you'll get back a GoogleAdsRow containing a campaign object with its id and name fields set, as well as a metrics object with its clicks field set.
• Rows for zero impressions are returned by default in the Google Ads API. There is no includeZeroImpressions parameter. If you want to exclude zero impression rows, use a predicate such as metrics.impressions > 0 in your Google Ads Query Language.
• The GoogleAdsFieldService is similar to the AdWords API ReportDefinitionService, but instead of returning metadata for report types, it returns metadata for resources and resource views.
• If the denominator value is zero for a ratio field, such as cost per conversion, the AdWords API returns a value of 0. The Google Ads API will return a value of null in this scenario to match the behavior in the Google Ads UI.
• Instead of having single attribution reports which can contain multiple criteria types in a single report, the Google Ads API relies on different reporting views for retrieving stats related to different criteria types. For example, you can make use of the keyword_view to retrieve data by keyword, or the product_group_view to retrieve data by product group. Thus, there is no longer a generic report that contains multiple criteria types; you can only get stats for a criteria type by looking up its view.