The Score API lets AudioEye Partners scan their customers’ page(s) to provide an estimate of how accessible they are currently.
Their accessibility state is expressed as an accessibility score, and is supplemented by a list of top accessibility issues detected on the site. The endpoint also provides an estimate of what their accessibility score would be with AudioEye enabled on the site.
Workflow
The Score Estimator consists of two relevant REST operations, CreateScore(CreateScoreRequest) and GetScore(id). Scoring a website is an asynchronous process. Calling CreateScore returns the id of the Score, but that Score may not have an actual value assigned to it immediately when calling GetScore(id).
The state of the Score is reflected in its lifecycleState attribute, which can be one of:
- ACCEPTED
- PENDING
- IN_PROGRESS
- FAILED
- COMPLETE
The score is available when the lifecycleState == COMPLETE.
The overall flow for scoring a site is:
- CreateScore(CreateScoreRequest), which yields an id
- GetScore(id), which yields a score with a score.lifecycleState attribute
- If score.lifecycleState is COMPLETE, read the score and exit
- If score.lifecycleState is FAILED, then display an error message and exit
- Otherwise, wait N seconds, then go to step 2
Making Test Requests
We recommend HTTPie for making ad hoc test requests from the CLI. After installation, submit a new score request:
https api.audioeye.io/v20210831/scores \
url=<site> \
x-api-key:<api-key>
This returns an ID, which you can subsequently read:
https api.audioeye.io/v20210831/scores/<scoreId> \
x-api-key:<api-key>
Retrieving & Displaying the Score
The getScore endpoint can be used to retrieve key accessibility information about any given URL. It will return information about the page’s accessibility score, the top issues found, and the abilities impacted by those issues (beneficiary).
A representative score for a site can be generated using the getScore endpoint in two ways:
- Scanning the websites homepage and using this a a representation of the sites score, clearly noting that it is a homepage score only (this is how AudioEye presents score on our website’s scanner)
- Scan a number of pages (call getScore for each of those pages) and combine the results as a representation of the sites overall score & status
- Use an average of all page scores to represent the site’s overall score.
- Combine the top issue records, summing issue count where the issue code is the same and then reorder the list by issue count descending to retrieve the top issues across the entire site
Score Display
This section outlines which key pieces of information to display to help users understand how to interpret the score. You can see an example of how AudioEye displays the data returned by the getScore endpoint on our accessibility web checker.
The getScore endpoint will return two key values important for accurately representing the score: installed and scoreResults. Installed indicates whether or not the site has AudioEye installed.
The scoreResults object contains the score, and name and description:
- Score: The accessibility compliance score for the page url scanned
- Name: Short description of the page’s accessibility state based on the score
- Description: More detailed information about how to interpret the score in terms of accessibility and compliance
If you are scanning only a single page (for example the home page) you will be able to use the name and description to give users context about that score.
If however you have scanned multiple pages and combined the results the name and description may not be appropriate based on that average in this scenario we suggest using the values below to populate the name and description based on whether AudioEye is currently installed on the site or not:
- Installed
- Name: Compliant with AudioEye
- Description: Nice Work! Your website meets ADA / WCAG guidelines for digital compliance because you have AudioEye installed.
- Not Installed
- Name: Not Compliant
- Description: Without AudioEye, your site may not meet ADA / WCAG guidelines for digital compliance and you are currently at legal risk.