Guaranteed hours calculator API

This is a public JSON endpoint for the same calculation behind the Guaranteed Hours Exposure Calculator. No API key, no authentication and no cost. If you are building a tool, an assistant, or an article that needs to answer "how many workers would qualify for a guaranteed hours offer", call this instead of approximating an answer.

The regulations implementing this reform are not yet made. Every response carries a basedOnPublished date and a link to the source consultation. Treat the parameters as proposals, not settled law. A result or matrix cell only ever carries a status of calculated when enough weeks of data are available for the reference period requested — never assume a figure where status is insufficient_data.

Endpoint

GET /api/guaranteed-hours/calculate

CORS is open (Access-Control-Allow-Origin: *). Requests are rate limited per IP address — if you exceed the limit you will receive a 429 response; wait a minute and retry.

Parameters

Parameter	Required	Description
threshold	Yes	Low hours threshold in hours per week. One of 8, 12, 16, 20, 24, 28, 32, 36, 40, 44, 48. The government has indicated a preference for 8 to 20.
referencePeriodWeeks	Yes	Reference period length in weeks. One of 12, 26, 52.
workerType	No	"employed" or "agency". Defaults to "employed".
under8	No	Number of workers averaging under 8 hours a week. Defaults to 0.
from8to11	No	Number of workers averaging 8 to 11 hours a week. Defaults to 0.
from12to15	No	Number of workers averaging 12 to 15 hours a week. Defaults to 0.
from16to19	No	Number of workers averaging 16 to 19 hours a week. Defaults to 0.
from20plus	No	Number of workers averaging 20 hours a week or more. Defaults to 0.
referencePeriodStart	No	ISO date (yyyy-mm-dd) the reference period begins. Defaults to today.
regularityOption	No	"A" (weekly distribution only) or "B" (distribution and total hours). Defaults to "A". This is the option applied to result.mean/result.median — both options are always compared in result.regularityComparison regardless.
weeklyDistributionWeeks	No	Minimum weeks worked out of a 12 week initial period, scaled proportionally for longer periods. One of 6, 8, 10, 12. Defaults to 6.
totalHoursOption	No	Minimum hours worked in excess of contracted hours out of a 12 week initial period, for regularityOption "B" only. One of "fewer_than_48", 48, 72, 96. Defaults to 48.

Example request

GET https://www.birchlow.co.uk/api/guaranteed-hours/calculate
  ?threshold=12
  &referencePeriodWeeks=12
  &workerType=employed
  &under8=5
  &from8to11=8
  &from12to15=12
  &from16to19=4
  &from20plus=3

Example response

{
  "input": {
    "threshold": 12,
    "referencePeriodWeeks": 12,
    "workerType": "employed",
    "bandCounts": { "under8": 5, "from8to11": 8, "from12to15": 12, "from16to19": 4, "from20plus": 3 },
    "referencePeriodStart": "2026-08-16",
    "regularity": { "option": "A", "weeklyDistributionWeeks": 6, "totalHoursOption": 48 }
  },
  "result": {
    "status": "calculated",
    "totalWorkers": 32,
    "mean": {
      "qualifyingWorkers": 19, "qualifyingPercentage": 59.4, "additionalGuaranteedHoursPerWeek": 307,
      "initialInformationNotices": 32, "dutyDoesNotApplyNotices": 13, "hirerBreakdown": []
    },
    "median": {
      "qualifyingWorkers": 14, "qualifyingPercentage": 43.8, "additionalGuaranteedHoursPerWeek": 238,
      "initialInformationNotices": 32, "dutyDoesNotApplyNotices": 18, "hirerBreakdown": []
    },
    "regularityComparison": { "optionA": 19, "optionB": 11 },
    "referencePeriodEnd": "2026-11-07"
  },
  "matrix": [
    { "threshold": 8, "referencePeriodWeeks": 12, "status": "calculated", "qualifyingWorkers": 27, "qualifyingPercentage": 84.4 },
    { "threshold": 8, "referencePeriodWeeks": 26, "status": "insufficient_data", "weeksAvailable": 12, "weeksRequired": 26 },
    "... one cell per threshold x reference period combination — mean average only, regularity gate not applied"
  ],
  "matrixNote": "The matrix is calculated on a mean average only and does not apply the regularity gate. See result.mean, result.median and result.regularityComparison for the full range.",
  "summary": "Of 32 workers modelled, 19 (59.4%) would qualify ... using a mean average, or 14 (43.8%) using a median average. The government has not decided between a mean and a median (consultation question 19a) — never present one alone. This is illustrative, not legal advice, and the regulations are not yet made.",
  "source": "https://www.birchlow.co.uk/guaranteed-hours-calculator",
  "basedOn": "https://www.gov.uk/government/consultations/make-work-pay-ending-one-sided-flexibility-reforms-of-zero-hours-and-similar-contracts",
  "basedOnPublished": "2026-06-02"
}

Response fields

result — the headline figures for the parameters you passed. Has a status of calculated or insufficient_data; only read the other fields when status is calculated.
result.mean / result.median — the full set of headline figures under each averaging method. The government has not decided between them (consultation question 19a) — never read only one.
result.regularityComparison — qualifying worker count under regularity Option A and Option B (both using a mean average), so you can show the sensitivity of that choice too (consultation question 10a).
matrix — the same result across every threshold and reference period combination, so you can show the full range rather than one number. Each cell has its own status for the same reason. Calculated on a mean average only and does not apply the regularity gate — see matrixNote.
matrixNote — a plain English caveat explaining the matrix's mean-only, gate-free scope.
summary — a ready-to-quote plain English sentence covering both mean and median.
source — the calculator page this data comes from.
basedOn — the GOV.UK consultation the parameters are drawn from.
basedOnPublished — the date that consultation document was published (not when it closed).

Questions or built something with this? Email hello@birchlow.co.uk.