← Amber English

Word analysis: method & API

Open the analysis workspace →

One coverage response includes the full vocabulary profile. The workspace uses this shared result for both views. Copy JSON and Download CSV export the currently selected view, preserving both existing formats.

Vocabulary profile

How the counts work

A token is one occurrence; a term is a lowercase spelling with curly apostrophes normalized. Repeated terms occur at least twice. Contractions and hyphenated compounds stay whole. Numbers, mixed alphanumeric words and non-ASCII words are excluded and counted separately.

NGSL 1.2 research core contains 2,809 reference entries. Bands use its frequency ranks, not CEFR levels. Multiple matching lemmas remain ambiguous. Off-list means absent from this reference, not necessarily difficult. This does not estimate your vocabulary knowledge.

Example: “The cat, the cat. Quuxxyz 123 中文. Cats run.” returns 7 tokens, 5 terms, 2 repeated terms and 2 excluded tokens.

Method: amber-english-profile/1.0. List: ngsl/1.2-research-core. Updated October 10, 2026. NGSL — Browne, Culligan & Phillips, CC BY-SA 4.0. Matching uses the published inflection list without guessing missing forms; the separate supplementary list is not included.

API for agents and developers

Send JSON to POST /api/tools/vocabulary-profile. No authentication, AI credits or saved result URL. Maximum text length: 300,000 UTF-16 code units; request body: 1,800,000 bytes. Calls are synchronous. No per-account quota is currently configured.

curl -X POST https://amberenglish.app/api/tools/vocabulary-profile -H 'Content-Type: application/json' -d '{"text":"The cat, the cat. Quuxxyz 123 中文. Cats run."}'

Optional scope: {"startParagraph":0,"endParagraph":1}. The range is half-open over parsed body paragraphs; Markdown headings do not occupy paragraphs. Omit it to analyze all text.

Schema vocabulary-profile/1 returns counts, distribution, terms, method, reference and source. Each term includes spelling, count, band, all candidate lemmas/ranks and occurrences. Occurrences contain paragraph index, UTF-16 start/end, sentence ID and original spelling. Positions refer to returned parsed paragraphs, not raw Markdown bytes. Source includes its SHA-256; reference includes data hashes. JSON from the page is this same response.

{"counts":{"tokens":7,"types":5,"repeatedTypes":2,"excludedTokens":2}}

This is a response excerpt. Read the complete example response, or use Copy JSON in your result.

Errors use {"error":{"code":"empty_input","message":"Enter English text to analyze."}}. HTTP 400: invalid_json, invalid_input, empty_input, no_english_tokens or invalid_scope; correct the input. HTTP 413: input_too_long; shorten it. HTTP 415: unsupported_media_type; send application/json. HTTP 500: analysis_failed; retry the same input. The webpage times out after 20 seconds and preserves your input for retry. Repeated calls have no saved side effects.

Submitted text and results are not public pages. Responses use no-store and noindex. Do not put private text in URLs.

List coverage

How coverage and gaps work

Coverage is matched word occurrences divided by all counted English word occurrences. It describes a text and list, not personal understanding. The target is a calculation aid, not a reading level or comprehension guarantee.

Custom lists match exact lowercase spellings, with curly apostrophes normalized. “cat” does not include “cats”. Separate entries with whitespace, commas or semicolons; duplicates count once. Phrases are not supported: whitespace separates words. An empty list is valid and matches nothing. CSV headers, counts and other punctuation are not supported.

NGSL matches any form explicitly included in the NGSL 1.2 research core. Multiple candidate lemmas remain unresolved in the embedded profile; matching does not select a meaning. The supplementary list is excluded. NGSL — Browne, Culligan & Phillips, CC BY-SA 4.0.

Gaps are sorted by descending count, then spelling. Adding the first N gap forms covers the fewest forms needed to reach the selected token target; ties have equal contribution. Each form includes all its occurrences. Repeated contribution counts occurrences beyond the first for each unmatched form. Contributions are descriptive, not study recommendations.

Example: “The cat, the cat. Cats run. Quuxxyz.” with “the, cat” matches 4 of 7 tokens (57.14%). The three gaps are cats, quuxxyz and run. A 98% target requires all seven tokens, so three more forms are needed.

Counting follows the shared vocabulary profiler: Markdown headings excluded, contractions and hyphenated words kept whole, numbers and non-ASCII tokens excluded. Method: amber-vocabulary-coverage/1.0; profile: amber-english-profile/1.0. Updated October 10, 2026.

API for agents and developers

Send JSON to POST /api/tools/vocabulary-coverage. Anonymous synchronous analysis, no AI credits, no saved side effects. Maximum text: 300,000 UTF-16 code units; custom list: 100,000 characters; request: 1,800,000 bytes. No per-account quota is currently configured.

curl -X POST https://amberenglish.app/api/tools/vocabulary-coverage -H 'Content-Type: application/json' -d '{"text":"The cat, the cat. Cats run. Quuxxyz.","list":{"kind":"custom","text":"the, cat"},"targetRatio":0.98}'

Omit list for NGSL or use {"kind":"ngsl"}. Optional targetRatio is a number from 0 to 1, default 0.98. Optional scope is {"startParagraph":0,"endParagraph":1}, a half-open range over parsed body paragraphs.

Schema vocabulary-coverage/1 includes the complete profile, versioned list identity and SHA-256, counts, unrounded ratio, target and sorted gaps. Each gap contains spelling, count, occurrence positions, contribution and cumulative matched tokens. Positions are UTF-16 offsets inside returned paragraphs. The first target.additionalTypes gaps form the target prefix.

Complete reproducible response. The webpage copies the same JSON and exports gaps as CSV. CSV includes contribution, cumulative tokens, target inclusion and paragraph indices. It is a report, not the plain spelling-list input format.

Errors use {"error":{"code":"invalid_list","message":"…"}}. HTTP 400: invalid_input, invalid_json, empty_input, no_english_tokens, invalid_scope, invalid_list, invalid_target; correct the input. HTTP 413: input_too_long or list_too_long; shorten the input. HTTP 415: unsupported_media_type; use application/json. HTTP 500: analysis_failed; retry. The page times out after 20 seconds and retains input.

Responses use no-store and noindex. Submitted materials do not become public pages; keep private text out of URLs. Account-level book access remains authenticated separately.