▣ ARTIFICIAL INTELLIGENCE · SEO

Readability Scores Documents API

Hosted on ApyHub

What it does

Readability Score analyzes a document or web page and returns text statistics plus a readability score you can use to gauge how easy the content is to read.

Send a PDF, DOC, or DOCX file to POST /file, or a publicly accessible web page URL to POST /file_url. In both cases, you can set language to english or german. The response includes stats such as words, sentences, characters, paragraphs, reading_time, speaking_time, avg_word_length, avg_sentence_length, and avg_paragraph_length.

For document analysis, the service returns flesh_kincaid_reading_ease with a class, label, level, score, and class_label. For web page analysis, it returns wiener_sachtextformel with the same fields. That makes it useful for content review pipelines, editorial QA, and checking whether customer-facing copy matches a target reading level before publishing.

▣ ENDPOINT 01 / 02

POST

Score readability of an uploaded document

http://localhost:8080/apyhub/score-readability/file

QUICKSTARTGUIDE

Quickstart

Upload a document file to check its readability score.

curl -X POST "http://localhost:8080/apyhub/score-readability/file" \
  -H "apy-token: $APY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"file":"@/path/to/document.pdf","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

API key

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.

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

Parameter	Type	Mandatory	Description
file	String	Yes	Document file to analyse. Binary upload; supported formats: PDF, DOC, or DOCX.
language	ENUM	No	Language 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.

Parameter	Type	Mandatory	Description
data	Object	No	Wrapper object containing the analysis result.
data.stats	Object	No	Text statistics for the analysed document.
data.stats.words	Integer	No	Number of words.
data.stats.sentences	Integer	No	Number of sentences.
data.stats.characters	Integer	No	Number of characters.
data.stats.paragraphs	Integer	No	Number of paragraphs.
data.stats.reading_time	Number	No	Estimated reading time in seconds.
data.stats.speaking_time	Number	No	Estimated speaking time in seconds.
data.stats.avg_word_length	Number	No	Average word length.
data.stats.avg_sentence_length	Number	No	Average sentence length.
data.stats.avg_paragraph_length	Number	No	Average paragraph length.
data.flesh_kincaid_reading_ease	Object	No	Readability analysis result for the Flesh-Kincaid Reading Ease variant. Includes `class`, `label`, `level`, `score`, and `class_label`.
data.flesh_kincaid_reading_ease.class	String	No	Readability class label.
data.flesh_kincaid_reading_ease.label	Boolean	No	Whether the text meets a standard readability threshold.
data.flesh_kincaid_reading_ease.level	Number	No	Readability level.
data.flesh_kincaid_reading_ease.score	Number	No	Readability score.
data.flesh_kincaid_reading_ease.class_label	String	No	Human-readable class description.
data.wiener_sachtextformel	Object	No	Readability analysis result for the Wiener Sachtextformel variant. Includes `class`, `label`, `level`, `score`, and `class_label`.
data.wiener_sachtextformel.class	String	No	Readability class label.
data.wiener_sachtextformel.label	Boolean	No	Whether the text meets a standard readability threshold.
data.wiener_sachtextformel.level	Number	No	Readability level.
data.wiener_sachtextformel.score	Number	No	Readability score.
data.wiener_sachtextformel.class_label	String	No	Human-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

http://localhost:8080/apyhub/score-readability/file_url

QUICKSTARTGUIDE

Quickstart

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

curl -X POST "http://localhost:8080/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

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

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

Parameter	Type	Mandatory	Description
file_url	String	Yes	Publicly accessible web page URL. Must be a URI.
language	ENUM	No	Allowed 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.

Parameter	Type	Mandatory	Description
data	Object	No	Wrapper object containing the readability output.
data.stats	Object	No	Aggregate text statistics.
data.stats.words	Integer	No	Number of words.
data.stats.sentences	Integer	No	Number of sentences.
data.stats.characters	Integer	No	Number of characters.
data.stats.paragraphs	Integer	No	Number of paragraphs.
data.stats.reading_time	Number	No	Estimated reading time in seconds.
data.stats.speaking_time	Number	No	Estimated speaking time in seconds.
data.stats.avg_word_length	Number	No	Average word length.
data.stats.avg_sentence_length	Number	No	Average sentence length.
data.stats.avg_paragraph_length	Number	No	Average paragraph length.
data.flesh_kincaid_reading_ease	Object	No	Readability result for the Flesh-Kincaid Reading Ease branch. Contains `class`, `label`, `level`, `score`, and `class_label`.
data.wiener_sachtextformel	Object	No	Readability 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.