WAVE API (version 3.1) Details

Using the API

API requests are made by sending a request to https://wave.webaim.org/api/request?key=yourAPIkey&url=yourURL.

The WAVE API is a shared service. To ensure optimal speed and availability to all users, please limit API calls to no more than 2 simultaneous requests, otherwise rate limiting may be implemented for your account. For faster analysis on unlimited URLs, check out the WAVE stand-alone API.

Query Parameters

NOTE: All parameters are optional unless specified.

Parameter	Meaning	Notes
key	Your API key. (REQUIRED)	The API key is provided to you after you register. It can be regenerated by logging in.
url	The full URL of the page to be analyzed. (REQUIRED)	The page must be publicly accessible (see authentication options below) in order to be analyzed. URLs must be URL encoded (e.g., ampersands, spaces, etc. escaped).
format	json or xml (Default=json)	The format in which results will be returned.
viewportwidth	integer (Default=1200)	Pixel width at which the page will be evaluated. This can be useful for testing pages at various responsive breakpoints. For emulating mobile devices, you may need to also define useragent.
evaldelay	integer (Default=250)	Number of milliseconds to wait after the last page request before evaluating the page. This can be better ensure that pages that are heavily manipulated via scripting area fully formed before being evaluated. This can be set to 0 for static pages or increased for very dynamic pages or pages loading from slow sources.
reporttype	1, 2, 3, or 4 (Default=1)	reporttype=1 (costs 1 API credit) will return only the WAVE statistics for the page being analyzed - the number of errors, contrast errors, alerts, features, ARIA elements, and structural elements. reporttype=2 (costs 2 API credits) will return the statistics above, as well as a listing of all WAVE items (e.g., types of errors and number of each) identified. reporttype=3 (costs 3 API credits) will return all of the above, as well as contrast data and the XPath of each element to which a WAVE item is associated. This can allow you to identify where in each page a particular issue occurs. reporttype=4 (costs 3 API credits) will return all of the above, as well as contrast data and the CSS Selector value of each element to which a WAVE item is associated. This can allow you to identify where in each page a particular issue occurs.
username	Username required for server authentication	If the page to be analyzed is password protected and uses standard authentication, WAVE can use the username and password to authenticate before checking the page.
password	Password required for server authentication	Please note that username and password are sent in plain text and are passed through the WAVE system to your domain. We recommend using https or using the WAVE Stand-alone API.
useragent	User agent string	By default, the API uses an up-to-date browser user agent string for a modern Chrome browser on Mac when requesting the page. This can be overridden here. In conjunction with viewportwidth, this can be helpful for emulating mobile browsers. Be sure to use a valid, URLencoded user agent string.

Result Parameters

The following result parameters are returned for reporttype=1 (or when no reporttype is specified)

Parameter	Meaning
status:success	Status of the API request (true or false). If false, a status:error message will be provided with error details.
status:httpstatuscode	Returned HTTP code (e.g., "200", "404", etc.) from the host server. This can be helpful for filtering out 404 or other error pages.
statistics:pagetitle	Title of the page.
statistics:pageurl	The URL of the page. Due to redirects, this may sometimes be different than the URL sent in the request.
statistics:time	Number of seconds required for WAVE to download and analyze the page.
statistics:creditsremaining	Number of WAVE API credits remaining on account
statistics:allitemcount	Sum of all categoryname:count items below, or number of distinct items returned by WAVE (must use reporttype=2+ to view them individually).
statistics:totalelements	Number of DOM elements in the page.
statistics:waveurl	The URL of the full online WAVE report.
categories:categoryname	Array of categories returned - error, contrast, alert, feature, structure, or aria
categories:categoryname:description	A brief description of the category.
categories:categoryname:count	Number of items in that category (e.g., categories:errors:count returns the number of errors detected).

In addition to all parameters above, the following result parameters are returned for reporttype=2

Parameter	Meaning
categories:categoryname:items	Array of items in that category (e.g., types of errors within the error category)
categories:categoryname:items:id	Distinct identifier for each item type. Example: categories:errors:items:alt_missing indicates the missing alternative text item is present.
categories:categoryname:items:id:count	The number of that particular item returned. (Example: categories:errors:items:alt_missing:count:7 indicates 7 missing alternative text items were found.
categories:categoryname:items:id:id	The distinct identifier for that item. This can be useful for looking up item details in the WAVE documentation.
categories:categoryname:items:id:description	A short description of the item. Additional details (what the item means, why it matters for accessibility, what to do about it, the WAVE algorithm, and WCAG 2 mappings) are available by querying the WAVE documentation using the item id.

In addition to all parameters above, the following result parameters are returned for reporttype=3

Parameter	Meaning
categories:categoryname:items:id:xpaths:xpath	Array of XPath values for each item of that type.
categories:contrast:items:contrast:contrastdata	Array of contrast information for each contrast item: WCAG contrast ratio, text foreground color hex value ("#" followed by 6 characters, or 8 characters if foreground opacity or alpha is present), text background color hex value ("#" followed by 6 characters), and true/false if the text is considered "large text" per WCAG's definition.

In addition to the reporttype=1 and reporttype=2 parameters above, the following result parameters are returned for reporttype=4

Parameter	Meaning
categories:categoryname:items:id:selectors:selector	Array of CSS selector values for each item of that type.
categories:contrast:items:contrast:contrastdata	Array of contrast information for each contrast item: WCAG contrast ratio, text foreground color, text background color, and true/false if the text is considered "large text" per WCAG's definition.

Examples

Basic Query

Query:

https://wave.webaim.org/api/request?key={yourAPIkey}&url=https://google.com/

Result:

Basic XML Query

Query:

https://wave.webaim.org/api/request?key={yourAPIkey}&format=xml&url=https://google.com/

Result:

<?xml version="1.0" encoding="UTF-8"?> <results> <status> <success>true</success> <httpstatuscode>200</httpstatuscode> </status> <statistics> <pagetitle>Google</pagetitle> <pageurl>https://google.com/</pageurl> <time>1.27</time> <creditsremaining>1487</creditsremaining> <allitemcount>21</allitemcount> <totalelements>234</totalelements> <waveurl> https://wave.webaim.org/report?url=https://google.com/ </waveurl> </statistics> <categories> <error> <description>Errors</description> <count>4</count> </error> <contrast> <description>Contrast Errors</description> <count>2</count> </contrast> <alert> <description>Alerts</description> <count>5</count> </alert> <feature> <description>Features</description> <count>1</count> </feature> <structure> <description>Structural Elements</description> <count>5</count> </structure> <aria> <description>ARIA</description> <count>4</count> </aria> </categories> </results>

Get Item Details

Query:

https://wave.webaim.org/api/request?key={yourAPIkey}&reporttype=2&url=https://google.com/

Result:

The results include all statistics, and also the types of WAVE items found and the count of each item type. Note that this request type will cost 2 API credits.

Get Item Details + XPaths

Query:

https://wave.webaim.org/api/request?key={yourAPIkey}&reporttype=3&url=https://google.com/

Result:

{ "status":{ "success":true, "httpstatuscode":200 }, "statistics":{ "pagetitle":"Google", "pageurl":"https://google.com/", "time":1.27, "creditsremaining":1487, "allitemcount":20, "totalelements":186, "waveurl":"https://wave.webaim.org/report?url=https://google.com/" }, "categories":{ "error":{ "description":"Errors", "count":4, "items":{ "language_missing":{ "id":"language_missing", "description":"Document language missing", "count":1, "xpaths":[ "#" ] }, "alt_spacer_missing":{ "id":"alt_spacer_missing", "description":"Spacer image missing alternative text", "count":1, "xpaths":[ "\/BODY[1]\/CENTER[1]\/SPAN[1]\/DIV[1]\/DIV[1]\/TABLE[1]\/TBODY[1]\/TR[2]\/TD[1]\/IMG[1]" ] }, "link_empty":{ "id":"link_empty", "description":"Empty link", "count":1, "xpaths":[ "\/BODY[1]\/DIV[1]\/DIV[1]\/DIV[1]\/DIV[2]\/OL[1]\/LI[3]\/A[1]" ] }, "label_missing":{ "id":"label_missing", "description":"Missing form label", "count":1, "xpaths":[ "\/BODY[1]\/TEXTAREA[1]" ] } } }, "contrast":{ "description":"Contrast Errors", "count":2, "items":{ "contrast":{ "id":"contrast", "description":"Very Low Contrast", "count":2, "xpaths":[ "\/BODY[1]\/DIV[1]\/DIV[1]\/DIV[1]\/DIV[1]\/OL[1]\/LI[1]\/A[1]", "\/BODY[1]\/DIV[1]\/DIV[1]\/DIV[1]\/DIV[1]\/OL[1]\/LI[2]\/A[1]" ], "contrastdata":[ [ 2.48, "#9a9aff", "#ffffff", false ], [ 2.81, "#9a9a9a", "#ffffff", true ] ] } } }, "alert":{ "description":"Alerts", "count":5, "items":{ "h1_missing":{ "id":"h1_missing", "description":"Missing first level heading", "count":1, "xpaths":[ "#" ] }, "title_redundant":{ "id":"title_redundant", "description":"Redundant title text", "count":1, "xpaths":[ "\/BODY[1]\/CENTER[1]\/DIV[1]\/A[1]\/IMG[1]" ] }, "label_title":{ "id":"label_title", "description":"Unlabeled form element with title", "count":1, "xpaths":[ "\/BODY[1]\/CENTER[1]\/FORM[1]\/TABLE[1]\/TBODY[1]\/TR[1]\/TD[2]\/DIV[1]\/INPUT[1]" ] }, "link_suspicious":{ "id":"link_suspicious", "description":"Suspicious link text", "count":1, "xpaths":[ "\/BODY[1]\/DIV[1]\/DIV[1]\/DIV[1]\/DIV[1]\/OL[1]\/LI[9]\/A[1]" ] }, "heading_skipped":{ "id":"heading_skipped", "description":"Skipped heading level", "count":1, "xpaths":[ "\/BODY[1]\/DIV[1]\/DIV[1]\/DIV[1]\/DIV[2]\/H2[1]" ] } } }, "feature":{ "description":"Features", "count":1, "items":{ "alt_link":{ "id":"alt_link", "description":"Linked image with alternative text", "count":1, "xpaths":[ "\/BODY[1]\/CENTER[1]\/DIV[1]\/A[1]\/IMG[1]" ] } } }, "structure":{ "description":"Structural Elements", "count":6, "items":{ "table_layout":{ "id":"table_layout", "description":"Layout table", "count":3, "xpaths":[ "\/BODY[1]\/CENTER[1]\/FORM[1]\/TABLE[1]\/TBODY[1]\/TR[1]\/TD[1]", "\/BODY[1]\/CENTER[1]\/SPAN[1]\/DIV[1]\/DIV[1]\/TABLE[1]\/TBODY[1]\/TR[1]\/TD[1]", "\/BODY[1]\/TABLE[1]\/TBODY[1]\/TR[1]\/TD[1]" ] }, "ol":{ "id":"ol", "description":"Ordered list", "count":1, "xpaths":[ "\/BODY[1]\/DIV[1]\/DIV[1]\/DIV[1]\/DIV[1]\/OL[1]\/LI[1]" ] }, "h2":{ "id":"h2", "description":"Heading level 2", "count":1, "xpaths":[ "\/BODY[1]\/DIV[1]\/DIV[1]\/DIV[1]\/DIV[2]\/H2[1]" ] }, "iframe":{ "id":"iframe", "description":"Inline Frame", "count":1, "xpaths":[ "\/BODY[1]\/IFRAME[1]" ] } } }, "aria":{ "description":"ARIA", "count":4, "items":{ "aria":{ "id":"aria", "description":"ARIA", "count":4, "xpaths":[ "\/BODY[1]\/DIV[1]\/DIV[1]\/DIV[1]\/DIV[1]\/OL[1]\/LI[9]\/A[1]", "\/BODY[1]\/DIV[1]\/DIV[1]\/DIV[1]\/DIV[1]\/OL[1]\/LI[9]\/DIV[1]", "\/BODY[1]\/DIV[1]\/DIV[1]\/DIV[1]\/DIV[2]\/OL[1]\/LI[3]\/A[1]", "\/BODY[1]\/DIV[1]\/DIV[1]\/DIV[1]\/DIV[2]\/OL[1]\/LI[3]\/DIV[1]" ] } } } } }

The results include all data from above, including XPath data for each WAVE item identified. XPath values may be useful to associate a particular item with a distinct element within the page (e.g., determining which particular image in the page is missing alternative text). This request will cost 3 API credits.

The item details and XPaths can also be returned in XML format with the following:

Query:

https://wave.webaim.org/api/request?key={yourAPIkey}&format=xml&reporttype=3&url=google.com

Get Item Details + CSS Selectors

Query:

https://wave.webaim.org/api/request?key={yourAPIkey}&reporttype=4&url=https://google.com/

Output will be as above, except that CSS selector values will be provided instead of XPath values. Selector values may be useful to associate a particular item with a distinct element within the page (e.g., determining which particular image in the page is missing alternative text). These can also be returned in XML format. This request will cost 3 API credits.

Getting WAVE Documentation

A separate API allows you to get details about WAVE items. A JSON file that provides summary details for all items is available at https://wave.webaim.org/api/docs. This can be retrieved in XML format at https://wave.webaim.org/api/docs?format=xml or in HTML at https://wave.webaim.org/api/docs?format=html.

You can also query full details for any WAVE item by its id (e.g., "alt", "alt_link_missing", "h3", etc.). The full documentation API returns:

name - The unique identifier for the item
title - A brief description of the item
type - The item category: error, contrast, alert, feature, structure, or aria
summary - A summary of the item
purpose - A brief description of what the item means
actions - What should be done to fix or further evaluate the item
details - The algorithm that caused the item to be identified
guidelines - An array of the WCAG 2.1 guideline names and links that are applicable to that item

JSON documentation

Query:

https://wave.webaim.org/api/docs?id=alt

Result:

{ "name":"alt", "title":"Alternative text", "type":"feature", "summary":"Image alternative text is present.", "purpose":"Alternative text presents the content or function of an image to screen reader users or in other situations where images cannot be seen or are unavailable.", "actions":"Ensure that the alternative text conveys the content and function of the image accurately and succinctly. The alt attribute should be equivalent, accurate, and succinct.", "details":"A non-empty alt attribute is present on an image.", "guidelines":[ { "name":"1.1.1 Non-text Content (Level A)", "link":"https:\/\/webaim.org\/standards\/wcag\/checklist#sc1.1.1" } ] }

XML documentation

Query:

https://wave.webaim.org/api/docs?id=alt&format=xml

Result:

<?xml version="1.0" encoding="UTF-8"?> <results> <name>alt</name> <title>Alternative text</title> <type>feature</type> <summary>Image alternative text is present.</summary> <purpose>Alternative text presents the content or function of an image to screen reader users or in other situations where images cannot be seen or are unavailable.</purpose> <actions>Ensure that the alternative text conveys the content and function of the image accurately and succinctly. The alt attribute should be equivalent, accurate, and succinct.</actions> <details>A non-empty alt attribute is present on an image.</details> <guidelines> <item> <name>1.1.1 Non-text Content (Level A)</name> <link>https://webaim.org/standards/wcag/checklist#sc1.1.1</link> </item> </guidelines> </results>

Feedback

If you have feedback or recommendations on the WAVE API Specification, please contact us.