After the Deadline

API Documentation

After the Deadline is a web service for checking the spelling and style of English text. This page documents the API.

Posting

The AtD service is at https://service.afterthedeadline.com. For any call you may use POST or GET. Here are the calls supported by AtD at this time:

URI	Description
/checkDocument	Checks a document and returns errors and suggestions
/checkGrammar	Checks a document (sans spelling) returns errors and suggestions
/info.html	Returns HTML describing an error
/stats	Returns statistics about the writing quality of a document

API Keys

We used to require users to register for an API key. We no longer do this but applications are still required to submit an API key. The API key is used as both a synchronous locking point (e.g., only one request/key is processed at a time) and to enable server-side caching of results and session information. This makes subsequent requests for the same key much faster.

To generate an API key, consider using a short string to identify your application followed by a hash of something unique to the user or installation of AtD. In WordPress, we hash the user's blog URL and use that as a key.

/checkDocument

Variables

Variable	Format	Description
key	ID + 32 hex digits	Required, used to control server-side caching.
data	HTML, text	Required, this is the data to check. HTML is stripped.

Response

A typical response will look like this:

<results>
  <error>
    <string>to be</string>
    <description>Passive voice</description>
    <precontext>want</precontext>
    <type>grammar</type>
    <url>https://service.afterthedeadline.com/info.html?text=to+be</url>
  </error>
  <error>
    <string>wether</string>
    <description>Did you mean...</description>
    <precontext>determine</precontext>
    <suggestions>
        <option>whether</option>
        <option>weather</option>
    </suggestions>
    <type>spelling</type>
    <url>https://service.afterthedeadline.com/info.html?text=wether</url>
  </error>
</results>

The service will send one or more error items. The string item is the phrase in question. The precontext is the token before the string item. Sometimes this variable is empty.

The suggestion tag contains one or more options to replace the phrase in question. These values are sorted in order of relevance. You'll rarely see more than 5 values here.

If an error occurs, you'll get a response like this:

<results>
  <message>This is a description of what went wrong</message>
</results>

When this occurs, it's best to present the information to the user. The usual cause is a bad API key.

/checkGrammar

This call is the same as /checkDocument except it does not include spelling errors. The spelling corrector is the slowest part of After the Deadline. If you'd like to perform the other checks without the performance hit of spell check, use this call.

/info.html

Variables

Variable	Format	Description
tags	NN/VB	Optional, part-of-speech tags for text separated by a /
text	a string	Required, the text that triggered an error.
theme	"wordpress", "tinymce", ""	Optional. if set, the theme is a wrapper for displaying the information.

Response

Depending on the theme, the response is ready to display HTML. The TinyMCE theme shows HTML ready for a TinyMCE popup window. The Wordpress theme shows HTML ready for a Wordpress popup window. Specifying no theme shows the error HTML with no wrapper.

The info.html call (when available) is provided in the <url></url> field of checkDocument.

You do not send your API key with an info.html call.

/stats

Variables

Variable	Format	Description
key	ID + 32 hex digits	Required, used to control server-side caching.
data	HTML, text	Required, this is the data to check. HTML is stripped.

Response

A typical response consists of multiple metric values, like this:

<scores>
 <metric>
    <type>[grammar|spell|stats|style]</type>
    <key>[key based on metric (e.g. errors)]</key>
    <value>[some integer here]</key>
  </metric>
</scores>

The type is a category to add some organization to the information. Here are the types and keys associated with them:

grammar

• errors - number of grammar errors
• revise - number of miscellaneous things to revise
• repeated words - number of times "the the" or some other repeated sequence occurs

spell

• hyphenate - number of phrases found missing a hypen
• misused words - number of misused words detected
• raw - raw number of words not in AtD's dictionary
• estimate - number of times a known common misspelling occurs (these are almost always a legit error)

stats

• sentences - number of sentences in the document (estimate)
• words - number of words in the document

style

• cliches - number of cliche phrases found
• complex phrases - number of complex phrases found
• hidden verbs - number of hidden verb phrases found
• passive voice - number of passive phrases found