How to migrate from Google’s AdWords API to the new Google Ads API
By CASPER CRAUSE
And ARBEN KQIKU
With Google having recently announced the sunset date for the AdWords API, those using it for retrieving data must switch over to the new Google Ads API.
Google recently announced that it will be retiring the AdWords API on April 27, 2022. After this date, advertisers using the API to retrieve data from their Google Ads campaigns will no longer receive vital performance analytics or the means to scale operations like bid management. This poses a concern to those who use automated scripts that rely on the legacy API. In this guide, we will explain how to migrate to the new API, as well as benefit from its new functions and features.
What has changed?
The legacy API allowed advertisers to choose between different report types depending on their requirements. For example, they could create campaign performance reports to measure performance at a campaign level, or ad group performance reports to measure performance at the ad group level. By contrast, the new Google Ads API has resources that are available for query, rather than performance reports. As such, if an advertiser wants to access the data related to campaigns, they would query the campaigns resource rather than the campaign performance report.
How does the new API work?
The original AdWords API uses its own query language, called the AdWords Query Language (AWQL), for querying the API. The new API, however, uses a modern programmatic interface based on the Google Ads Query Language (GAQL). This language is used for sending queries via the Google Ads API for resources and related attributes, segments, and metrics using the Google Ads Service. In practical terms, this means automated scripts must be rewritten to use the new query language for them to work with the new API.
How to build queries for the new API
Building these queries requires subject matter expertise. Fortunately, there are resources for assisting developers, such as the official Google Ads API documentation. There is also a new Query Builder tool to help developers quickly build new queries. Here’s how we can set up a new query from scratch using the tool:
- Choose a resource name you’d like to query, such as campaign. The query builder will then display a list of all the fields, segments, and metrics associated with that resource.
- Now, we can choose between the different tabs at the top of the form, such as select, where, order by, limit, and parameters.
- Expand the desired tab to reveal a list of checkable boxes, such as attribute resource fields, segments, and metrics. Ticking a checkbox will build your GAQL query.
With some experimentation, you will garner a better understanding of how to segment and filter out unwanted resources and order your results using the select, where, order by, and limit tabs. Your final results should look something like this:
You can also use the Query Builder tool to carry out a quick check of syntax and structure, but you will need to use the Query Validator tool to ensure the query is legitimate. Let’s imagine we want to validate the query from the screen capture above. Simply copy it into the clipboard, navigate to the Query Validator, and paste it into the dialog. The validator will let you know if there are any issues with your query.
Do I need to rewrite all of the old AWQL queries?
The good news is that you do not need to rewrite all your old AWQL queries from the legacy API from scratch. Since the naming conventions between the two APIs are quite different, by far the quickest and most efficient approach is to use the migration tool. This lets you input the original AWQL query, whereupon it will be automatically converted into a new GAQL query. If the conversion is successful, the output will appear green. Here is a practical example of how we can use the migration tool. In this example, we will use a Google Ads Script to select the campaign names containing a specific campaign label and compare the output between the old and the new API.- Select your Google Ads account ID.
2. Select a query written in the old AdWords AWQL query language
With the old AdWords API, the code should look something like this:
With the new AdWords API, the code should look something like this:
3. Gather together all the rows of that query. Note that in the example below, we use AdsApp.report() and report.rows() to achieve the desired result in the old API.
In the new Google Ads API, the code is more succinct and should look like this:
4. Create a container and push all of the rows into it. With he old AdWords API, the result should look something like this:
At this point, there will still be rows left, so we need to create a new variable, called row, and grab the campaign name from it to push into the allCampaigns container. This process differs slightly from using the Google Ads API, as the resources are their own objects. For example, campaign.name becomes two separate entities – firstly campaign followed by name.
You can enter the data retrieved by both APIs in two separate columns in a Google Sheets or Excel spreadsheet and then compare their outputs. If the conversion process worked properly, the results should be identical between the two APIs.
What happens if I fail to migrate to the new API?
Anyone using the legacy AdWords API to retrieve data must migrate to the Google Ads API by the sunset date. From April 27, 2022, all requests to the old API will fail, leaving advertisers unable to retrieve crucial data-driven insights into the performance of their Google Ads campaigns. This poses a significant challenge to those who rely heavily on automated scripts for scaling operations like performance reporting, bid management, and split testing. That being said, Google has made it fairly straightforward to migrate queries over to the new API. This also allows advertisers to enjoy the unique benefits of upgrading, which include the ability to extend and scale their reporting capabilities with a more intuitive query language. The Google Ads API also has a steady release schedule, regularly rolling out new features and fixes to keep it in line with Google’s latest standards. If you are still struggling to make sense of the new API, comtogether can help you migrate your scripts to ensure you never miss out on crucial insights. Get in touch today to learn more.You want to learn more about Google Ads ? Discover our Whitepaper ! 👇