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_TIME
    The API_REQUEST_TIME header is sent with every request to the API, and is the UNIX timestamp of the request (in the UTC timezome). The request will be rejected if the API_REQUEST_TIME is not within the last 30 seconds.
  • API_SIGNATURE
    The 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.

Analyse Text

You can pass any plain text to the site to score.

POST https://api.readable.io/api/text/
  • Required Parameter: text
    Type: Plain text string, with UTF-8 encoding
    Description: The text you wish to score.

Analyse a URL

You can pass any URL to the site to score. We recommend sending all URLs encoded as UTF-8. If a URL is resolved to a file, that will automatically be added to the file queue to process as though it were uploaded normally.

POST https://api.readable.io/api/url/
  • Required Parameter: url
    Type: URL string, with UTF-8 encoding
    Description: The URL you wish to score.
  • Optional Parameter: extract
    Type: boolean, true or false (defaults to false)
    Description: If set to true, we will attempt to automatically extract the body copy from the URL, removing navigation, headers, footers and so on.

Retrieve Highlighted Issues and Content from a Scored Item

When you score a piece of text or a URL, we can also generate a highlighted version of that content, showing possible issues to address. This can be retrieved with a call to the highlight endpoint.

POST https://api.readable.io/api/highlight/
  • Required Parameter: score_id
    Type: score ID string, with UTF-8 encoding
    Description: The score ID, returned with the results of a previous call to either the text or URL endpoint

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));
$file = curl_exec($ch);
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_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",
   "composition_nonword_count": "2",
   "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