{"success":true,"version":"v1","request":{"tool":"get_calculator_schema","calculator_id":"date-difference"},"result":{"entity_type":"calculator","id":"date-difference","calculator_id":"date-difference","canonical_url":"https://tttkmbb.com/everyday/date-difference","name":"Date Difference Calculator","title":"Date Difference Calculator – Days, Weeks, Months and Business Days Between Two Dates","category":"everyday","category_name":"Everyday Life","tool_name":"calculate_date_difference","featured_mcp_tool":true,"description":"Counts the days between two ISO dates and expresses the gap as weeks and days, as a calendar breakdown in years, months and days, and as business days (Monday–Friday, public holidays not excluded).","use_when":"You need the number of days, weeks or working days between two dates, or a calendar-style 'x years y months z days' difference.","do_not_use_when":"You want to add or subtract a number of days from a date (use add-days), or you need an age with the next birthday (use age).","inputs":[{"name":"start_date","label":"Start date","type":"date","required":true,"description":"First date (ISO 8601, YYYY-MM-DD).","example":"2026-01-01"},{"name":"end_date","label":"End date","type":"date","required":true,"description":"Second date (YYYY-MM-DD). If it is earlier than start_date the dates are swapped and a note is returned.","example":"2026-12-25"},{"name":"include_end_date","label":"Include end date","type":"boolean","required":false,"default":false,"description":"true counts both endpoints (adds one day to days, weeks/days and business_days), e.g. for inclusive rental or leave periods.","example":false}],"outputs":[{"name":"days","label":"Days","type":"integer","unit":"days","decimals":4,"description":"end_date − start_date in days (+1 when include_end_date is true)."},{"name":"weeks","label":"Whole weeks","type":"integer","unit":"weeks","decimals":4,"description":"floor(days / 7)."},{"name":"remaining_days","label":"Remaining days","type":"integer","unit":"days","decimals":4,"description":"days − 7 × weeks."},{"name":"weeks_and_days","label":"Weeks and days","type":"string","decimals":4,"description":"Same gap written as weeks and days."},{"name":"calendar_years","label":"Calendar years","type":"integer","decimals":4,"description":"Whole years between the two dates (not affected by include_end_date)."},{"name":"calendar_months","label":"Calendar months","type":"integer","decimals":4,"description":"Whole months beyond the years."},{"name":"calendar_days","label":"Calendar days","type":"integer","decimals":4,"description":"Days beyond the whole months."},{"name":"calendar_text","label":"Calendar difference","type":"string","decimals":4,"description":"Years, months and days written out (zero parts omitted)."},{"name":"business_days","label":"Business days","type":"integer","unit":"days","decimals":4,"description":"Mondays to Fridays among the counted days (public holidays are not excluded)."}],"input_schema":{"type":"object","properties":{"start_date":{"description":"First date (ISO 8601, YYYY-MM-DD).","type":"string","format":"date","examples":["2026-01-01"]},"end_date":{"description":"Second date (YYYY-MM-DD). If it is earlier than start_date the dates are swapped and a note is returned.","type":"string","format":"date","examples":["2026-12-25"]},"include_end_date":{"description":"true counts both endpoints (adds one day to days, weeks/days and business_days), e.g. for inclusive rental or leave periods.","type":"boolean","default":false,"examples":[false]}},"additionalProperties":false,"required":["start_date","end_date"]},"output_schema":{"type":"object","properties":{"days":{"description":"end_date − start_date in days (+1 when include_end_date is true). Unit: days.","type":"integer","x-unit":"days"},"weeks":{"description":"floor(days / 7). Unit: weeks.","type":"integer","x-unit":"weeks"},"remaining_days":{"description":"days − 7 × weeks. Unit: days.","type":"integer","x-unit":"days"},"weeks_and_days":{"description":"Same gap written as weeks and days.","type":"string"},"calendar_years":{"description":"Whole years between the two dates (not affected by include_end_date).","type":"integer"},"calendar_months":{"description":"Whole months beyond the years.","type":"integer"},"calendar_days":{"description":"Days beyond the whole months.","type":"integer"},"calendar_text":{"description":"Years, months and days written out (zero parts omitted).","type":"string"},"business_days":{"description":"Mondays to Fridays among the counted days (public holidays are not excluded). Unit: days.","type":"integer","x-unit":"days"}}},"formula":"days = end_date − start_date (+1 if include_end_date); weeks = floor(days / 7); remaining_days = days mod 7; business_days = number of Mon–Fri dates in [start_date, end_date) or [start_date, end_date] when inclusive; calendar breakdown = whole years, months, then days borrowed from the month before end_date","method":"Counts calendar days in UTC without times of day. By default the count is exclusive of end_date, so Monday to Friday of one week is 4 days and 4 business days; set include_end_date for 5.","sources":[{"name":"ISO 8601 – Date and time format (Wikipedia)","url":"https://en.wikipedia.org/wiki/ISO_8601","type":"reference","retrieved_at":"2026-09-23"},{"name":"Business day (Wikipedia)","url":"https://en.wikipedia.org/wiki/Business_day","type":"reference","retrieved_at":"2026-09-23"}],"freshness":{"type":"static","max_age_seconds":null,"note":"Deterministic formula with fixed constants; results never go stale. Inputs supplied by the caller determine the output."},"examples":[{"name":"2026-01-01 to 2026-12-25","inputs":{"start_date":"2026-01-01","end_date":"2026-12-25"},"expected":{"days":358,"weeks":51,"remaining_days":1,"weeks_and_days":"51 weeks 1 day","calendar_years":0,"calendar_months":11,"calendar_days":24,"calendar_text":"11 months 24 days","business_days":256},"url":"https://tttkmbb.com/api/v1/calculate/date-difference?start_date=2026-01-01&end_date=2026-12-25"},{"name":"2025-11-05 to 2026-03-15 inclusive","inputs":{"start_date":"2025-11-05","end_date":"2026-03-15","include_end_date":true},"expected":{"days":131,"weeks":18,"remaining_days":5,"weeks_and_days":"18 weeks 5 days","calendar_months":4,"calendar_days":10,"calendar_text":"4 months 10 days","business_days":93},"url":"https://tttkmbb.com/api/v1/calculate/date-difference?start_date=2025-11-05&end_date=2026-03-15&include_end_date=true"}],"faq":[{"q":"Does business_days exclude public holidays?","a":"No. It only excludes Saturdays and Sundays; subtract the holidays of your jurisdiction yourself."},{"q":"Why does the calendar breakdown not add up to the day count?","a":"Months have different lengths, so 'x months y days' is a calendar convention: whole months are counted first and the leftover days are borrowed from the month preceding end_date."}],"tags":["date difference","days between dates","business days","working days","weeks between dates"],"related":[{"calculator_id":"add-days","reason":"Add or subtract days from a date."},{"calculator_id":"age","reason":"Exact age with next-birthday countdown."},{"calculator_id":"days-until","reason":"Countdown from today to a target date."}],"links":{"html":"https://tttkmbb.com/everyday/date-difference","markdown":"https://tttkmbb.com/everyday/date-difference.md","json":"https://tttkmbb.com/everyday/date-difference.json","api":"https://tttkmbb.com/api/v1/calculate/date-difference","schema":"https://tttkmbb.com/api/v1/calculators/date-difference","openapi":"https://tttkmbb.com/openapi.json","mcp":"https://tttkmbb.com/mcp"},"version":"v1","updated_at":"2026-09-23"},"timestamp":"2026-09-23T23:24:38Z","next_actions":[{"tool":"calculate_date_difference","calculator_id":"date-difference","reason":"Run Date Difference Calculator with the inputs above."}],"links":{"markdown":"https://tttkmbb.com/everyday/date-difference.md"}}