Documentation (API Version 2 and Test API)

The ProperSpell API is a REST based API which will return XML results when a correctly formatted URL is input.

(for the older Version 1 documentation, please click here)

Every user is provided with an application ID (APPID) as well as a secret key (SECRET). When a request is sent to the ProperSpell server, a signature is attached in order to verify the authorization of the requesting client.

Important notes about the ProperSpell API:

  • The API currently only supports requests in the English language.
  • The presence of any non-Latin characters in the query string will result in no suggestion.
  • Any query that contains more than five words will result in no suggestion.

Returned Formats:

An example of how to generate a ProperSpell request in PHP:

function spell_check($query) {

  $appid = "APPID";
  $secret = "SECRET";
  $signature = md5($appid . $query . $secret);

  $appid = urlencode($appid);
  $query = urlencode($query);
  $signature = urlencode($signature);
  $version = 2;
  $format = 'xml';

  $xml = @ simplexml_load_file("http://properspell.com/api/rest/?q={$query}&id={$appid}&sig={$signature}&out={$format}&v={$version}");    

  if (!$xml) {
    return false; }

  if ($xml->attributes()->responsecode == "200") {
    return (string) $xml->suggestion; }
  else {
    return false; }
}

The URL request for a query of “untied stats” might look like this:

http://properspell.com/api/rest/?q=untied+stats&id=7a21b5067376d19002dc3faf0c10d47e&sig=2460b7f3855afed6e1b25c763cdcc4d4

The query parameters in bold denote default values:

  • q: The urlencoded string to be spell checked.
  • id: The urlencoded string of your application ID.
  • sig: The urlencoded string of your signature. The signature is generated by concatenating your application ID, the query string, and your secret key, and then performing an md5 hash on the result.
  • v: the version to use (1,2,test)
  • out: the output format (xml, json, jsonp, pser, html)

The XML response for a query of “untied stats” might look like this:

<?xml version='1.0' encoding='UTF-8'?>
<properspell responsecode='200'>
<status><![CDATA[Success]]></status>
<usage><![CDATA[5]]></usage>
<query><![CDATA[untied stats]]></query>
<frequency><![CDATA[42]]></frequency>
<clicks><![CDATA[0]]></clicks>
<suggestion><![CDATA[united states]]></suggestion>
<html><![CDATA[<b><i>united states</i></b>]]></html>
<hash><![CDATA[88c0d1dab5391cb91821bc970e1414c8]]></hash>
<spelltime><![CDATA[0]]></spelltime>
<time><![CDATA[0.03]]></time>
</properspell>

The XML response fields are:

  • responsecode: The numeric response code. (see below for possible values)
  • status: The response status text.
  • error: If there was an error during the request, an error string will be located here. Otherwise, this parameter will not be set.
  • usage: The current lookups performed for the day.
  • query: The original query that was passed to the API.
  • frequency: How often the query term has been requested (historical).
  • clicks: FUTURE How many times the spelling suggestion was clicked.
  • suggestion: The spelling suggestion.
  • html: HTML formatted spelling suggestion, with corrected words highlighted by <b> and <i> tags.
  • hash: The unique ID of the lookup.
  • spelltime: How long the spell algorithm itself took.
  • time: The amount of time that the request took, in seconds.

Possible Response Codes are:

  • 200: Response OK, all parameters correct.
  • 202: Test API – No lookups.
  • 206: History updated. Summary info not found.
  • 304: Spell check request not found.
  • 400: No query parameters provided.
  • 401: Invalid signature provided by the client.
  • 402: Daily user defined query limit reached.
  • 403: Client has reached the daily limit for requests.
  • 407: Account inactive.
  • 412: Invalid Application ID.

The ProperSpell Test API:

Since any lookup performed against the live server using your APPID and SECRET will count against your defined daily limit as well as used in billing, we have implemented a way to allow you to test the creation of the URL (proper signature generation) as well as receive the correct response format. You can either change the version to test (&v=test) in the URL, or use the test API keys:

  • Test APPID: cec3d7226c429cb7b41e541e791514ed
  • Test SECRET: e889589e826799f0143ae49ea3282ddd

Items to note using the Test API:

  • The result spelling correction result will always be for ‘untied stats’.
  • You must properly create the SIGNATURE with either your APPID or the Test Key. The API will invalidate with the wrong combination.
  • The Frequency/Usage/Clicks values will not change.
  • This lookup request will not be used in any billing or statistics reports.