← Back to Quick Start

Analyze Text Readability with 6 Scoring Formulas

Get Flesch Reading Ease, Gunning Fog, Coleman-Liau, and more — plus text statistics, issues, and suggestions.

What you'll learn

  • How to analyze any text and get 6 readability scores in a single call
  • How to interpret Flesch, Gunning Fog, and other formulas
  • How the API detects long sentences, complex words, and other readability issues
  • How to integrate readability checks into a content management workflow

Prerequisites

Step 1: Your first call

Analyze a simple paragraph:

curl -s -X POST /api/v1/readability/analyze \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "text": "The cat sat on the mat. It was a warm day. The sun was bright.",
    "language": "en",
    "mode": "STANDARD",
    "options": {
      "includeStatistics": true,
      "includeIssues": true,
      "includeSuggestions": true
    }
  }' | python3 -m json.tool

Expected response:

{
  "requestId": "f1a2b3c4-d5e6-...",
  "status": "OK",
  "language": "en",
  "mode": "STANDARD",
  "serviceVersion": "1.0",
  "scores": [
    {"code": "FLESCH_READING_EASE", "displayName": "Flesch Reading Ease", "value": 98.4, "unit": "score", "gradeLevel": "5th grade"},
    {"code": "GUNNING_FOG", "displayName": "Gunning Fog Index", "value": 2.8, "unit": "grade"},
    {"code": "COLEMAN_LIAU", "displayName": "Coleman-Liau Index", "value": 3.1, "unit": "grade"},
    {"code": "AUTOMATED_READABILITY", "displayName": "Automated Readability Index", "value": 1.2, "unit": "grade"},
    {"code": "SMOG", "displayName": "SMOG Index", "value": 3.0, "unit": "grade"},
    {"code": "FLESCH_KINCAID_GRADE", "displayName": "Flesch-Kincaid Grade Level", "value": 1.5, "unit": "grade"}
  ],
  "statistics": {
    "characterCount": 48,
    "wordCount": 15,
    "sentenceCount": 3,
    "paragraphCount": 1,
    "syllableCount": 16,
    "averageWordLength": 3.2,
    "averageSentenceLength": 5.0,
    "averageParagraphLength": 15.0,
    "longestSentenceWordCount": 6,
    "longestWordLength": 6
  },
  "issues": [],
  "suggestions": ["Text readability is within acceptable ranges."],
  "processingTimeMs": 8
}

Step 2: Understanding the scores

Flesch Reading Ease 0–100 scale. Higher = easier. 60–70 is standard, 90+ is very easy, below 30 is very difficult.
Gunning Fog Estimates US school grade needed to understand the text. 6 = 6th grade, 12 = high school senior.
Coleman-Liau Grade level based on character count per word and sentence. Does not require syllable counting.
Automated Readability Grade level based on characters per word and words per sentence.
SMOG Grade level based on polysyllable count. Best for health and technical writing.
Flesch-Kincaid Grade US school grade level. Widely used in government and education.

Step 3: Common use cases

Complex text (low readability)

curl -s -X POST /api/v1/readability/analyze \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "text": "The epistemological ramifications of post-structuralist deconstructionism necessitate a thoroughgoing reconceptualization of the hermeneutic frameworks traditionally employed in the exegesis of literary artifacts, particularly insofar as the ontological presuppositions undergirding conventional interpretive methodologies have been systematically problematized by contemporary critical theorists.",
    "language": "en",
    "mode": "STANDARD",
    "options": {"includeStatistics": true, "includeIssues": true, "includeSuggestions": true}
  }'
{
  "scores": [
    {"code": "FLESCH_READING_EASE", "value": -12.3, "gradeLevel": "College graduate+"},
    {"code": "GUNNING_FOG", "value": 38.2, "unit": "grade"},
    {"code": "FLESCH_KINCAID_GRADE", "value": 32.5, "unit": "grade"}
  ],
  "statistics": {
    "wordCount": 42,
    "sentenceCount": 1,
    "averageSentenceLength": 42.0,
    "averageWordLength": 9.8
  },
  "issues": [
    {"code": "VERY_LONG_SENTENCE", "message": "Sentence has 42 words (threshold: 30)", "severity": "WARNING"}
  ],
  "suggestions": [
    "Consider breaking long sentences into shorter ones for improved readability.",
    "Consider using simpler, shorter words where possible.",
    "The text is rated as 'Very Difficult'. Consider simplifying vocabulary and sentence structure."
  ]
}

Comparing two versions of copy

Analyze both versions and compare their Flesch Reading Ease scores. A higher score means more accessible content:

# Version A: 45.2 (Difficult)
# Version B: 72.8 (Standard)
# Choose Version B for a general audience

Step 4: Handling errors

Text too long

{
  "error": "VALIDATION_ERROR",
  "message": "Text length 150001 exceeds maximum 100000",
  "status": 400
}

Empty text

{
  "error": "VALIDATION_ERROR",
  "message": "text: must not be blank",
  "status": 400
}

Step 5: Integration tips

Python CMS integration

import requests

API_BASE = ""
HEADERS = {
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_API_KEY"
}

def analyze_readability(text, target_grade=8):
    """Analyze text and check if it meets the target grade level."""
    resp = requests.post(
        f"{API_BASE}/api/v1/readability/analyze",
        json={
            "text": text,
            "language": "en",
            "mode": "STANDARD",
            "options": {
                "includeStatistics": True,
                "includeIssues": True,
                "includeSuggestions": True
            }
        },
        headers=HEADERS, verify=False
    )
    resp.raise_for_status()
    data = resp.json()

    # Find Flesch-Kincaid grade
    fk_grade = next(
        (s["value"] for s in data["scores"]
         if s["code"] == "FLESCH_KINCAID_GRADE"), None
    )

    return {
        "grade_level": fk_grade,
        "meets_target": fk_grade is not None and fk_grade <= target_grade,
        "issues": data.get("issues", []),
        "suggestions": data.get("suggestions", [])
    }

result = analyze_readability("Your blog post text here...")
if not result["meets_target"]:
    print(f"Grade level {result['grade_level']} exceeds target.")
    for s in result["suggestions"]:
        print(f"  - {s}")

Next steps