跳转到内容
POST AI agent ready /v1/text/readability

Readability API - Flesch, Gunning Fog & Grade Level

Runs a readability analysis on any English text and returns three standard indexes plus the underlying counts. Flesch-Kincaid Grade maps to US school grade levels, Flesch Reading Ease runs 0-100 (higher is easier), and Gunning Fog estimates the years of formal education needed. The response also includes sentence, word, syllable, and complex-word totals so you can compute other indexes yourself.

Parameters

stringrequired

The text to analyze.

Code examples

curl -X POST https://api.botoi.com/v1/text/readability \
  -H "Content-Type: application/json" \
  -d '{"text":"Plain language helps readers understand content faster. Use short sentences and common words."}'

When to use this API

Enforce plain-language standards

Gate CMS publishing on a minimum Flesch Reading Ease score so marketing copy stays accessible to a broad audience before it goes live.

Check legal and medical drafts

Regulatory guidelines (US Plain Writing Act, NHS content style) target 6th to 8th grade reading levels. Score each draft and flag sections that exceed the threshold.

Optimize blog posts for SEO

Search engines favor content that matches reader comprehension. Track grade level alongside word count and tighten sections that score too high.

Compare writing across authors

Score every post in a publication to surface consistency issues when one author drifts into academic prose while others stay conversational.

Frequently asked questions

Which readability indexes does the API return?
Flesch-Kincaid Grade (US school grade), Flesch Reading Ease (0-100, higher is easier), and Gunning Fog (years of education). All three use the same sentence, word, and syllable counts, so scores are consistent across indexes.
How are syllables counted?
The API strips non-letter characters, groups consecutive vowels as one syllable, and subtracts a silent trailing "e". It is a heuristic, so uncommon words occasionally miss by one syllable. For long passages the error averages out.
What counts as a complex word?
Any word with three or more syllables, which is the standard Gunning Fog definition. The response exposes complex_words directly so you can build your own SMOG or LIX scores without extra calls.
Does this work for non-English text?
The formulas and syllable heuristics are calibrated for English. Other languages return numbers, but the grade mapping is not meaningful. Use /v1/text/language to detect the language before scoring.
How much text should I send?
Aim for at least 100 words. Short snippets produce unstable scores because a single long word or sentence swings the ratios heavily.

Get your API key

Free tier includes 5 requests per minute with no credit card required. Upgrade for higher limits.

Sign up free View full docs