Readability Scores Documents API

Data Extraction

#documents #readability #score

ApyHub

250 atoms

Base tier

About

This API calculates the text readability score of documents including PDFs, DOCs, and ODFs.

The API supports English (using Flesch-Kincaid) and German (using Wiener Sachtextformel) text analysis, helping users target specific audiences effectively. Ideal for content creators who can use this API to make marketing material easier to understand as well as researchers who can use it to ensure research papers are clear and accessible to a wide audience.

Try out the API in the API playground and see how this document readability score calculator API can help you calculate the readability of a document, optimise your content and improve reader satisfaction with a simple API call.

Select API Endpoints

Input

file

url

API Playground

API Documentation

Extract Readability Score from File

POST

https://api.apyhub.com/extract/document/readability-score/file

Request example

1
curl --location --request POST 'https://api.apyhub.com/extract/document/readability-score/file' \
2
--header 'apy-token: {{token}}' \
3
--form 'file=@"test.pdf"'

Method: POST

Content Type: multipart/form-data

Request Body

Attribute	Type	Mandatory	Description
file	File	Yes	The source pdf or document file should be in `.pdf`,`.doc` or `.docx` format for which you want to calculate the readability score metics.
language	String	No	Language of the input text. Supported values: 'english' (default) or 'german'. This determines which readability metrics will be calculated - `Flesch-Kincaid` for English or `Wiener Sachtextformel` for German.

Response (When language=english)

Attribute	Type	Description
data.flesh_kincaid_reading_ease.score	Number	The Flesch Reading Ease score ranges from 1 to 100, The `Flesh Kincaid Reading Ease Table` is an example of values. While the maximum score is 121.22, there is no limit on how low the score can be. A negative score is valid.
data.flesh_kincaid_reading_ease.level	Number	The Flesch-Kincaid Grade of the given text.
data.flesh_kincaid_reading_ease.label	Boolean	If the Flesch Reading Ease score is greater then 70 it is `true` else `false`.
data.flesh_kincaid_reading_ease.class	String	Describes the readability class or category, such as `College` for complex texts, the `Flesh Kincaid Reading Ease Table` contains all possible values.
data.flesh_kincaid_reading_ease.class_label	String	Provides a descriptive label for the readability class,the `Flesh Kincaid Reading Ease Table` contains all possible values like `Difficult to read`.
data.stats.paragraphs	Number	The total number of paragraphs in the text.
data.stats.sentences	Number	The total count of sentences in the text.
data.stats.words	Number	The total number of words in the text.
data.stats.characters	Number	The total character count in the text.
data.stats.reading_time	Number	The estimated time in seconds it would take to read the entire text.
data.stats.speaking_time	Number	The estimated time in seconds it would take to verbally speak or present the text.
data.stats.avg_word_length	Number	Average length of words in the text (measured in characters).
data.stats.avg_sentence_length	Number	Average length of sentences in the text (typically measured in words).
data.stats.avg_paragraph_length	Number	Average length of paragraphs in the text (often measured in sentences or words).

Flesh Kincaid Reading Ease Table

Score	Class	Class Label
Greater than 90	5th grade	Very easy to read. Easily understood by an average 11-year-old student.
90.0–80.0	6th grade	Easy to read. Conversational English for consumers.
80.0–70.0	7th grade	Fairly easy to read.
70.0–60.0	8th & 9th grade	Plain English. Easily understood by 13- to 15-year-old students.
60.0–50.0	10th to 12th grade	Fairly difficult to read.
50.0–30.0	College	Difficult to read.
30.0–10.0	College graduate	Very difficult to read. Best understood by university graduates.
Less than 10.0	Professional	Extremely difficult to read. Best understood by university graduates.

Sample Response (When language=english)

1
{
2
    "data": {
3
        "flesh_kincaid_reading_ease": {
4
            "score": 38.62,
5
            "level": 11.8,
6
            "label": false,
7
            "class": "College",
8
            "class_label": "Difficult to read."
9
        },
10
        "stats": {
11
            "paragraphs": 3,
12
            "sentences": 17,
13
            "words": 267,
14
            "characters": 1555,
15
            "reading_time": 22.84,
16
            "speaking_time": 106.8,
17
            "avg_word_length": 5.82,
18
            "avg_sentence_length": 15.71,
19
            "avg_paragraph_length": 5.67
20
        }
21
    }
22
}

Response (When language=german)

Attribute	Type	Description
data.wiener_sachtextformel.score	Number	The Wiener Sachtextformel score, typically ranging from 4 to 15.
data.wiener_sachtextformel.level	Number	Approximate grade level (score divided by 4).
data.wiener_sachtextformel.label	Boolean	True if complex (score > 8), False if simple.
data.wiener_sachtextformel.class	String	Readability class based on score ranges.
data.wiener_sachtextformel.class_label	String	Descriptive label of the readability level.
data.stats.paragraphs	Number	The total number of paragraphs in the text.
data.stats.sentences	Number	The total count of sentences in the text.
data.stats.words	Number	The total number of words in the text.
data.stats.characters	Number	The total character count in the text.
data.stats.reading_time	Number	The estimated time in seconds to read the text.
data.stats.speaking_time	Number	The estimated time in seconds to speak the text.
data.stats.avg_word_length	Number	Average length of words in characters.
data.stats.avg_sentence_length	Number	Average length of sentences in words.
data.stats.avg_paragraph_length	Number	Average length of paragraphs in sentences.

Wiener Sachtextformel Score Table

Score Range	Class	Class Label
< 4.5	4th grade	Very Easy (4th grade).
4.5 - 7.4	5th-6th grade	Easy (5th-6th grade).
7.5 - 9.4	7th-8th grade	Moderate (7th-8th grade).
9.5 - 11.4	9th-10th grade	Difficult (9th-10th grade).
≥ 11.5	11th grade+	Very Difficult (11th grade+).

Sample Response (When language=german)

1
{
2
   "data":{
3
      "wiener_sachtextformel":{
4
         "score":8.45,
5
         "level":2.1,
6
         "label":true,
7
         "class":"Moderate (7th-8th grade)",
8
         "class_label":"Moderate (7th-8th grade)"
9
      },
10
      "stats":{
11
         "paragraphs":2,
12
         "sentences":12,
13
         "words":156,
14
         "characters":945,
15
         "reading_time":0.78,
16
         "speaking_time":62.4,
17
         "avg_word_length":6.06,
18
         "avg_sentence_length":13.0,
19
         "avg_paragraph_length":6.0,
20
      }
21
   }
22
}

HTTP Response Codes

The method may return one of the following HTTP status codes:

Status Code	Description
200	The request was successful.
401	Required authentication information is either missing or not valid for the resource.
400	Invalid input - the image urls are corrupt or not accessible.
500	If any unexpected error occurs while processing the request.

Authentication

All API requests to ApyHub services need to be authenticated. Currently we support tokens or basic authentication mechanisms. You can generate and view your existing credentials from your workspace settings (on the left side of the navbar) and go to “API Keys".

Points to note:

Credential secrets are generated on the fly and are not stored in plain text, so on generating a credential please save the secrets somewhere safe.
Use the apy-token as the header parameter to pass the token.
Use the Authorization header to send the basic authentication credentials.

Error codes

1
{
2
  "error": {
3
    "code": 105,
4
    "message": "Invalid URL"
5
  }
6
}

To search for a specific error code, enter the code in the search box below. Alternatively, you can click on the button to view a complete list of all error codes.

Search by code

Table of contents

AboutAPI PlaygroundAPI DocumentationAuthenticationError codesRelated Utility APIsRelated Articles

Readability Scores Documents API

About

API Playground

API Documentation

Request example

HTTP Response Codes

Authentication

Error codes

101 - Missing parameters

102 - Invalid JSON

103 - Invalid input

104 - Invalid file

105 - Invalid URL

109 - Invalid input format

110 - Server error