apyhub
Back
▣ ARTIFICIAL INTELLIGENCE · SEO

Readability Scores Documents API

Hosted on ApyHub

What it does

The Readability Scores Documents API measures how easy a document or web page is to read. Upload a PDF or Word file, or send the URL of a web page, and get back a standard readability score and reading level together with statistics like word count, sentence length and reading time.

There are two endpoints. POST /file takes a PDF, DOC or DOCX upload of up to 100 MB, and POST /file_url takes the address of a public web page. Both accept an optional language: english, the default, scores the text with the Flesch Reading Ease formula, and german uses the Wiener Sachtextformel, the standard readability formula for German. The API extracts the text for you, so there is no need to convert the file or strip the HTML first.

The result includes the score, the grade class it falls into, such as "8th & 9th grade", a plain-language class_label like "Plain English. Easily understood by 13- to 15-year-old students", and a label showing whether the text meets a standard readability threshold. The stats object adds words, sentences, characters and paragraphs, the average length of words, sentences and paragraphs, and estimated reading_time and speaking_time in seconds. It gives you readability statistics similar to the ones Microsoft Word shows, without anyone having to open the file.

Common uses include checking contracts, policies and terms against plain-language requirements, reviewing manuals and help center pages before they are published, auditing the readability of every page on a website, scoring reports and proposals against a house style, and comparing a competitor's page with your own.

If you already have the text as a string, use the Readability Score API, which scores plain text directly. To pull the main article out of a web page before scoring it, use Extract Readable Content from HTML, and for simpler word and sentence counts, try the Basic Text Analysis API.

You can try it right here in the playground. Start for free with 5 API calls a day, no card required, and score your own document before you commit.

The API is also available through ApyHub MCP, so AI agents can check the readability of a document or page directly as part of a content review.

▣ ENDPOINT 01 / 02
POST
Score readability of an uploaded document
https://api.eu.apyhub.com/apyhub/score-readability/file

QUICKSTART

GUIDE

Quickstart

Upload a document file to check its readability score.

curl -X POST "https://api.eu.apyhub.com/apyhub/score-readability/file" \
  -H "apy-token: $APY_TOKEN" \
  -F "file=@/path/to/document.pdf" \
  -F "language=english"

What you'll get back

Returns a JSON object with a data object. data.stats contains document metrics like word and sentence counts, and data.flesh_kincaid_reading_ease contains the readability results.

{
  "data": {
    "stats": {
      "words": 95,
      "sentences": 8,
      "characters": 512,
      "paragraphs": 2,
      "reading_time": 6.49,
      "speaking_time": 38,
      "avg_word_length": 5.39,
      "avg_sentence_length": 11.88,
      "avg_paragraph_length": 4
    },
    "flesh_kincaid_reading_ease": {
      "class": "8th & 9th grade",
      "label": false,
      "level": 6.49,
      "score": 65.74,
      "class_label": "Plain English. Easily understood by 13- to 15-year-old students."
    }
  }
}
TRY ITLIVE · 250 ATOMS
Loading your default key…
The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.
Max 100MB total per request (all files combined). Larger? Use this API's URL-based endpoint instead, if it has one.
body*
Document file to analyse (PDF, DOC, or DOCX).

About this endpoint

What it does

Uploads a document file and returns readability metrics for the extracted text. The request accepts a binary file and an optional language setting; the response contains a data object with text statistics and one readability formula result.

Request Body

ParameterTypeMandatoryDescription
fileStringYesDocument file to analyse. Binary upload; supported formats: PDF, DOC, or DOCX.
languageENUMNoLanguage used for analysis. Allowed values: english, german. Default: english.

Response

Returns a JSON object with a data object field. Inside data, stats contains document text metrics, and the readability result is provided as either flesh_kincaid_reading_ease or wiener_sachtextformel depending on the response variant.

ParameterTypeMandatoryDescription
dataObjectNoWrapper object containing the analysis result.
data.statsObjectNoText statistics for the analysed document.
data.stats.wordsIntegerNoNumber of words.
data.stats.sentencesIntegerNoNumber of sentences.
data.stats.charactersIntegerNoNumber of characters.
data.stats.paragraphsIntegerNoNumber of paragraphs.
data.stats.reading_timeNumberNoEstimated reading time in seconds.
data.stats.speaking_timeNumberNoEstimated speaking time in seconds.
data.stats.avg_word_lengthNumberNoAverage word length.
data.stats.avg_sentence_lengthNumberNoAverage sentence length.
data.stats.avg_paragraph_lengthNumberNoAverage paragraph length.
data.flesh_kincaid_reading_easeObjectNoReadability analysis result for the Flesh-Kincaid Reading Ease variant. Includes class, label, level, score, and class_label.
data.flesh_kincaid_reading_ease.classStringNoReadability class label.
data.flesh_kincaid_reading_ease.labelBooleanNoWhether the text meets a standard readability threshold.
data.flesh_kincaid_reading_ease.levelNumberNoReadability level.
data.flesh_kincaid_reading_ease.scoreNumberNoReadability score.
data.flesh_kincaid_reading_ease.class_labelStringNoHuman-readable class description.
data.wiener_sachtextformelObjectNoReadability analysis result for the Wiener Sachtextformel variant. Includes class, label, level, score, and class_label.
data.wiener_sachtextformel.classStringNoReadability class label.
data.wiener_sachtextformel.labelBooleanNoWhether the text meets a standard readability threshold.
data.wiener_sachtextformel.levelNumberNoReadability level.
data.wiener_sachtextformel.scoreNumberNoReadability score.
data.wiener_sachtextformel.class_labelStringNoHuman-readable class description.

Body

Name
Type
Description
bodyREQUIRED
object
—

Max 100MB total per request (all files combined). Larger? Use this API's URL-based endpoint instead, if it has one.

▣ ENDPOINT 02 / 02
POST
Score readability of a web page
https://api.eu.apyhub.com/apyhub/score-readability/file_url

QUICKSTART

GUIDE

Quickstart

Check the readability of a public webpage by sending its URL.

curl -X POST "https://api.eu.apyhub.com/apyhub/score-readability/file_url" \
  -H "apy-token: $APY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "https://assets.apyhub.com/samples/sample.html"
  }'

What you'll get back

Returns a JSON object with a data object. Inside data, the response includes stats with text counts and timing metrics, and either flesh_kincaid_reading_ease or wiener_sachtextformel depending on the response variant.

{
  "data": {
    "stats": {
      "words": 95,
      "sentences": 8,
      "characters": 512,
      "paragraphs": 2,
      "reading_time": 6.49,
      "speaking_time": 38,
      "avg_word_length": 5.39,
      "avg_sentence_length": 11.88,
      "avg_paragraph_length": 4
    },
    "flesh_kincaid_reading_ease": {
      "class": "8th & 9th grade",
      "label": false,
      "level": 6.49,
      "score": 65.74,
      "class_label": "Plain English. Easily understood by 13- to 15-year-old students."
    }
  }
}
TRY ITLIVE · 250 ATOMS
Loading your default key…
The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.
body*
Publicly accessible web page URL.

About this endpoint

What it does

Scores the readability of a publicly accessible web page fetched from the provided file_url. The response returns readability statistics plus one readability model result, with the model depending on the schema branch used.

Request Body

ParameterTypeMandatoryDescription
file_urlStringYesPublicly accessible web page URL. Must be a URI.
languageENUMNoAllowed values: english, german. Default: english.

Response

Returns a JSON object with a data object field. Inside data, the response includes a stats object plus one readability result object: either flesh_kincaid_reading_ease or wiener_sachtextformel, depending on the response branch.

ParameterTypeMandatoryDescription
dataObjectNoWrapper object containing the readability output.
data.statsObjectNoAggregate text statistics.
data.stats.wordsIntegerNoNumber of words.
data.stats.sentencesIntegerNoNumber of sentences.
data.stats.charactersIntegerNoNumber of characters.
data.stats.paragraphsIntegerNoNumber of paragraphs.
data.stats.reading_timeNumberNoEstimated reading time in seconds.
data.stats.speaking_timeNumberNoEstimated speaking time in seconds.
data.stats.avg_word_lengthNumberNoAverage word length.
data.stats.avg_sentence_lengthNumberNoAverage sentence length.
data.stats.avg_paragraph_lengthNumberNoAverage paragraph length.
data.flesh_kincaid_reading_easeObjectNoReadability result for the Flesh-Kincaid Reading Ease branch. Contains class, label, level, score, and class_label.
data.wiener_sachtextformelObjectNoReadability result for the Wiener Sachtextformel branch. Contains class, label, level, score, and class_label.

Body

Name
Type
Description
bodyREQUIRED
object
—
▣ COMMON ERRORS

Errors any endpoint can return

400bad_request

Required parameter missing or malformed body.

401unauthorized

API key missing, revoked, or not authorized for this service.

429rate_limited

Your plan's per-second rate exceeded. Retry with exponential backoff.

503upstream_busy

Backend temporarily unavailable. Try again in a few seconds.

Similar APIs

Closest matches in the catalog based on this service.

CALLReadability Scores APIApyHubCALLBasic Text Analysis APInick creightonCALLExtract and Analyze Content from Web Page APISumalya APIsCALLExtract Readable Content from HTML APIDosvak LLC