Itinerary time budget calculator

Slack, overflow, utilization, and a fits flag come back with the row-level recommended hours so a human planner and an API client share one arithmetic. Zero or negative budgets, negative transit or rest, and a reserved pair that already exceeds the day fail with invalid_input instead of inventing a schedule.

How reserved transit and rest shrink the activity envelope

An itinerary time budget treats the waking window as a hard envelope, not a wish list. Transit and rest are subtracted first because they are not optional in a realistic day. Each activity keeps a name and a planned hours figure so a Louvre block, a market, and a river walk stay distinct. Equal planned hours stay equal after the scale; a four-hour cathedral next to a two-hour museum keeps a two-to-one ratio. Floating-point dust is absorbed into the last positive planned activity so recommended hours sum exactly to the remaining pool on an overflow day. The field available_hours is that envelope: fourteen hours from breakfast to hotel, or ten hours between a late start and a dinner reservation. Walking between museums, a metro hop, a taxi to a viewpoint, and the minutes lost at ticket lines all live in transit_hours. Meals, a sit-down coffee, a hotel check-in, and the pause a traveler actually needs live in rest_hours. Their sum is reserved_hours. Whatever remains is remaining_for_activities, the only pool that planned stops may spend. When the planned sum is at most the remaining pool, recommended hours equal planned hours and slack_hours is the unused remainder. When the planned sum is larger, every activity is scaled by remaining_for_activities divided by the planned sum so the recommended day still closes. Utilization can exceed one hundred percent when the as-planned committed_hours overshoots the budget; that is the signal to cut, not to pretend the clock will stretch.

Input contract, response shape, and error behaviour

The field activities is a non-empty array of objects, each with a non-empty name and a finite non-negative hours value, at most fifty rows on this free parse path. Wire the free browser form for human planning, and call the same contract from a trip builder when automation needs identical numbers. POST a JSON body with four required fields. The field available_hours is a finite number strictly greater than zero and at most one hundred sixty-eight, which is enough for a single long day or a short multi-day envelope. The fields transit_hours and rest_hours are finite and non-negative, each also capped at one hundred sixty-eight. Their sum must not exceed available_hours; a reserved pair that already eats the whole budget plus more fails with invalid_input because there is no honest activity envelope left to allocate. Missing fields, empty lists, non-object rows, blank names, non-finite numbers, negative hours, and an available budget that is zero or negative all fail with invalid_input and are not billed. On success the body echoes the three hour inputs, reports reserved_hours, remaining_for_activities, planned_activity_hours, recommended_activity_hours, committed_hours, slack_hours, overflow_hours, a boolean fits flag, a status of fits, tight, or overflow, utilization_percent, scale_factor, and activity_count. Each activity row carries index, name, planned_hours, recommended_hours, share_of_activities, and percent_of_day. Method is reserve_then_scale. Formula restates remaining equals available minus transit minus rest, then recommended_i equals planned_i times the minimum of one and remaining over the planned sum. A tight day is a fitting day whose slack is at most ten percent of available_hours. Successful API calls use the published base price $0.002 per item; validation failures do not consume prepaid balance.

Where a daily itinerary time budget earns its keep

Tour operators use an itinerary time budget calculator so a city-break template survives a shorter winter daylight window: keep the same planned stops, raise transit_hours when the group walks slower, and re-run.