API Basics

API Introduction

The Readable.com API is a simple interface for passing text and URLs to Readable.com 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.

HEADER Parameters


    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.


    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.

API Testing

If you want to test the API, you can use the following testing API key.


Please note that the requests made with the test key return the same results in the same format as a normal request, but the API will not analyse the text you send; it analyses pre-set test text (if you're curious, the first paragraph of Moby Dick). There is no charge for test requests.

API Endpoints

Analyse Text

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

POST https://api.readable.com/api/text/

POST Parameters

  • 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 through the website.

POST https://api.readable.com/api/url/

POST Parameters

  • url

    Type: URL string, with UTF-8 encoding
    Description: The URL you wish to score.

  • 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 with the API, the API response will include a score_id. You can pass this back to the API highlight endpoint to retrieve a highlighted version of that content, showing possible issues to address.

Text highlights are only available for six hours after scoring a URL or piece of text.

The highlighted version of the text is provided in HTML, with spans wrapped around items of interest. The API response includes a key for the classes for those spans to indicate what they mean.

POST https://api.readable.com/api/highlight/

POST Parameters

  • 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.

Profanity Detector

You can pass any plain text to the API to be examined for profanity. You can also specify how sensitive you would like the profanity detector to be.

POST https://api.readable.com/api/profanity/

POST Parameters

  • text

    Type: Plain text string, with UTF-8 encoding
    Description: The text you wish to analyse.

  • level

    Type: A number - 1, 2 or 3 (defaults to 1)
    Description: The sensitivity you want to set the profanity detection systems to. 1: Highlight strong profanity only (e.g., "fuck", "arse", racism and other discriminatory language). 2: Highlight strong and medium profanity including mildly offensive words (e.g., "idiot", "dammit", "wanker"). 3: Highlight all potential profanity, including words which are usually fine but can be profane or objectionable in certain circumstances (e.g., "black", "yank", "addict").

API Examples

API Postman Example

Please click the button below to load an example of our API using Postman (please note that this uses a test key for the API and returns example data in response to each query).

API Request Example (PHP)

$api_key = 'KSTHBX12ST5Z969LVN74Z8EPK0CXPNYC'; // Generate this in your Readable.com account.
$url = 'https://api.readable.com/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);

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

API Text/URL Response Example

   "rating": "B",
   "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,
   "forcast_grade": 7.1,
   "fry_grade": 8,
   "raygor_grade": 9,
   "lensear_write": 7.8,
   "lix_score": 40.1,
   "rix_score": 10,
   "dale_chall_readability_score": "4.7",
   "spache_readability_score": "4.6",
   "powers_sumner_kearl_score": 8.3,
   "average_grade_level": "9.3",
   "paragraph_count": "11",
   "sentence_count": "25",
   "sentence_count_flesch": "26",
   "letter_count": "1,948",
   "word_count": "459",
   "lensear_word_count": 298,
   "unique_word_count": 239,
   "word_with_three_syllables": 44,
   "word_with_three_syllables_common_only": 41,
   "dale_chall_difficult_words": 110,
   "spache_difficult_words": 99,
   "syllable_count": "657",
   "words_per_sentence": "18.4",
   "sentences_per_paragraph": "2.3",
   "words_per_paragraph": "41.4",
   "words_per_sentence_flesch": "17.5",
   "syllables_per_word": "1.4",
   "letters_per_word": "4.2",
   "cefr_level": "B1",
   "ielts_level": "4-5",
   "cefr_score": "666.6",
   "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_proper_noun_count": 13,
   "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",
   "reach": "98",
   "reach_public": "83",
   "keyword_density": {
      "1 word": {
            "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]
   "score_id": "5f09a17b879f17a5bfa3",
   "result": "success",
   "response_timestamp": 1455874980

API Highlight Response Example

   "highlighted_text": "<span class=\"highlight_bad\">Way, way back in 2004, I wrote a piece ... [snipped]",
   "cliche_count": 1,
   "adverb_count": 8,
   "spelling_error_count": 12,
   "grammar_error_count": 7,
   "very_long_sentence_count": 6,
   "long_sentence_count": 17,
   "passive_voice_count": 1,
   "long_word_count": 2,
   "high_syllable_word_count": 4,
   "highlighted_text_key": {
      "highlight_warn": "Long sentence (more than 20 syllables)",
      "highlight_bad": "Very long sentence (more than 30 syllables)",
      "highlight_long_word": "Long word (more than 12 letters)",
      "highlight_hard_word": "Hard word (more than 4 syllables)",
      "highlight_adverb": "Possible adverb",
      "highlight_cliche": "Possible cliche",
      "highlight_passive": "Possible passive voice",
      "highlight_hedge": "Possible Hedge Word",
      "highlight_transition": "Possible Transition Word",
      "highlight_profanity": "Possible Profanity",
      "highlight_buzzwords": "Possible Buzzword",
      "highlight_stopwords": "Possible Stop Word",
      "highlight_lazy": "Possible Lazy Wprd",
      "highlight_names": "Possible Name"
   "score_id": "5f09a17b879f17a5bfa3",
   "result": "success",
   "response_timestamp": 1455874980

API Profanity Detector Response Example

   "profanity_count": "2",
   "profanities": {
          "profanity": "ass",
          "type": "misc / other",
          "start": "4",
          "length": "3",
          "profanity": "wanker",
          "type": "sexual",
          "start": "42",
          "length": "6",
   "result": "success",
   "response_timestamp": 1455874980

API Example Classes and Code

These code examples have been generously shared by ReadablePro API users and are provided as-is, with no guarantee or warantee.

Login Popup Trigger

Log in to Readable

Login with Readable

          Don't have an account yet?

          Sign Up Today

          Premium Popup Trigger

          Measuring Readability Score ...