UK Petition Threshold ETA & Velocity Tracker

Tracks UK Government / Parliament e-petitions (petition.parliament.uk) and predicts, from signature velocity between runs, how many hours are left until a petition crosses one of the two statutory lines that trigger a government reaction. Built entirely on the official, public, keyless Petitions site JSON API - no scraping, no browser, no login.

Why this exists

Every open petition page on petition.parliament.uk already shows a live signature count. What it does not show - and no other public tool tracks

• is how fast that count is moving and when it will cross a threshold:

• 10,000 signatures - the government must respond in writing.

• 100,000 signatures - the petition is considered for a House of Commons debate.

What it does

1. Lists petitions from the official site (petitions.json, OGL open data), filtered by state (open/closed/all) and an optional search term, exactly like the site's own search box.
2. Scores a shortlist in full detail - petitions at or above your signature floor, plus any petition ID you explicitly watch - by fetching each one's own record (petitions/<id>.json), which carries its constituency-by-constituency, region-by-region and country-by-country signature breakdown and its threshold timestamps.
3. Diffs against the previous run - the Actor's own key-value store remembers each scored petition's signature count and the time it was last checked. On the next run it computes signatures_per_hour from the delta, and turns that rate into eta_hours_to_next_threshold and eta_next_threshold_at for whichever line (10,000 or 100,000) is still ahead. First run for a petition has no velocity yet (

   velocity_basis: "no_previous_run_recorded"
   ) - run it again later (e.g. hourly) to get a real ETA. This ETA engine is the feature: the site itself, and every other public petitions tool, only ever answers "what is the count right now" - never "at this rate, when".
4. Flags threshold crossings - crossed_response_threshold_since_previous_run and crossed_debate_threshold_since_previous_run go true the run a petition's own official timestamp for that threshold first appears, compared with what was stored last time - a genuine changed-since-last-check signal, not just a snapshot.
5. Names the top signing constituencies and their MP - each scored petition includes its highest-signing constituencies from the official breakdown, each with the sitting MP's name as published by the Petitions site itself (useful for local-angle journalism or lobbying research - "who in my MP's seat signed this").
6. Lets you run a lean alert feed - onlyApproachingOrJustCrossedThreshold drops every petition that is not within your alert window of its next threshold and has not just crossed one, so a scheduled run only ever surfaces petitions that changed in a way worth reading.

Input

Field	Type	Default	Notes
state	enum	open	open, closed, or all.
searchQuery	string	-	Same free-text search as the site's search box (q=).
watchPetitionIds	array of numbers	[]	Petition IDs (the number in petition.parliament.uk/petitions/<id>) to always score.
maxPetitionsToScan	integer	150	How many petitions to pull from the listing (25/page) before filtering.
minSignatureCount	integer	500	Skip petitions below this count in the listing pass.
maxPetitionsToScore	integer	40	Cap on full-detail fetches (= charged events) per run.
onlyApproachingOrJustCrossedThreshold	boolean	false	Lean alert mode - see above.
etaAlertWindowHours	integer	24	ETA (hours) inside which a petition counts as "approaching".
topConstituenciesCount	integer	5	Top signing constituencies (with MP) to attach per petition.

Output (one dataset row per scored petition)

{
  "petition_id": 762815,
  "url": "https://petition.parliament.uk/petitions/762815",
  "action": "Example petition action text",
  "state": "open",
  "signature_count": 82717,
  "next_threshold": {"name": "debate_consideration", "count": 100000},
  "signatures_per_hour": 200.0,
  "hours_since_previous_run": 6.0,
  "eta_hours_to_next_threshold": 86.4,
  "eta_next_threshold_at": "2026-10-01T06:59:43+00:00",
  "velocity_basis": "delta_since_previous_run",
  "approaching_threshold": true,
  "crossed_response_threshold_since_previous_run": false,
  "crossed_debate_threshold_since_previous_run": false,
  "top_constituencies": [
    {"name": "Banbury", "mp": "Sean Woodcock MP", "ons_code": "E14001072", "signature_count": 299}
  ],
  "checked_at": "2026-09-27T18:40:00+00:00"
}

velocity_basis is one of no_previous_run_recorded (first time this petition is scored), delta_since_previous_run (a real rate was computed), previous_run_too_recent (elapsed time was zero or negative - clock skew guard), or stalled_or_declining (rate is zero or negative, so no ETA is given - a petition can plateau or, rarely, have its count corrected downward).

Pricing model

Pay-per-event: one petition-scored event is charged per petition row pushed to the dataset. Petitions in the listing pass that never make the signature floor or the scoring cap cost nothing; a petition ID that 404s (withdrawn/rejected, e.g. only reachable through watchPetitionIds) is reported in run stats and not charged.

Data source and licence

All data comes directly from petition.parliament.uk, the official UK Government and Parliament e-petitions site, via its own public JSON API (the .json suffix on every page - documented informally at petition.parliament.uk/help). No API key, no login, no rate-limit workaround. Data is Crown/Parliamentary copyright published under the Open Government Licence v3.

Known constraints

• First run has no velocity. signatures_per_hour and the ETA fields are only populated once a petition has been scored on a previous run (state carried in the Actor's key-value store). Schedule the Actor to run periodically (e.g. hourly or every few hours) for the ETA feature to do anything.
• ETA is a straight-line projection from the rate observed between the previous run and this one - it does not model campaigns, media spikes, or petitions closing. Treat it as "at the current rate", not a guarantee.
• Older-TLS-stack retries: this development machine's Python/TLS stack occasionally raises http.client.IncompleteRead against some UK government hosts; src/http.py catches it (and 429/5xx/connection resets) inside the same retry-with-backoff loop used by the other Actors in this project, so a transient blip does not fail the whole run.