API Documentation

Readable.io Premium!

Premium Subscribers get access to a whole host of specialist readability tools, including the Readability API, from as little as $27 per month!

Go Premium Today

  • Readability API
  • Unlimited Text Readability
  • File (Word Docs, PDFs, etc) Scoring
  • Bulk Text Readability
  • Bulk URL Readability

"Clear communication is an essential part of our email marketing platform, and Readable.io's bulk text tools are invaluable to us."

Elliot Raison, Superscribe


API Introduction

The Readable.io API is a simple interface for passing text and URLs to Readable.io from your application and getting back readability and keyword density statistics.

You can see your usage of the API in your account administration area.

All responses from the API are in JSON format. Each response contains a field called "result", which will contain either "error" or "success". If the "result" is "error", more information about the error will be contained in the "messages" array field. Every response also contains a "response_timestamp" field.

API Authentication

Authentication of all requests is done with an API key and a pair of (case-insensitive) HTTP headers - API_SIGNATURE and API_REQUEST_TIME. API keys can be generated in your account administration area (you can have as many as you want). You should never send your API key directly with a request.

  • API_REQUEST_TIMEThe API_REQUEST_TIME header is sent with every request to the API, and is the UNIX timestamp of the request. The request will be rejected if the API_REQUEST_TIME is not within the last 30 seconds.
  • API_SIGNATUREThe API_SIGNATURE header is an MD5 hash of an API key and the time you set in the API_REQUEST_TIME header. It should change with every request.

API Endpoints

The API includes two endpoints currently (with more planned). Each endpoint below is listed along with the required request method and any required parameters (in addition to the authentication headers described above).

  • https://api.readable.io/api/text/ Request Method: POST
    Required Parameters: text
  • https://api.readable.io/api/url/ Request Method: POST
    Required Parameters: url

API Request Example (PHP)

$api_key = 'KSTHBX12ST5Z969LVN74Z8EPK0CXPNYC'; // Generate this in your Readable.io account.
$url = 'https://api.readable.io/api/text/'; // The API endpoint you want to interact with
$request_time = time(); // Time of request
$api_signature = md5($api_key . $request_time); // Generate signature
$text = 'The quick brown fox jumps over the lazy dog.'; // The text you want to score

// Fetch URL with CURL
$postItems = array('text' => $text);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($postItems));
curl_setopt($ch, CURLOPT_HTTPHEADER, array('API_SIGNATURE: ' . $api_signature, 'API_REQUEST_TIME: ' . $request_time));
curl_setopt($ch, CURLOPT_TIMEOUT, 5);
curl_setopt($ch, CURLOPT_MAXREDIRS, 5);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
$file = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$results = json_decode($file, true);
var_dump($results);

API Response Example

{
   "rating": "B",
   "text": "Way, way back in 2004, I wrote a piece of code ... [snipped]",
   "clean_text": "Way, way back in 2004, I wrote a piece of code ... [snipped]",
   "flesch_kincaid_reading_ease": 69.5,
   "flesch_kincaid_grade_level": 8.1,
   "gunning_fog_score": 10.9,
   "coleman_liau_index": 9.2,
   "smog_index": 10.6,
   "automated_readability_index": 7.7,
   "average_grade_level": "9.3",
   "sentence_count": "25",
   "letter_count": "1,948",
   "word_count": "459",
   "syllable_count": "657",
   "words_per_sentence": "18.4",
   "syllables_per_word": "1.4",
   "letters_per_word": "4.2",
   "longest_word_letters": "12 (particularly)",
   "longest_word_syllables": "5 (readability, particularly)",
   "longest_sentence_words": "43 ([you can specify a  ... [snipped]",
   "composition_adjective_count": "3",
   "composition_adverb_count": "6",
   "composition_conjunction_count": "5",
   "composition_determiner_count": "4",
   "composition_interjection_count": "1",
   "composition_noun_count": "44",
   "composition_preposition_count": "3",
   "composition_pronoun_count": "2",
   "composition_qualifier_count": "11",
   "composition_verb_count": "23",
   "composition_unknown_count": "1",
   "reading_time": "2:02",
   "speaking_time": "3:40",
   "sentiment": "Positive",
   "tone": "Formal",
   "tone_number": "44",
   "gender": "Male",
   "gender_number": "62",
   "keyword_density": {
      "1 word": {
         "0000000007-text":{
            "item": "text",
            "count": 7,
            "percentage": "1.53"
         },
         {...} [snipped]
      },
      "2 words": {
         "0000000010-the page":{
            "item": "the page",
            "count": 5,
            "percentage": "1.09"
         },
         {...} [snipped]
      },
      "3 words": {
         "0000000012-of the page":{
            "item": "of the page",
            "count": 4,
            "percentage":  "0.87"
         },
         {...} [snipped]
      }
   },
   "result": "success",
   "response_timestamp": 1455874980
}

Premium Popup Trigger