Readability Score — analyze plain text clarity

Readability Scores API

Hosted on ApyHub

What it does

Readability Score analyzes plain text and returns readability metrics you can use to check how easy the text is to read. Send a text string, and choose language as english or german to select the scoring algorithm.

The response includes text stats such as words, sentences, characters, and paragraphs, plus estimated reading_time, speaking_time, and average lengths for words, sentences, and paragraphs. For English text, you also get flesh_kincaid_reading_ease; for German text, the service returns wiener_sachtextformel. Each score object includes the measured level, score, class, label, and class_label.

Use Readability Score when you need to assess documentation, marketing copy, help articles, or user-facing product text before publishing. It gives you a fast way to compare drafts, enforce writing guidelines, or flag content that is too dense for your target audience.

Quickstart

Send some plain text to get a readability score back.

curl -X POST "http://localhost:8080/apyhub/score-readability-of-plain-text" \
  -H "apy-token: $APY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"The quick brown fox jumps over the lazy dog. This sentence is simple and easy to read. Children enjoy reading short books."}'

What you'll get back

Returns a JSON object with a data object. Inside data, stats contains text metrics such as words, sentences, characters, paragraphs, reading_time, speaking_time, avg_word_length, avg_sentence_length, and avg_paragraph_length, and flesh_kincaid_reading_ease contains the readability result for English text.

{
  "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."
    }
  }
}

About this endpoint

What it does

Scores raw plain text for readability and returns text statistics plus a readability result for the selected language algorithm. The request body must include the text to analyze, and may include language to choose between the English and German scoring methods.

Request Body

Parameter	Type	Mandatory	Description
text	String	Yes	Raw text to analyse.
language	ENUM	No	Scoring algorithm to use. Allowed values: `english`, `german`. Default: `english`. `english` returns Flesch-Kincaid Reading Ease; `german` returns Wiener Sachtextformel.

Response

Returns a JSON object with a data object field. Inside data, stats is an object with text statistics, and the readability result is returned as either flesh_kincaid_reading_ease or wiener_sachtextformel, depending on the selected algorithm.

Parameter	Type	Mandatory	Description
data	Object	Yes	Response wrapper object. Contains `stats` and one readability result object.
data.stats	Object	Yes	Text statistics object.
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 returned for `language: english`. Contains `class`, `label`, `level`, `score`, and `class_label`.
data.flesh_kincaid_reading_ease.class	String	No	Readability class.
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	Flesch-Kincaid Reading Ease score.
data.flesh_kincaid_reading_ease.class_label	String	No	Human-readable class label.
data.wiener_sachtextformel	Object	No	Readability result returned for `language: german`. Contains `class`, `label`, `level`, `score`, and `class_label`.
data.wiener_sachtextformel.class	String	No	Readability class.
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	Wiener Sachtextformel score.
data.wiener_sachtextformel.class_label	String	No	Human-readable class label.

Notes

The response schema is a oneOf: the top-level shape is the same, but the readability result field changes with the selected language. Read data.flesh_kincaid_reading_ease for English scoring, or data.wiener_sachtextformel for German scoring.

Body

Name

Type

Description

bodyREQUIRED

object

—

Quickstart

What you'll get back

About this endpoint

What it does

Request Body

Response

Notes

Body

Errors any endpoint can return