Weekly study hours per course

Zero or negative budgets and a zero weight sum fail with invalid_input instead of inventing a timetable.

How credit hours and difficulty share a weekly budget

If weekly_hours is H, course i has credits c_i and difficulty d_i, the allocated hours are H times (c_i times d_i) divided by the sum of every credit-difficulty product. After proportional multiplication, floating-point rounding can leave a tiny residual so the cleaned hours no longer sum exactly to H; this endpoint absorbs that residual into the last course with a positive weight so the returned hours array is always a partition of the requested budget. Each row also reports hours_per_credit so you can see whether the plan lands near the common two-to-three hours of study per credit hour, plus share_ratio and percent for charts that should not recompute the weight sum.

Input contract, response shape, and error behaviour

The field courses is a non-empty array of objects, each with a non-empty name and a finite positive credits number. Difficulty is optional and defaults to one; when present it must be finite and strictly positive, typically one for a standard course, one and a half for a heavy STEM load, or two for an unusually demanding class. Up to forty courses are accepted on this free parse path. A parallel hours array matches the input order for scripts that only need the numeric allocation. A classic check is a twenty-hour week with Calculus II at four credits and difficulty one and a half, plus US History and Spanish I at three credits and difficulty one, which yields ten, five, and five hours. POST a JSON body with weekly_hours and courses. The field weekly_hours is a finite number strictly greater than zero and at most one hundred sixty-eight, representing the hours you can actually study this week; zero and negative values fail with invalid_input naming the field. Optional study_days is an integer from one to seven; when you send it, every course also receives hours_per_day so a five-day plan turns a ten-hour Calculus share into two hours each weekday. Missing fields, empty course lists, non-object rows, blank names, non-finite numbers, non-positive credits or difficulty, more than forty rows, a weekly budget above one hundred sixty-eight, and a weight sum of zero all fail with invalid_input and are not billed. On success the body echoes weekly_hours, reports course_count, credit_sum, and weight_sum, and returns a courses array of objects each carrying index, name, credits, difficulty, weight, share_ratio, hours, percent, and hours_per_credit. Method is credits_times_difficulty and formula restates hours_i equals weekly_hours times credits_i times difficulty_i over the sum of those products. Successful API calls use the published base price $0.002 per item; validation failures do not consume prepaid balance.

Where a weekly study allocation earns its keep

Students rebuilding a GPA after a midterm shock raise difficulty on the course that is slipping and re-run so the rescue hours come out of lighter classes rather than from an already empty Saturday. Residence-life and athletics staff embed the same contract so a travel week with only twelve study hours still assigns something to every course instead of dropping the three-credit seminar entirely. Academic advisors use a weekly study hours per course calculator so a fifteen-credit term does not quietly demand fifty hours when the student also works twenty hours a week: keep the same credits and difficulty, lower weekly_hours to the hours that still exist after sleep and shifts, and read the new split instead of guessing. Campus apps avoid shipping their own floating-point edge cases—zero budget, all-zero weights, residual rounding—because those paths are already covered by deterministic invalid_input or residual absorption.