Readability Scores for Documents API - ApyHub - ApyHub

Readability Scores Documents API

ApyHub
ApyHub
verified icon
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

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
AttributeTypeMandatoryDescription
fileFileYesThe source pdf or document file should be in .pdf,.doc or .docx format for which you want to calculate the readability score metics.
languageStringNoLanguage 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)
AttributeTypeDescription
data.flesh_kincaid_reading_ease.scoreNumberThe 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.levelNumberThe Flesch-Kincaid Grade of the given text.
data.flesh_kincaid_reading_ease.labelBooleanIf the Flesch Reading Ease score is greater then 70 it is true else false.
data.flesh_kincaid_reading_ease.classStringDescribes 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_labelStringProvides a descriptive label for the readability class,the Flesh Kincaid Reading Ease Table contains all possible values like Difficult to read.
data.stats.paragraphsNumberThe total number of paragraphs in the text.
data.stats.sentencesNumberThe total count of sentences in the text.
data.stats.wordsNumberThe total number of words in the text.
data.stats.charactersNumberThe total character count in the text.
data.stats.reading_timeNumberThe estimated time in seconds it would take to read the entire text.
data.stats.speaking_timeNumberThe estimated time in seconds it would take to verbally speak or present the text.
data.stats.avg_word_lengthNumberAverage length of words in the text (measured in characters).
data.stats.avg_sentence_lengthNumberAverage length of sentences in the text (typically measured in words).
data.stats.avg_paragraph_lengthNumberAverage length of paragraphs in the text (often measured in sentences or words).
Flesh Kincaid Reading Ease Table
ScoreClassClass Label
Greater than 905th gradeVery easy to read. Easily understood by an average 11-year-old student.
90.0–80.06th gradeEasy to read. Conversational English for consumers.
80.0–70.07th gradeFairly easy to read.
70.0–60.08th & 9th gradePlain English. Easily understood by 13- to 15-year-old students.
60.0–50.010th to 12th gradeFairly difficult to read.
50.0–30.0CollegeDifficult to read.
30.0–10.0College graduateVery difficult to read. Best understood by university graduates.
Less than 10.0ProfessionalExtremely 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)
AttributeTypeDescription
data.wiener_sachtextformel.scoreNumberThe Wiener Sachtextformel score, typically ranging from 4 to 15.
data.wiener_sachtextformel.levelNumberApproximate grade level (score divided by 4).
data.wiener_sachtextformel.labelBooleanTrue if complex (score > 8), False if simple.
data.wiener_sachtextformel.classStringReadability class based on score ranges.
data.wiener_sachtextformel.class_labelStringDescriptive label of the readability level.
data.stats.paragraphsNumberThe total number of paragraphs in the text.
data.stats.sentencesNumberThe total count of sentences in the text.
data.stats.wordsNumberThe total number of words in the text.
data.stats.charactersNumberThe total character count in the text.
data.stats.reading_timeNumberThe estimated time in seconds to read the text.
data.stats.speaking_timeNumberThe estimated time in seconds to speak the text.
data.stats.avg_word_lengthNumberAverage length of words in characters.
data.stats.avg_sentence_lengthNumberAverage length of sentences in words.
data.stats.avg_paragraph_lengthNumberAverage length of paragraphs in sentences.
Wiener Sachtextformel Score Table
Score RangeClassClass Label
< 4.54th gradeVery Easy (4th grade).
4.5 - 7.45th-6th gradeEasy (5th-6th grade).
7.5 - 9.47th-8th gradeModerate (7th-8th grade).
9.5 - 11.49th-10th gradeDifficult (9th-10th grade).
≥ 11.511th 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 CodeDescription
200The request was successful.
401Required authentication information is either missing or not valid for the resource.
400Invalid input - the image urls are corrupt or not accessible.
500If 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.
Table of contents
AboutAPI PlaygroundAPI DocumentationAuthenticationError codesRelated Utility APIsRelated Articles