# Readability Score Calculator & Word Frequency Counter (`data-done-right/readability-score-calculator`) Actor

Readability score calculator and word frequency counter for texts, web pages and dataset fields in bulk. Flesch Reading Ease, Flesch-Kincaid, Gunning Fog, SMOG, Coleman-Liau, ARI, consensus grade, word count, reading time, top words and lexical diversity.

- **URL**: https://apify.com/data-done-right/readability-score-calculator.md
- **Developed by:** [Data Done Right](https://apify.com/data-done-right) (community)
- **Categories:** Developer tools, Automation, Other
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.64 / 1,000 text analyzeds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Readability Score Calculator & Word Frequency Counter

This **readability score calculator** measures how easy your writing is to read, in bulk. Paste texts, give page URLs or pick a dataset and get one row per item with **Flesch Reading Ease, Flesch-Kincaid grade, Gunning Fog, SMOG, Coleman-Liau and ARI**, a consensus grade level, a plain-language reading level, **word count, sentence count, syllable count, reading time and speaking time**, plus a **word frequency counter** (top words with counts and percentages), lexical diversity and your longest sentences. It runs offline inside the Actor: no API key and no external service.

Pay only for items that got statistics. Empty, failed and skipped items are free.

### What does this readability analyzer give you

- **Seven readability formulas.** Flesch Reading Ease (0-100+, higher is easier), Flesch-Kincaid grade, Gunning Fog, SMOG, Coleman-Liau, Automated Readability Index and an optional approximate Dale-Chall. A `consensusGrade` averages the grade-level formulas so you get one number to act on, and `readingLevel` gives a label such as "Standard (8th-9th grade)".
- **Word counter and text statistics.** `wordCount`, `sentenceCount`, `syllableCount`, `charCount`, `charCountNoSpaces`, `paragraphCount`, average words per sentence, average syllables per word, complex-word share.
- **Reading and speaking time.** Minutes to read silently (default 238 words per minute) and to read aloud (default 150 wpm). Both speeds are inputs.
- **Word frequency counter.** The top N words per text with `count` and `percent`, with an English stopword filter you can switch off and your own extra stopwords.
- **Lexical diversity.** `uniqueWords`, type-token ratio and the length-robust Guiraud index.
- **Longest sentences.** The longest sentences with their word counts, so you know what to split.
- **Three input modes.** One text per line, page URLs (main text extracted with trafilatura), or a field of another Actor's dataset.

### How to calculate the readability score of a text

1. Paste your texts in **Texts**, one per line (the prefill has two examples, one plain and one dense).
2. Run the Actor.
3. Open the dataset overview table or download JSON, CSV or Excel. `fleschReadingEase` and `consensusGrade` are the columns to start with.

### How to check the readability of a web page

Put the URLs in **Page URLs**. The article text is extracted with trafilatura and scored. The page `title` is returned. Public pages only, no login and no CAPTCHA solving. Pages that need JavaScript to show their text return `empty` with an explanation.

### How to count word frequency in a dataset

Pick the **Dataset** and set **Dataset field** (default `text`, dotted paths and list positions work, for example `review.text`). Every string in that field becomes a row with its own top words. To get one frequency list for a whole corpus, join your texts into one entry first.

### How to read the scores

| Flesch Reading Ease | Reading level |
|---|---|
| 90-100 | Very easy (5th grade) |
| 80-90 | Easy (6th grade) |
| 70-80 | Fairly easy (7th grade) |
| 60-70 | Standard (8th-9th grade) |
| 50-60 | Fairly difficult (10th-12th grade) |
| 30-50 | Difficult (college) |
| 10-30 | Very difficult (college graduate) |
| below 10 | Extremely difficult (professional) |

Most web content works best at Flesch 60-70 or a consensus grade of about 8.

### Input example

```json
{
  "texts": [
    "Readability is how easy a text is to read. Short sentences and plain words make a page easy to follow.",
    "Notwithstanding the aforementioned considerations, organizations should systematically evaluate their communications."
  ],
  "urls": ["https://en.wikipedia.org/wiki/Readability"],
  "topWords": 20,
  "removeStopwords": true,
  "longestSentences": 3,
  "includeDaleChall": false,
  "maxItems": 1000
}
```

### Output example

```json
{
  "index": 1,
  "source": "text",
  "textPreview": "Readability is how easy a text is to read. Short sentences and plain words make a page easy to follow.",
  "status": "analyzed",
  "wordCount": 20,
  "sentenceCount": 2,
  "syllableCount": 29,
  "charCount": 102,
  "readingTimeMinutes": 0.08,
  "speakingTimeMinutes": 0.13,
  "avgWordsPerSentence": 10.0,
  "fleschReadingEase": 74.02,
  "fleschKincaidGrade": 5.4,
  "gunningFog": 8.0,
  "smog": 8.8,
  "colemanLiau": 5.1,
  "automatedReadabilityIndex": 2.6,
  "consensusGrade": 5.3,
  "readingLevel": "Fairly easy (7th grade)",
  "englishLikely": true,
  "uniqueWords": 16,
  "lexicalDiversity": 0.8,
  "topWords": [{"word": "easy", "count": 2, "percent": 16.67}, {"word": "readability", "count": 1, "percent": 8.33}],
  "longestSentences": [{"words": 11, "text": "Short sentences and plain words make a page easy to follow."}],
  "note": "short text (under 30 words): readability scores are unstable"
}
```

### Use cases

- **SEO and content teams:** score every blog post or landing page and flag the ones above grade 10.
- **Plain-language and accessibility audits:** government, health, legal and finance copy.
- **Education:** check that reading material matches a grade level.
- **Dataset enrichment:** add readability and word counts to scraped reviews, articles or comments.
- **Writers and editors:** find the longest sentences and the most overused words.

### How much does it cost

Pay per event: **`text-analyzed` = $0.0008 per text, page or dataset item** that received statistics ($0.80 per 1,000). Empty, failed and skipped items are not charged, and `maxItems` caps your spend. There is no start fee. The Actor is light (512 MB) and analyses thousands of texts per minute; page URLs add download time.

### Honest limits

- **Readability formulas are English formulas.** Syllables are estimated with a rule-based heuristic (no dictionary), usually within a few percent, so scores can differ by a point or two from other tools. Numbers count as one syllable. Proper nouns are not counted as complex words in Gunning Fog and SMOG.
- **Other languages:** word count, sentence count, character counts, reading time and word frequencies work in any language with spaces between words (and per character for Chinese and Japanese). For Latin-script text that does not look English, the grades are still calculated but `englishLikely` is `false` and a note says to treat them as unreliable. For non-Latin scripts the grades are `null`. The built-in stopword list is English only; add your own with **Extra stopwords**.
- **Short texts (under 30 words)** give unstable scores and carry a note. SMOG is designed for 30+ sentences and joins the consensus grade from 10 sentences. Lists and headings without punctuation are treated as separate sentences only when separated by a blank line.
- **Dale-Chall (lite)** uses a rare-word proxy instead of the official 3,000-word list and is off by default.
- **Page URLs:** JavaScript-only pages, login walls and PDFs are not supported; pages are fetched with normal requests and no bot-protection evasion.
- Texts longer than **Max characters analysed** (default 200,000) are cut, and a note is added.

### FAQ

**What is a good Flesch Reading Ease score?** 60-70 is plain English that most adults follow easily. Higher is easier. Technical, legal and academic writing often scores 20-50.

**Why do I get different scores than another tool?** Tools differ in how they split sentences and count syllables. The formulas here are the standard published ones; the inputs are estimated by documented rules. Compare scores from the same tool over time rather than across tools.

**Does it work for languages other than English?** Counts, reading time and word frequency do. The grade formulas were built for English, so for other languages they are flagged and should not be relied on.

**Can I get word frequency for a whole corpus?** Each row has its own top words. Join your texts into a single entry to get a combined list.

**Are numbers counted as words?** Yes, in `wordCount` and the readability formulas (one syllable each). They are left out of the word frequency list.

**What does it do when something fails?** One bad URL or text never stops the run. The row gets a status of `failed`, `empty` or `skipped` with an `error`, is not charged, and the run's `SUMMARY` record lists the totals.

### Related tools

- **Keyword Extractor: Extract Keywords & Keyphrases from Text** for the key phrases of your texts.
- **Language Detector: Detect Text Language in Bulk (API)** to find out which language a text is in before scoring it.

# Actor input Schema

## `texts` (type: `array`):

Texts to analyse, one per line. Each entry is one result row. Example: The cat sat on the mat. It was a sunny day.

## `urls` (type: `array`):

Web pages whose main text should be analysed (extracted with trafilatura). Public pages only, no logins. Example: https://en.wikipedia.org/wiki/Readability.

## `datasetId` (type: `string`):

Optional. Pick an Apify dataset (for example the output of a scraper) and the field below is analysed for every item. Example: a dataset ID such as aBcD1234eFgH5678i.

## `datasetField` (type: `string`):

Field of each dataset item that holds the text (or a list of texts). Dotted paths work. Example: review.text or comments.0. Default: text.

## `topWords` (type: `integer`):

How many of the most frequent words to return for each text, with counts and percentages. 0 turns word frequency off. Example: 20.

## `removeStopwords` (type: `boolean`):

Skip common English words (the, and, of, to) in the word frequency list so meaningful words come first. The built-in list is English only. Example: true.

## `customStopwords` (type: `array`):

Optional extra words to leave out of the frequency list, in any language. Example: said, also, www.

## `minWordLength` (type: `integer`):

Words shorter than this many letters are left out of the frequency list. Example: 3.

## `longestSentences` (type: `integer`):

How many of the longest sentences to list per text (with their word counts), useful for finding what to shorten. 0 turns it off. Example: 3.

## `includeDaleChall` (type: `boolean`):

Also compute an approximate Dale-Chall score. It uses a rare-word proxy, not the official 3,000-word list, so treat it as indicative. Example: false.

## `language` (type: `string`):

auto guesses whether each text is English. Choose en to trust that texts are English, or other to flag every grade as English-only. Counts and word frequencies work in any language. Example: auto.

## `readingWordsPerMinute` (type: `number`):

Used for readingTimeMinutes. 238 is the average silent reading speed of adults. Example: 238.

## `speakingWordsPerMinute` (type: `number`):

Used for speakingTimeMinutes (speeches, voice-over, video scripts). 150 is a typical presentation pace. Example: 150.

## `maxItems` (type: `integer`):

Maximum texts and pages to process in this run. Items beyond the limit are listed as skipped and not charged. Example: 1000.

## `maxCharsPerText` (type: `integer`):

Longer texts are cut to this length (charCount shows the analysed length and a note is added). Example: 200000.

## `concurrency` (type: `integer`):

How many page URLs are downloaded at the same time. Example: 4.

## `timeoutSecs` (type: `number`):

Give up on a page URL after this many seconds. Example: 30.

## `proxyConfiguration` (type: `object`):

Only used for page URLs. Leave empty to download pages directly.

## Actor input object example

```json
{
  "texts": [
    "Readability is how easy a text is to read. Short sentences and plain words make a page easy to follow. Long sentences with many complicated, multisyllabic words make the same idea much harder to understand, especially for people who read quickly on a phone.",
    "Notwithstanding the aforementioned considerations, organizations implementing comprehensive documentation methodologies should systematically evaluate whether their communications demonstrate appropriate accessibility characteristics for heterogeneous audiences."
  ],
  "datasetField": "text",
  "topWords": 20,
  "removeStopwords": true,
  "minWordLength": 2,
  "longestSentences": 3,
  "includeDaleChall": false,
  "language": "auto",
  "readingWordsPerMinute": 238,
  "speakingWordsPerMinute": 150,
  "maxItems": 1000,
  "maxCharsPerText": 200000,
  "concurrency": 4,
  "timeoutSecs": 30
}
```

# Actor output Schema

## `results` (type: `string`):

All result items of this run (the default dataset), as JSON, CSV, Excel and more.

## `records` (type: `string`):

Key-value store records: the run summary and notes on any problems.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "texts": [
        "Readability is how easy a text is to read. Short sentences and plain words make a page easy to follow. Long sentences with many complicated, multisyllabic words make the same idea much harder to understand, especially for people who read quickly on a phone.",
        "Notwithstanding the aforementioned considerations, organizations implementing comprehensive documentation methodologies should systematically evaluate whether their communications demonstrate appropriate accessibility characteristics for heterogeneous audiences."
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("data-done-right/readability-score-calculator").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "texts": [
        "Readability is how easy a text is to read. Short sentences and plain words make a page easy to follow. Long sentences with many complicated, multisyllabic words make the same idea much harder to understand, especially for people who read quickly on a phone.",
        "Notwithstanding the aforementioned considerations, organizations implementing comprehensive documentation methodologies should systematically evaluate whether their communications demonstrate appropriate accessibility characteristics for heterogeneous audiences.",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("data-done-right/readability-score-calculator").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "texts": [
    "Readability is how easy a text is to read. Short sentences and plain words make a page easy to follow. Long sentences with many complicated, multisyllabic words make the same idea much harder to understand, especially for people who read quickly on a phone.",
    "Notwithstanding the aforementioned considerations, organizations implementing comprehensive documentation methodologies should systematically evaluate whether their communications demonstrate appropriate accessibility characteristics for heterogeneous audiences."
  ]
}' |
apify call data-done-right/readability-score-calculator --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,data-done-right/readability-score-calculator"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/oqSgreaPmmITZqJhk/builds/oT1RzKfZHS563fcaX/openapi.json