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.
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.

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"
  },
  "result": {
    "status": "calculated",
    "totalWorkers": 32,
    "qualifyingWorkers": 19,
    "qualifyingPercentage": 59.4,
    "additionalGuaranteedHoursPerWeek": 307,
    "initialInformationNotices": 32,
    "dutyDoesNotApplyNotices": 13,
    "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"
  ],
  "summary": "Of 32 workers modelled, 19 (59.4%) would qualify for a guaranteed hours offer at a 12 hour threshold over a 12 week reference period, under the proposals in the \"Make Work Pay: ending one-sided flexibility\" consultation. 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.
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.
summary — a ready-to-quote plain English sentence.
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.