January 13th 2021

When building accessible websites, the gold standard is thorough manual testing with a range of assistive technologies and browser combinations, as well as carefully considering the experience you are offering to other users who may not be using assistive technology.

However, it can be daunting knowing where to start, which areas of the site may be the most affected, or how to identify issues in the first place. In this tutorial I’ll show you how you can use the Wave API and Google Sheets to scrape your whole site for accessibility issues, so you can identify the most common issues on your site, the pages or templates most affected, and begin to prioritise which issues to fix first.

Note: The Wave API is great, but like any tool, it’s not a complete substitute to manual checks. I’d recommend using this analysis as a starting point for your accessibility improvements and working from there.

For this you will need:

  • Access to a crawler (I’ll be using Screaming Frog) or a list of all of the URLs you’d like to analyse.
  • Google Sheets, with the API Connector for Google Sheets (you can sign up for a free trial of the pro version) – preferably a copy of our free template.
  • API credits for the Wave API (you’ll use three credits per URL, per device. You’ll need to double the number of credits if you want to test your site again after you’ve implemented your fixes.)

Step 1: Crawl Your Site

In order to run the Wave API on our entire site, we first need to get a list of all URLs a user may encounter. I’m using Screaming Frog, to do this, but any crawler will work.

Step 2: Configure Your Wave API Requests

The next step is to work out what parameters you want to include in your API request, which will depend on what information you want to collect. The query parameters I’ll be using in this example are as follows (but feel free to play around using the Wave API documentation):

ParameterValue
keyYour parameter key (you’ll have been sent this when you signed up for the Wave API).
urlThe URL of the page on your site you want to assess.
reporttype2 will return the number of each error type per page. 3 will also return the XPath to help you find it on the page. You can use 4 to also include the CSS selector.
  • First, open a blank Google Sheet (or use our free template!)
  • In Sheet1, in the first column, paste “https://wave.webaim.org/api/request?”
  • In the second column, write ‘key=’
  • In the third column, paste in your API key
  • In the fourth column, write ‘&reporttype=’
  • In column five, enter the report type you’d like to use (I’ll use 2)
  • In column six, write ‘&url=’
  • In column 7 paste in the list of URLs from your crawl (these are the pages on your site you’d like to analyse)
  • Copy your values in columns 1-8 down to the end of your list of URLs (it should look something like this:).
template URLs tab with populated columns
  • Finally, in column 8, use the CONCATENATE function to combine the values in column 1-7 into a single URL (if you’re using our template it will do this for you). You should now have a list of URLs with the syntax:

https://wave.webaim.org/api/request?key=[APIKEY]&reporttype=[REPORTTYPE]&url=[YOURSITEURL]">https://wave.webaim.org/api/request?key=[APIKEY]&reporttype=[REPORTTYPE]&url=[YOURSITEURL]

Step 3: Set Up Your Requests with API Connector

The next step will be to set up the API Connector add-on so you can scrape your site. I’m going to assume you already have this installed in Google Sheets and you’ve created an account (with your 7 day free trial).

  • Open this add-on by going to Add-ons > API Connector > Open. You should see something like this:
API connector pop-up window
  • Hit ‘Add New’, which should open the ‘Requests’ tab.
  • Set the following parameters (leave the API URL path field blank for now):
MethodGet
Destination SheetResults (Don’t use set current as it will write over the URL list we created earlier. If you’re not using our template, make sure you create a second sheet to collect your results in)
Name and Save RequestYour API Call Name (e.g. ‘Erudite Accessibility’)
  • Next we’re going to point the API Connector to the list of URLs we created earlier. To do this, we need a list of cell references for the API Connector to use to find the URLs you just created (if you’re using our template you’ll find a ready made list in the tab ‘Cell List’), which you’ll paste into the ‘API URL path’ field with the following syntax:

+++URLs!H1+++
+++URLs!H2+++

+++URLs!H3+++
+++URLs!H4+++

etc.

API connector pop-up window with API URL path field populated with URL list and destination sheet set to 'Results'.
  • Finally, we need to add some output settings to make sure the data collected is presented in a usable format. You want to set the output mode to ‘Overwrite’, and the report style to ‘default (single row)’:
Output settings populated. Output mode = overwrite, report style = default (single row).
  • Save your request so you can use it again to retest.

Step 4: Run Your API Requests

To run your API requests, simply hit ‘Run’ in the API Connector window. You should see the ‘Results’ sheet being populated with your results.

And there you have it! You should now have a table of accessibility issues across your whole site, which you can use to identify the worst affected pages and most prevalent errors. If you need support with implementation, check out our Introduction to Web Accessibility or Web Accessibility Tips articles, or feel free to contact me on jess.james@erudite.agency.