Feasibility of an AdWords API Translation Layer

Stay organized with collections Save and categorize content based on your preferences.

When migrating, you may wonder if it is feasible to create a shim or translation layer between the AdWords API and the Google Ads API in order to save development time and preserve legacy code, especially given the common carryover concepts.

This is not an effective use of development resources for the following reasons:

  • There are important semantic differences between the AdWords API and the Google Ads API that complicate a translation layer.

  • The AdWords API has been stable for close to ten years. We expect similar longevity for the Google Ads API which therefore merits a one-time migration.

  • The AdWords API was based on the legacy Google AdWords UI, which has since been deprecated. The Google Ads API is more analogous to the new Google Ads UI.

  • The shim would have to be updated any time the underlying Google Ads API changes. This incurs additional maintenance costs which are difficult to predict, especially if the changes break prior assumptions about AdWords API functionality.

  • New features will be rolling out at a faster pace. By being constrained by the legacy AdWords API, a shim layer will either have to invent custom ways to surface new functionality, or not take advantage of new features. If you require RMF compliance, there are potential compliance implications.

  • The two APIs can be used concurrently, even in the same process, which simplifies incremental migration to the new platform.

  • The AdWords API has limited data type information due to XML encoding. The Google Ads API is strongly typed, so prior assumptions made on specific data types, such as a double value, may break prior code.

Semantic Differences

The following aspects have the greatest semantic differential between the two APIs:

Object Definition and Hierarchy
In creating a new API for the foreseeable future, we took the opportunity to make several improvements to the object structure, including hierarchy and attributes. There is no 1:1 mapping of AdWords API objects to Google Ads API objects. For example, the BudgetOrderService will be significantly different.
The AdWords API provides separate reporting and management functionality. All Google Ads API reporting data are returned as metrics like any other field in a query that may also contain management information. This unification may reduce code complexity in many applications.
The AdWords API reports return data in CSV format, where complex objects are converted to a string representation. A common example is CriteriaParameters which requires parsing to extract relevant data about each criterion. In contrast, the Google Ads API returns full-fledged objects along with reporting metrics. With a shim, you'd have to choose the lowest common denominator (the AdWords API approach) and as a result, you'd miss out on the significant advantages of the unified management plus reporting features of the Google Ads API.
Query Languages
While there are relatively minor differences in query language syntax, there are significant semantic differences in resource names, field names, and enums. Certain AdWords API services have been split or recombined into different Google Ads API services.
Fine grained account management
The Google Ads API has much finer control over manager account hierarchies by using the login-customer-id. All calls to the Google Ads API that use OAuth credentials from a manager account must include this information, which is handled easily by the client libraries. Not using this new feature may affect billing and privacy issues.

Specific Services

The following AdWords API services have greatly changed or been entirely replaced:

Underlying Transport and Encoding

The AdWords API uses SOAP / XML as its transport protocol. The Google Ads API client libraries use gRPC and efficiently encoded protocol buffers.

The new mechanism should be more efficient when transferring large volumes of data. Depending on the assumptions made by the calling program with regard to network retries, error handling, HTTP proxies, and other network dependencies, there may be non-trivial differences in behavior to be accounted for in the shim layer.


Building a shim layer may appear initially appealing but in practice is likely to cost more and cause more problems than a one-time migration to the Google Ads API.