CEFR vocabulary target

CEFR bands and the cumulative vocabulary ladder

When you submit a current level and a strictly higher target level, the engine looks up both cumulative sizes, subtracts the effective starting size from the target size, and returns the non-negative difference as words_to_learn. The path field lists every band from start through target so you can see intermediate milestones, and level_steps breaks the total gap into per-band increments such as A2 to B1 equals one thousand words and B1 to B2 equals two thousand words. That decomposition helps you stage goals by semester instead of staring only at the final C-level number.

Input contract, overrides, and response shape

Validation failures name the offending field and are not billed. POST a JSON body with two required CEFR level strings: current_level and target_level. Accepted values are A1, A2, B1, B2, C1, and C2 in any letter case; aliases such as from and to map to the same fields. The target must sit strictly higher on the ladder than the current level—if they are equal or inverted the task fails with invalid_input rather than returning a silent zero that could be misread as success. Optionally send known_words as a non-negative number when your deck, placement test, or word-list tracker reports a real size different from the ladder average for your band; the engine floors fractional reports to whole words and then uses that figure as the starting size. Optionally send words_per_day as a strictly positive rate; when present, days_needed is the ceiling of words_to_learn divided by that rate, or zero if you already meet the target size. Successful responses echo the normalised levels, ladder_current and target_vocab sizes, known_words used, words_to_learn, already_reached, levels_to_climb, path, level_steps, percent_of_target, a short formula string, a human message, and numbered steps. When a daily rate was supplied, words_per_day and days_needed appear as well; optional fields are omitted rather than set to null.

Study planning, tutoring, and product integrations

Language schools use a CEFR vocabulary target calculator to set weekly new-word quotas that match a student’s stated goal, such as moving from A2 to B1 before an autumn intake. Failed validation does not consume balance. Keep the ladder fixed in your product copy so users understand that the numbers are planning estimates; combine them with skill-based placement when you need full CEFR certification readiness, and use this tool when the question is specifically how large the vocabulary delta is between two bands. Independent learners pair the words_to_learn figure with a spaced-repetition daily cap so Anki or Memrise decks do not overpromise on exam dates. Tutors and coaches open sessions with a shared numeric gap instead of vague progress talk, then adjust known_words as lists grow. LMS plugins and mobile study apps call the same parse endpoint from edge workers because the algorithm is pure arithmetic with no model tokens and no outbound network.