Developer API v2 in AWR

We've released the AWR Developer API version 2!

And because some of you have been expecting it for a while, I thought I'd write a post to tell you a bit about the new functionalities.

First of all, if you're still using v1, don't worry. The first version of the developer API will not be discontinued, so you can go on using it just as before.

Still, I encourage you to check out v2 and find out a few more details before you make the switch.

Version 2 of the AWR Developer API has been designed to help you increase productivity and focus on what matters: your application. We’ve added a bunch of new features and improved existing ones, and we think you’ll be more than pleased with its new flexibility and capacity.

Some of the newly developed calls and operations were based on your suggestions and feedback. Before I go into a bit of detail on what these new features are, I want to thank you on behalf of the team for taking the time to send them in. I am sure some of you will recognize your own ideas in the paragraphs below. :)

So here’s what you’ll find in the new version:

New Calls for Search Console and Visibility Data

With the new version of the API, we aimed to extend the data provided for your projects. In addition to keyword ranking positions, now you can automatically get information from the Google Search Console account, as well as the Visibility values that AWR computes based on the keywords and search engines you’re tracking.

Historical Search Console data

As you know, the application can show you Google keyword data for a time frame longer than the 90-day standard. Your data is stored from the moment you make the connection between your AWR project and your Search Console account. The export will include Impressions, Clicks, Average Rank and CTR for the selected device and time frame.

To get historical Search Console data, the following calls are available:

• action=gwt_export: this schedules the data export to CSV and returns the get link for the export.

• action=get_gwt: the call starts the export file download.

Visibility data

Now you can easily export Visibility values from AWR into your own dashboards - there is no need to replicate the calculation formula anymore. Values can be directly retrieved with the new API call.

The export file will contain the Visibility values as explained here in our documentation, calculated for the main website and competitor websites monitored in the project on the targeted dates.

These are the new calls to get Visibility data:

• action=visibility_export: this schedules the data export to CSV and returns the get link for the export.

• action=get_visibility: the call starts the export file download.

Estimate & Request Ranking Updates On-demand

Since the on-demand update request feature is very important and useful to all our users, with the new version of the API we wanted to create more availability on that. We’ve added two new calls that were much needed in the previous version of the API.

Estimate resource consumption

First is the [estimate on demand] call which helps you see how many resources an on-demand update would consume from your quota. This allows you to see whether you’ve still got enough resources before actually requesting the data refresh.

Manually request rankings

Now you can request on demand rankings data for your application. The call is simple and straightforward: [on demand] - it pushes the actual rankings update for your projects.

As you know, there are two types of on-demand updates, depending on the estimated completion time:

• slow (rankings are delivered within 7 days)

• fast (data is available within 24h)

Bulk Project Removal

Now you can remove projects from your account in bulk, so clean-up should be a much faster and tidier job. This is helpful when you run seasonal SEO campaigns, or temporary campaigns for marketing prospecting. So after these projects are done and you’ve exported your data, you can delete them all in one go.

Here’s how bulk project removal will look in v2:

The response you receive will include the list with the projects in the call, and the related status for each:

• 0 - for projects that were removed successfully from the account

• 15 - for projects that were already not available in the account

Support for Response Calls

API v2 offers you the possibility to receive a JSON response instead of plain text. But to cut things short, you can find the complete list of response codes available in the Response Messages section of the v2 documentation.

There, you’ll also find more technical details on the new calls integrated within the new API version.

New columns for existing reports

Here are some of the new data columns that will be included in your API:

• for [export ranking] - a new column called "Current Visits" was added. This reflects the value of organic visits from Google Analytics related to each keyword in the export. The correspondent view in the UI is Rankings - Keyword Rankings.

• for [topsites export] - a "Page" column was added. This shows the SERP page where the ranking URL was found for the result displayed. The corresponding view in the UI is Rankings - Website Ranking - Top Sites.

Support for add/ remove keyword groups to new/ existing keywords

This functionality is available when using the [update project] call. As a rule of thumb, the call helps you change the properties of inputs that you have in your project, but without changing the inputs themselves.

Let’s take an example where keyword “key_example” belongs to two keyword groups: “group_example”, and “group_example2”. To remove this keyword from the first group, and keep it assigned to the second group, the call would look like:

Thus, when updating this property of the keyword, only the supplied groups will be kept or added.

Other Changes in v2

There were a lot of new things we wanted to add to this version of the API, but we first wanted to focus on the features users like you have asked for - while adding some of our own ideas. To get a full view of the improvements, you’ll have to try out the API. But here’s some other changes you might like to know about right away:

Encode export content

Functionality has also been improved for v2 of the API.

If the websites you are tracking contain URLs with space characters, you may want to add &encodedurl=true in the export to CSV calls (export_ranking and export_topsites). This will ensure that the URLs are well encoded in the export files. For example, an URL like "http://www.test.com/url space" will be exported as http://www.test.com/url%20space in the cell.

Quotes inside cell values are escaped

All fields are enclosed in quotes now and delimited with commas according to standard CSV specifications. Quote characters within a field are escaped using a preceding quote. For example, 8” bar is encoded as “8” bar” in the CSV cell.

Among other details, we’ve also added a new optional parameter to the [export ranking] call, for CSV/ JSON file format. If the format is not provided in the export call, then the file is generated as CSV by default.

We really hope you’ll be delighted by these new improvements.

API v2 is available for monthly plans from Agency upwards, and for all yearly plans. Remember that you can still use v1 just as before, but we do recommend switching to v2 when you’re ready. You can always contact our Support team and they’ll be happy to assist you any way they can.

Now, over to you:

What do you think of the new improvements? Is there anything you hoped to see in V2 that we haven’t included?

I’d love to hear your thoughts on this and get your feedback!