Readability metrics API: 17 proven formulas in 86 languages

Reference

Parameters

Name	Type	Required	Description
`text`	string	one of text/url	Text to analyse, minimum 50 characters.
`url`	string	one of text/url	Public page to fetch and analyse, maximum 2 MB.
`lang`	string	no	Language code mapped to ReadSight: en to en-us, de to de-1996. Default: en.
`format`	string	no	json or jsonp. Default: json.
`callback`	string	no	JSONP callback name. Default: callback.

Example request

curl -s "https://api2.globus.studio/v2/readability-check?text=Thequickbrownfoxjumpsoverthelazydog.Thisisasimplesentence.&lang=en"

Open documentation

Readability metrics turn a block of text into numbers: how many words and sentences it has, how long those sentences are and which school grade a reader needs to follow it. One request scores a page with Flesch, Gunning Fog, SMOG and fourteen more formulas, then returns the statistics behind each score.

The scoring engine is the open-source ReadSight library under the MIT licence. It covers 86 languages and 17 formulas with language-specific coefficients.

What the readability metrics API returns

The response has four blocks. statistics counts characters, words, sentences and syllables, plus three averages. scores holds the formulas with their numbers. interpretation turns the result into a level, a target audience and two time estimates. language echoes the language that was used for the coefficients.

{
    "success": true,
    "statistics": {"words": 45, "sentences": 5, "avg_words_per_sentence": 9, "avg_syllables_per_word": 1.78},
    "scores": {
        "flesch_reading_ease": {"score": 47.3, "description": "Difficult"},
        "flesch_kincaid_grade": 8.9,
        "gunning_fog": 8,
        "average_grade": 8.1
    },
    "interpretation": {"level": "middle_school", "reading_time_minutes": 1},
    "language": "en",
    "language_used": "en-us"
}

Send text directly, or send url and the readability metrics API fetches the page itself, up to 2 MB. Pick one. Text shorter than 50 characters is rejected because a single sentence cannot support a grade.

Grades are school years, not quality marks

Every formula estimates the years of schooling a reader needs. A grade of 9 means a fourteen-year-old can follow the text. That is a statement about sentence length and word length, nothing else. A precise text with short words scores lower than a vague text with long ones.

Read the number as a direction. If a product page aimed at small business owners scores at grade 15, the sentences are too long for the audience. If a legal notice scores at grade 6, words may have been cut at the cost of precision. Both cases need a human decision, and the decision is not “make the number smaller”.

The raw statistics are often more useful than the grade. avg_words_per_sentence above 25 is a reliable sign of a paragraph that needs splitting. avg_syllables_per_word above 2 marks a dense vocabulary.

One language, one set of coefficients

Formulas do not transfer between languages. The syllable count behind Flesch works for English and fails for German compounds. ReadSight solves this with per-language coefficients, and the endpoint maps your lang to the engine locale: en becomes en-us, de becomes de-1996, and so on.

Pass the right lang to the readability metrics API. The default is en. A Russian page scored as English returns numbers that look plausible and mean nothing. When a formula has no support for the language, its value comes back as null, and average_grade is calculated only from the formulas that do apply.

Short texts stay unreliable in any language. The API accepts 50 characters, but a two-sentence sample will swing ten grades between runs. Score a full article, not a paragraph.

Reading time and speaking time

reading_time_minutes and speaking_time_minutes are estimates for an average reader and an average speaker. They are useful for video scripts and documentation intros. They are not a promise: a technical text with code samples reads slower than the estimate, and a list scrolls faster.

Run readability metrics on a URL

Point the endpoint at a public URL:

curl -s "https://api2.globus.studio/v2/readability-check?url=https://example.com/article&lang=en"

The readability metrics API blocks private ranges and loopback addresses, follows the same public-only rule as the rest of the API, and gives up after a few seconds. For a page behind a login, fetch the HTML yourself and post the text instead.

Reading the failure cases

Text or URL parameter is required means both inputs were empty. Text too short for analysis (min 50 chars) is a hard stop, not a warning. Failed to fetch URL content covers a private address, a non-HTML response and a timeout.

A page that returns null for most formulas is not broken. It means the chosen language has coefficients for fewer formulas than English does. Compare results within one language and one formula, never across them.

To confirm that the text is in the language you think it is, use the language detection API; pair it with readability metrics when a translation has to pass a reader, not only a model. For filler text of a fixed length, see the text placeholder API. The rest of the catalogue sits on the API page.

Further reading: WCAG 2.1 on reading level.