ForHosting KIT · Developer Utilities

Weekends Until Date Calculator

The weekends until date calculator counts complete Saturday–Sunday pairs inside the inclusive span from a reference date to a target date.

● BetaFree · in your browser

Run — free How it works & API

Use it from WebAPIEmailTelegramApp soon

It gives planners a practical answer without mixing partial weekends into the result. Enter two Gregorian calendar dates in YYYY-MM-DD format; the calculator accepts future or past targets, identifies the direction, reports the inclusive calendar span, and returns the number of full weekends using deterministic calendar arithmetic. The result is clear, repeatable, and ready for schedules.

What counts as a full weekend

This calculator treats a weekend as the consecutive Saturday and Sunday used by the common Monday-to-Friday working week. A weekend counts only when both of those dates are inside the inclusive interval formed by the reference date and target date. For example, a range that ends on Saturday does not include that weekend because its Sunday falls outside the range. A range that starts on Sunday also excludes the preceding Saturday–Sunday pair. By contrast, a range beginning on Saturday and ending on Sunday contains exactly one full weekend. This boundary rule is useful for planning because it avoids presenting a partial rest period as two complete available days. The calculation does not count Fridays, public holidays, local observances, or alternative weekend conventions. Both endpoint dates themselves are included when the interval is tested. The result therefore answers a precise question: how many complete Saturday–Sunday pairs are wholly available between these two calendar endpoints?

How to enter dates and read the result

Provide the reference date and target date in the strict YYYY-MM-DD format, including four digits for the year and two digits each for month and day. The calculator validates real Gregorian dates, so impossible values such as February 30 are rejected instead of being silently shifted into another month. The target may be later than, earlier than, or identical to the reference. The full-weekend count is symmetric: reversing the same endpoints does not change how many complete weekends lie in their span. The direction field explains whether the target is in the future, in the past, or on the same day relative to the supplied reference. The inclusive calendar-day total is also returned, making the interval easy to audit. No current date is assumed. If you want a countdown from today, explicitly enter today as the reference date so the saved request remains reproducible when it is run again later.

Using the count in practical plans

A full-weekend count is a compact planning measure, but it should be combined with the constraints of the activity. For a trip, each counted pair represents a Saturday and Sunday entirely inside the planning window; travel time on Friday evening or Monday morning remains outside this measure. For a project, the count can estimate how many uninterrupted weekend work sessions or recovery periods occur before a milestone, but it does not convert them into working hours. For events, it helps compare candidate windows consistently when one option begins or ends midway through a weekend. The algorithm uses only calendar values, without time zones, clock times, daylight-saving transitions, network calls, or the machine’s current date. That makes the same input produce the same result in a browser or API workflow. API use costs $0.002 per request, while the browser calculator can run the same deterministic logic locally.

What you can do with it

Plan a trip window

See how many complete Saturday–Sunday pairs fit between booking, departure, or return dates.

Estimate project weekends

Count the full weekends available before a launch, submission, renovation, or study deadline.

Compare event ranges

Evaluate candidate date windows without accidentally treating a boundary Saturday or Sunday as a complete weekend.

FAQ

Are the reference and target dates included?

Yes. Both endpoints belong to the tested interval, but a weekend counts only if its Saturday and Sunday are both included.

What happens when the target date is earlier?

The calculator counts over the same calendar span and marks the direction as past. Reversing endpoints does not change the count.

Does a range ending on Saturday count that weekend?

No. The following Sunday is outside the interval, so that Saturday–Sunday pair is not a full weekend.

Are holidays or regional weekend patterns included?

No. A weekend is strictly Saturday plus Sunday; holidays and other regional non-working days are not considered.

Does time zone or daylight saving time affect the answer?

No. The calculation uses calendar dates only and does not use clock times, time zones, or daylight-saving transitions.

What does the API request cost?

Each API request costs $0.002. The browser version runs the same deterministic calculation for free.

For developers — API access

Everything on this page is available programmatically. This section is for teams who want to wire it into their own systems; everyone else can just use the tool above.

API endpoint

POSThttps://api.kit.forhosting.com/date/weekends-until

Prefer to automate it? One authenticated POST creates the task; the result comes back by webhook or a signed link. The same capability also runs here on the web, by email and from Telegram — and soon from our app too.

Call it from your stack

curl -X POST https://api.kit.forhosting.com/date/weekends-until \
  -H "Authorization: Bearer $KIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reference_date":"2026-08-12","target_date":"2026-09-07"}'

const res = await fetch("https://api.kit.forhosting.com/date/weekends-until", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.KIT_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "reference_date": "2026-08-12",
    "target_date": "2026-09-07"
  })
});
const { task_id } = await res.json();

import os, requests

res = requests.post(
    "https://api.kit.forhosting.com/date/weekends-until",
    headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
    json={
    "reference_date": "2026-08-12",
    "target_date": "2026-09-07"
},
)
task_id = res.json()["task_id"]

<?php
$res = file_get_contents("https://api.kit.forhosting.com/date/weekends-until", false, stream_context_create([
  "http" => [
    "method"  => "POST",
    "header"  => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
    "content" => '{"reference_date":"2026-08-12","target_date":"2026-09-07"}',
  ],
]));
$task = json_decode($res, true);

body := bytes.NewBufferString(`{"reference_date":"2026-08-12","target_date":"2026-09-07"}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/date/weekends-until", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)

Example request

{
  "reference_date": "2026-08-12",
  "target_date": "2026-09-07"
}

Example response

{
  "task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
  "type": "date.weekends_until",
  "status": "queued",
  "_links": {
    "result": "/tasks/tsk_…/result"
  }
}

The API is asynchronous: the call returns a task_id immediately and the result arrives by webhook. Polling is capped at 1 req/s per task.

Pricing

Per request$0.002

Published price — no tokens, no invented credits. A failed task is never charged.

Errors

HTTP	Code	Meaning
`401`	`unauthorized`	Missing or invalid API key.
`402`	`insufficient_balance`	Your balance doesn't cover the task price.
`404`	`unknown_type`	That task type doesn't exist.
`429`	`rate_limited`	Too many requests. Use the webhook instead of polling.

Read the full KIT documentation →