Methodology
How FuelClock.nz calculates New Zealand's fuel security position in real time.
Architecture
FuelClock.nz is a stateless, no-database application built with Next.js 16 (App Router, TypeScript, Tailwind CSS). Every API request recalculates the current state from a fixed MBIE anchor point — the same approach used by nzoilwatch.com. The site is deployed on Vercel (Sydney region) and all external data is fetched server-side via Route Handlers with in-memory caching.
Client-side components use SWR for data fetching with configurable refresh intervals. Charts are rendered with Recharts. No user data is collected or stored.
The Depletion Engine
The core fuel security calculation runs on every request to /api/fuel-data. It produces depletion estimates for three fuel types: Petrol, Diesel, and Jet Fuel.
Core Formula
1. MBIE Anchor
The starting point is MBIE's published in-country petroleum stockholding data. The current anchor is from 18 March 2026and gives opening stock levels in megalitres per fuel type. These are converted to "days of supply" by dividing by the daily consumption rate. When MBIE publishes new data (typically weekly, Mon/Wed afternoons), the anchor is updated — either automatically via the MBIE scraper or manually as a fallback.
2. Weighted Elapsed Days
Hours elapsed since the anchor date are accumulated with day-of-week consumption weighting. This accounts for real-world demand patterns where weekday fuel consumption exceeds weekends. The calculation iterates hour-by-hour from the anchor timestamp to the current time.
3. Arrived Vessel Days
Confirmed vessels that have arrived at NZ ports since the anchor date add supply back into the model. Only vessels with status confirmed and a recorded arrival date after the anchor date contribute. This prevents the countdown from being monotonically decreasing.
4. On-Land vs On-Water Separation
The engine separates on-land reserves(what's actually in NZ) from on-water supply(confirmed vessels still at sea). MBIE counts all vessels (confirmed + likely + scheduled) in their "total" figure, which inflates the apparent security position. FuelClock only counts confirmed vessels in its total, and the MBIE Comparison panel exposes the difference.
5. Risk Classification
The overall risk level is derived from the lowest fuel type's days of supply compared to its MSO threshold. Levels: low (well above MSO), moderate, elevated, high, critical (below MSO).
Consumption Rates & MSO Thresholds
Daily consumption rates are from MBIE energy statistics. Minimum Stock Obligation (MSO) thresholds are set by the Petroleum Stocks regulations.
| Fuel Type | Daily Rate | MSO Threshold | Current Anchor Stock |
|---|---|---|---|
| Petrol | 8.1 ML/day | 28 days | 221.9 ML (27.4d) |
| Diesel | 10.7 ML/day | 21 days | 224.7 ML (21.0d) |
| Jet Fuel | 4.8 ML/day | 24 days | 102.7 ML (21.4d) |
Dashboard Sections
Fuel Reserves Countdown
A live countdown timer driven by the lowest fuel type's on-land days of supply. Updates every second, subtracting elapsed time since the last API fetch.
NZ Government Debt
A pure client-side debt counter that replicates the calculation from DebtClock.nz. Uses the same constants (starting debt $272.085B at 30 Jun 2025, +$690.73/sec) extracted from their site's JavaScript. No API call required — runs entirely in the browser at 100ms intervals.
Fuel Gauges
Visual gauge cards for each fuel type showing on-land days of supply as a percentage of MSO. The most critical fuel type gets a full-width highlighted card with an alert banner. Gauges update every 60 seconds via the depletion engine.
MBIE Comparison
Side-by-side table showing MBIE's claimed total reserves versus FuelClock's more conservative figure. MBIE includes all vessels (confirmed + likely + scheduled) in their totals; FuelClock only counts confirmed vessels. The "inflation" column shows the difference.
Daily Consumption
Live burn rate counters that show how much fuel NZ is consuming in real time. Animated progress bars depict today's consumption against daily budgets, adjusting for day-of-week weighting.
Oil & FX
Live pricing for Brent Crude, WTI Crude, Dubai Crude (Oman Crude Futures), and NZD/USD exchange rate. Sourced from Yahoo Finance with 30-minute cache. Shows price, daily change, and percentage movement. Dubai Crude is particularly relevant as it's the benchmark for Asian-Pacific refined product pricing; WTI is the global benchmark for light sweet crude.
Fuel Prices
NZ retail fuel prices scraped from Gaspy.nz Firebase API. Shows current average prices for 91 Octane, 95 Octane, Diesel, and EV charging with 7-day and 28-day price changes. Cached for 15 minutes.
Supply Projections
Recharts line chart showing historical reserve depletion from January 2026 to today, plus four projection curves: No Intervention (baseline), Voluntary Conservation (10% reduction), Government Rationing (25%), and Emergency Lockdown (40%). An MSO threshold reference line shows when reserves would drop below the legal minimum. Switchable between Diesel, Petrol, and Jet Fuel.
Geopolitical Risk — Polymarket
Live prediction market probabilities from Polymarket via the Gamma API (server-side proxy to avoid CORS). Six markets are tracked: US-Iran Ceasefire, Hormuz Traffic Normalisation, Average Ships Transiting Hormuz, Crude Oil >$90/bbl, Kharg Island Strike, and US Naval Escorts. Displayed with headline summary cards, cumulative probability bars, a donut ring gauge, a ship-transit bar chart, and related market links. Polled every 60 seconds; fallback values used when API is unavailable.
NZ Government Bonds
Tracks NGB.NZ (Smart S&P/NZX NZ Government Bond ETF) via the Yahoo Finance chart API. Displays a 3-month price history chart, current price with daily change, day range, 52-week range, volume, previous close, and 1-week/1-month/3-month performance. Includes NZ sovereign credit rating (Fitch AA+, Stable). Updated every 60 seconds.
Vessel Pipeline & Tracking
Interactive SVG map with GeoJSON country outlines (Natural Earth 110m) showing all NZ-bound fuel tankers. Vessel data is sourced from official NZ port schedules: Northport Channel Infrastructure (Marsden Point — NZ's main fuel import terminal) and Port of Tauranga shipping schedules. These two ports handle virtually all of NZ's fuel imports. Vessels are filtered for petroleum/fuel cargo types including refined products, petroleum imports, and bitumen. The map supports zoom (scroll/pinch) and pan (drag). Vessel positions are estimated by linear interpolation between origin port and NZ destination based on scheduled arrival time. Below the map: fleet status breakdown (confirmed/likely/scheduled), normal vs current ship count, Hormuz transit exposure, next arrivals, per-fuel-type supply, and a full vessel list with risk flags. Cargo type is inferred from cargo descriptions and vessel name; volume is estimated from known vessel class sizes (MR tanker ~45ML, LR1 ~55ML, coastal ~18ML).
Scenario Projections
Four disruption scenario cards showing estimated days to depletion per fuel type under different conditions: Business as Usual (0.30× multiplier), Prolonged Disruption (0.85×), Full Crisis (1.00×), and SK Export Ban (1.48×). Also lists government response measures with estimated days of supply saved (speed limits, rationing, essential travel only, flight reductions, strategic reserve release).
AI Risk Assessment
A comprehensive risk analysis generated by Claude (claude-sonnet-4-20250514) that synthesises all dashboard data into a headline, detailed analysis, fiscal note, watch items, buying advice, and tips. Generated server-side with a 60-minute cache. Fallback assessment used when the API is unavailable.
News & Media Releases
NZ fuel-related news from Google News RSS (10-minute cache) and NZTU media releases scraped from the Taxpayers' Union news page (NationBuilder CMS, 30-minute cache).
Data Sources & Refresh Rates
| Source | Cache TTL | Implementation |
|---|---|---|
| MBIE petroleum stocks | 4 hr | Scraper fetches MBIE fuel stocks page; fallback to hardcoded anchor from 18 Mar 2026 |
| Gaspy fuel prices | 15 min | Firebase Realtime Database API (gaspy-4e3e3.firebaseio.com) |
| DebtClock.nz | N/A | Pure client-side — constants extracted from debtclock.nz JavaScript, no API call |
| Polymarket | 60 sec | Server-side proxy to Gamma API (gamma-api.polymarket.com), 6 market slugs |
| NZ Government Bonds | 1 min | Yahoo Finance chart API — NGB.NZ (Smart S&P/NZX NZ Government Bond ETF), 3-month daily OHLCV |
| Brent, WTI & Dubai Crude | 30 min | Yahoo Finance API (BZ=F Brent, CL=F WTI, QM=F Dubai Crude / Oman futures) |
| NZD/USD exchange rate | 30 min | Yahoo Finance API (NZDUSD=X) |
| NZTU news | 30 min | HTML scrape from taxpayers.org.nz/news (NationBuilder CMS) |
| Vessel tracking | 15 min | NZ port schedule scraping — Northport Channel Infrastructure (Marsden Point) + Port of Tauranga shipping schedules |
| AI risk assessment | 60 min | Anthropic Claude claude-sonnet-4-20250514 via server-side API call |
| Google News | 10 min | RSS feed: news.google.com/rss/search for NZ fuel-related terms |
Supply Projections Model
The supply projections chart shows four scenarios representing different demand reduction levels. Each scenario applies a percentage reduction to the daily consumption rate and projects days of supply remaining into the future.
| Scenario | Demand Reduction | Description |
|---|---|---|
| No Intervention (Baseline) | 0% | Current consumption continues unchanged |
| Voluntary Conservation | 10% | Public asked to reduce non-essential driving |
| Government Rationing | 25% | Mandatory odd/even plate rationing, speed limits |
| Emergency Lockdown | 40% | Essential travel only, flight reductions, strategic reserves |
Disruption Scenario Model
The Scenario Projections section models how geopolitical disruptions would increase effective consumption (panic buying, hoarding, supply chain friction). The multiplier is applied to the base consumption rate.
| Scenario | Multiplier | Description |
|---|---|---|
| Business as Usual | 0.30× | Normal supply chain with minor regional tensions |
| Prolonged Disruption | 0.85× | Extended Strait of Hormuz disruption, partial rerouting |
| Full Crisis | 1.00× | Complete Hormuz closure, all Middle East supply cut off |
| SK Export Ban | 1.48× | South Korea halts refined product exports — NZ loses primary refining source |
Staleness Indicators
Every data section shows a staleness badge indicating when the data was last fetched. Colour coding: green (<5 min), grey (<30 min), amber (<1 hr), red(>1 hr). If external sources fail, hardcoded fallback values are used and clearly labelled with an amber ⚠ warning banner.
Technical Stack
Disclaimer
FuelClock.nz provides indicative estimates only. Stock levels are calculated from published MBIE anchors and should not be treated as exact measurements. Vessel positions are sourced from live AIS data (aisstream.io); however, cargo type and volume are estimated from vessel dimensions and NZ import proportions — they are not confirmed manifest data. Prediction market probabilities are derived from Polymarket and reflect market sentiment, not forecasts.
This dashboard is for informational purposes and should not be used for trading decisions. The NZ Taxpayers' Union takes no responsibility for decisions made based on this data.
Built by RB Alliance Limited for the NZ Taxpayers' Union