WAVE Web Accessibility Tool Register |  Login

WAVE API (v.1) Details

Using the API

API requests are made by sending a request to http://wave.webaim.org/api/request?key={yourAPIkey}&url={url}. You can use https:// for a secure, encrypted connection.

Query Parameters

NOTE: All parameters are optional unless specified.

ParameterMeaningNotes
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.
reporttype 1, 2, or 3
(Default=1)

reporttype=1 (costs 1 API credit) will return only the WAVE statistics for the page being analyzed - the number of errors, alerts, features, HTML5/ARIA elements, structural elements, and contrast issues.

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) identified.

reporttype=3 (costs 3 API credits) will return all of the above, including 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.

username
Not yet supported
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
Not yet supported
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 the SSL API URL.

You can limit requests to specific IP addresses and domains in the online control panel after logging in. This ensures that your API key is used only by computers and/or to analyze domains that you want.

Result Parameters

The following result parameters are returned for reporttype=1

ParameterMeaning
status:success|error Status of the request
status:error:code
status:error:description
(Returns only if status is error)
Error code returned by your server (e.g. "404") or the WAVE engine, and a description of the error (e.g., "No API credits remaining").
categories:categoryname Array of categories returned - error, alert, feature, structure, html5, and/or contrast
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 by WAVE).
statistics:creditsremaining Number of WAVE API credits remaining on account
statistics:pageurl The URL of the page analyzed. Note that due to redirects, this may sometimes be different than the URL sent in the request.
statistics:pagetitle Page title of the page analyzed.
statistics:waveurl The URL of the full WAVE report.
statistics:time Number of seconds required for WAVE to analyze the page.
statistics:allitemcount Sum of all categoryname:count above, or number of distinct items returned by WAVE (must use reporttype=2 or reporttype=3 to view them individually).
statistics:totalelements Number of elements in the page that were analyzed.

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

ParameterMeaning
categories:categoryname:items Array of items in that category
categories:categoryname:items:id Distinct id of each item returned by WAVE. (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:7 indicates 7 missing alternative text items were found.
categories:categoryname:items:id:id The unique 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 Section 508 and WCAG 2.0 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

ParameterMeaning
categories:categoryname:items:id:xpaths Array of XPath values for each item of that type.
categories:categoryname:items:id:xpaths:xpath XPath values. These 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).

Examples

Basic Query

Query:

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

Result:

{ "status":{ "success":true }, "statistics":{ "pagetitle":"Google", "pageurl":"google.com", "time":683, "allitemcount":20, "totalelements":178 }, "categories":{ "error":{ "description":"Errors", "count":4 }, "alert":{ "description":"Alerts", "count":5 }, "feature":{ "description":"Features", "count":1 }, "structure":{ "description":"Structural Elements", "count":5 }, "html5":{ "description":"HTML and ARIA", "count":4 }, "contrast":{ "description":"Contrast Errors", "count":2 } } }

Basic XML Query

Query:

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

Result:

<?xml version="1.0" encoding="UTF-8"?> <results> <status> <success>1</success> </status> <statistics> <pagetitle>Google</pagetitle> <pageurl>google.com</pageurl> <time>596</time> <allitemcount>20</allitemcount> <totalelements>178</totalelements> </statistics> <categories> <error> <description>Errors</description> <count>4</count> </error> <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> <html5> <description>HTML5 and ARIA</description> <count>4</count> </html5> <contrast> <description>Contrast Errors</description> <count>2</count> </contrast> </categories> </results>

Get Item Details

Query:

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

Result:

{ "status":{ "success":true }, "statistics":{ "pagetitle":"Google", "pageurl":"google.com", "time":805, "allitemcount":31, "totalelements":178 }, "categories":{ "error":{ "description":"Errors", "count":4, "items":{ "language_missing":{ "id":"language_missing", "description":"Document language missing", "count":1 }, "alt_spacer_missing":{ "id":"alt_spacer_missing", "description":"Spacer image missing alternative text", "count":1 }, "link_empty":{ "id":"link_empty", "description":"Empty link", "count":1 }, "label_missing":{ "id":"label_missing", "description":"Missing form label", "count":1 } } }, "alert":{ "description":"Errors", "count":5, "items":{ "h1_missing":{ "id":"h1_missing", "description":"Missing first level heading", "count":1 }, "title_redundant":{ "id":"title_redundant", "description":"Redundant title text", "count":1 }, "label_title":{ "id":"label_title", "description":"Unlabeled form element with title", "count":1 }, "link_suspicious":{ "id":"link_suspicious", "description":"Suspicious link text", "count":1 }, "heading_skipped":{ "id":"heading_skipped", "description":"Skipped heading level", "count":1 } } }, "feature":{ "description":"Features", "count":1, "items":{ "alt_link":{ "id":"alt_link", "description":"Linked image with alternative text", "count":1 } } }, "structure":{ "description":"Structural Elements", "count":5, "items":{ "table_layout":{ "id":"table_layout", "description":"Layout table", "count":2 }, "ol":{ "id":"ol", "description":"Ordered list", "count":1 }, "h2":{ "id":"h2", "description":"Heading level 2", "count":1 }, "iframe":{ "id":"iframe", "description":"Inline Frame", "count":1 } } }, "html5":{ "description":"HTML5 and ARIA", "count":4, "items":{ "aria":{ "id":"aria", "description":"ARIA", "count":4 } } }, "contrast":{ "description":"Contrast Errors", "count":2, "items":{ "contrast":{ "id":"contrast", "description":"Very Low Contrast", "count":2 } } } } }

The results includes 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:

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

Result:

{ "status":{ "success":true }, "statistics":{ "pagetitle":"Google", "pageurl":"google.com", "time":697, "allitemcount":20, "totalelements":186 }, "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]" ] } } }, "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]" ] } } }, "html5":{ "description":"HTML5 and 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]" ] } } }, "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]" ] } } } } }

Query:

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

Result:

<?xml version="1.0" encoding="UTF-8"?> <results> <status> <success>1</success> </status> <statistics> <pagetitle>Google</pagetitle> <pageurl>google.com</pageurl> <time>890</time> <allitemcount>20</allitemcount> <totalelements>178</totalelements> </statistics> <categories> <error> <description>Errors</description> <count>4</count> <items> <language_missing> <id>language_missing</id> <description>Document language missing</description> <count>1</count> <xpaths> <item>#</item> </xpaths> </language_missing> <alt_spacer_missing> <id>alt_spacer_missing</id> <description>Spacer image missing alternative text</description> <count>1</count> <xpaths> <item>/BODY[1]/CENTER[1]/SPAN[1]/DIV[1]/DIV[1]/TABLE[1]/TBODY[1]/TR[2]/TD[1]/IMG[1]</item> </xpaths> </alt_spacer_missing> <link_empty> <id>link_empty</id> <description>Empty link</description> <count>1</count> <xpaths> <item>/BODY[1]/DIV[1]/DIV[1]/DIV[1]/DIV[2]/OL[1]/LI[3]/A[1]</item> </xpaths> </link_empty> <label_missing> <id>label_missing</id> <description>Missing form label</description> <count>1</count> <xpaths> <item>/BODY[1]/TEXTAREA[1]</item> </xpaths> </label_missing> </items> </error> <alert> <description>Alerts</description> <count>5</count> <items> <h1_missing> <id>h1_missing</id> <description>Missing first level heading</description> <count>1</count> <xpaths> <item>#</item> </xpaths> </h1_missing> <title_redundant> <id>title_redundant</id> <description>Redundant title text</description> <count>1</count> <xpaths> <item>/BODY[1]/CENTER[1]/DIV[1]/A[1]/IMG[1]</item> </xpaths> </title_redundant> <label_title> <id>label_title</id> <description>Unlabeled form element with title</description> <count>1</count> <xpaths> <item>/BODY[1]/CENTER[1]/FORM[1]/TABLE[1]/TBODY[1]/TR[1]/TD[2]/DIV[1]/INPUT[1]</item> </xpaths> </label_title> <link_suspicious> <id>link_suspicious</id> <description>Suspicious link text</description> <count>1</count> <xpaths> <item>/BODY[1]/DIV[1]/DIV[1]/DIV[1]/DIV[1]/OL[1]/LI[9]/A[1]</item> </xpaths> </link_suspicious> <heading_skipped> <id>heading_skipped</id> <description>Skipped heading level</description> <count>1</count> <xpaths> <item>/BODY[1]/DIV[1]/DIV[1]/DIV[1]/DIV[2]/H2[1]</item> </xpaths> </heading_skipped> </items> </alert> <feature> <description>Features</description> <count>1</count> <items> <alt_link> <id>alt_link</id> <description>Linked image with alternative text</description> <count>1</count> <xpaths> <item>/BODY[1]/CENTER[1]/DIV[1]/A[1]/IMG[1]</item> </xpaths> </alt_link> </items> </feature> <structure> <description>Structural Elements</description> <count>5</count> <items> <table_layout> <id>table_layout</id> <description>Layout table</description> <count>2</count> <xpaths> <item>/BODY[1]/CENTER[1]/FORM[1]/TABLE[1]/TBODY[1]/TR[1]/TD[1]</item> <item>/BODY[1]/CENTER[1]/SPAN[1]/DIV[1]/DIV[1]/TABLE[1]/TBODY[1]/TR[1]/TD[1]</item> </xpaths> </table_layout> <ol> <id>ol</id> <description>Ordered list</description> <count>1</count> <xpaths> <item>/BODY[1]/DIV[1]/DIV[1]/DIV[1]/DIV[1]/OL[1]/LI[1]</item> </xpaths> </ol> <h2> <id>h2</id> <description>Heading level 2</description> <count>1</count> <xpaths> <item>/BODY[1]/DIV[1]/DIV[1]/DIV[1]/DIV[2]/H2[1]</item> </xpaths> </h2> <iframe> <id>iframe</id> <description>Inline Frame</description> <count>1</count> <xpaths> <item>/BODY[1]/IFRAME[1]</item> </xpaths> </iframe> </items> </structure> <html5> <description>HTML5 and ARIA</description> <count>4</count> <items> <aria> <id>aria</id> <description>ARIA</description> <count>4</count> <xpaths> <item>/BODY[1]/DIV[1]/DIV[1]/DIV[1]/DIV[1]/OL[1]/LI[9]/A[1]</item> <item>/BODY[1]/DIV[1]/DIV[1]/DIV[1]/DIV[1]/OL[1]/LI[9]/DIV[1]</item> <item>/BODY[1]/DIV[1]/DIV[1]/DIV[1]/DIV[2]/OL[1]/LI[3]/A[1]</item> <item>/BODY[1]/DIV[1]/DIV[1]/DIV[1]/DIV[2]/OL[1]/LI[3]/DIV[1]</item> </xpaths> </aria> </items> </html5> <contrast> <description>Contrast Errors</description> <count>2</count> <items> <contrast> <id>contrast</id> <description>Very Low Contrast</description> <count>2</count> <xpaths> <item>/BODY[1]/CENTER[1]/SPAN[1]/DIV[1]/DIV[1]/TABLE[1]/TBODY[1]/TR[1]/TD[1]/DIV[1]</item> <item>/BODY[1]/CENTER[1]/SPAN[1]/DIV[1]/DIV[1]/TABLE[1]/TBODY[1]/TR[3]/TD[1]/DIV[1]</item> </xpaths> </contrast> </items> </contrast> </categories> </results>

The results include all data from above, including XPath data for each WAVE item identified. Note that this request will cost 3 API credits.

Getting WAVE Documentation

A separate API allows you to query details about any WAVE item by its id (e.g., "alt", "alt_link_missing", "h3", etc.). The documentation API returns:

JSON documentation

Query:

http://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":"Section 508 (a)", "link":"http:\/\/webaim.org\/standards\/508\/checklist#standarda" }, { "name":"1.1.1 Non-text Content (Level A)", "link":"http:\/\/webaim.org\/standards\/wcag\/checklist#sc1.1.1" } ] }

XML documentation

Query:

http://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>Section 508 (a)</name> <link>http://webaim.org/standards/508/checklist#standarda</link> </item> <item> <name>1.1.1 Non-text Content (Level A)</name> <link>http://webaim.org/standards/wcag/checklist#sc1.1.1</link> </item> </guidelines> </results>