fuelclock-nz
Query NZ fuel prices, supply, inbound tankers, MSO status, geopolitical shipping risk markets, and NZ fuel headlines from fuelclock.nz. No authentication required.
SKILL.mdskills/fuelclock-nz/SKILL.md
GitHubFuelClock NZ
Goal
Query live New Zealand fuel price and supply data from fuelclock.nz through a CLI that is easy for agents to script and easy for humans to scan. Includes geopolitical shipping risk markets and recent NZ fuel headlines.
Use this when
- A user asks about current NZ petrol, diesel, or premium fuel prices
- A user wants to know whether NZ fuel supply is tight or below MSO thresholds
- A user asks what tankers are en route to New Zealand
- A user wants a quick fuel situation summary focused on prices, supply, and vessels
- A user asks about geopolitical shipping risk markets relevant to NZ fuel supply
- A user wants recent NZ fuel headlines
Do not use this for
- Fuel prices outside New Zealand
- Electricity, gas, or LPG pricing
- Vehicle fuel efficiency calculations
- Forecasting future fuel prices beyond the live observed data
Preferred workflow
- Run
scripts/cli.pywith the narrowest subcommand that answers the task - Use
summaryfor a quick situational briefing across prices, supply, and vessels - Use
watchfor a quick briefing across geopolitical risk markets and recent headlines - Use default human output for direct answers
- Use
--jsonwhen another tool or agent needs machine-readable output
CLI
Run with:
python3 skills/fuelclock-nz/scripts/cli.py <command> [flags]
summary [--json]
Best default for general fuel questions. Combines prices, supply, and inbound vessels.
JSON shape:
prices: fetched price snapshot plus filtered price rowssupply: overall risk, countdown, lowest fuel, below-MSO list, and fuel rowsvessels: fetched time, inbound vessel count, flagged count, and top vessels
Examples:
python3 skills/fuelclock-nz/scripts/cli.py summary
python3 skills/fuelclock-nz/scripts/cli.py summary --json
watch [--json]
Quick briefing combining top geopolitical risk markets and recent NZ fuel headlines.
JSON shape:
risk.fetchedAt,risk.totalMarkets,risk.markets[]news.fetchedAt,news.totalArticles,news.articles[]
Examples:
python3 skills/fuelclock-nz/scripts/cli.py watch
python3 skills/fuelclock-nz/scripts/cli.py watch --json
prices [--fuel 91|95|98|diesel] [--json]
Shows national average NZ pump prices from FuelClock's Gaspy-backed endpoint.
JSON shape:
fetchedAtsourceisFallbackfilters.fuelcountprices[]withfuel,label,price,change7d,change28d,changePercent28d,direction7d,direction28d,min,max,stationCount
Examples:
python3 skills/fuelclock-nz/scripts/cli.py prices
python3 skills/fuelclock-nz/scripts/cli.py prices --fuel diesel
python3 skills/fuelclock-nz/scripts/cli.py prices --fuel 95 --json
supply [--fuel petrol|diesel|jet] [--below-mso] [--json]
Shows NZ fuel supply state, including days remaining, MSO gap, and depletion timing.
JSON shape:
timestampanchorDatembieAsAtDateoverallRiskcountdownHourslowestFuelfilters.fuelfilters.belowMSOcountfuels[]withfuel,label,currentDays,totalDays,onLandDays,onWaterDays,msoThreshold,gapToMSODays,belowMSO,calendarDaysToDepletion,dailyConsumptionML,currentStockML,remainingOnWaterDays,remainingOnWaterML,mbieInCountryDays
Examples:
python3 skills/fuelclock-nz/scripts/cli.py supply
python3 skills/fuelclock-nz/scripts/cli.py supply --below-mso
python3 skills/fuelclock-nz/scripts/cli.py supply --fuel diesel --json
vessels [--fuel petrol|diesel|jet] [--flagged-only] [--limit N] [--json]
Shows inbound vessel data, sorted by ETA.
JSON shape:
fetchedAtsourcegovOnWaterByFuelfilters.fuelfilters.flaggedOnlyfilters.limittotalMatchingreturnedCountvessels[]withname,fuel,status,eta,arrived,cargoML,cargoDays,origin,progressPct,flagRisk,flagReason,hormuzTransit
Examples:
python3 skills/fuelclock-nz/scripts/cli.py vessels
python3 skills/fuelclock-nz/scripts/cli.py vessels --flagged-only --limit 3
python3 skills/fuelclock-nz/scripts/cli.py vessels --fuel diesel --json
risk [--limit N] [--json]
Shows tracked geopolitical markets relevant to fuel shipping (Polymarket-style), sorted by trading volume.
JSON shape:
fetchedAtsortfilters.limittotalMarketsreturnedCountmarkets[]withtitle,shortTitle,probability,volume,liquidity,lastUpdated,isFallback,subMarkets[]
Examples:
python3 skills/fuelclock-nz/scripts/cli.py risk
python3 skills/fuelclock-nz/scripts/cli.py risk --limit 5
python3 skills/fuelclock-nz/scripts/cli.py risk --limit 3 --json
news [--limit N] [--json]
Shows recent NZ fuel headlines, newest first.
JSON shape:
fetchedAtfilters.limittotalArticlesreturnedCountarticles[]withtitle,source,date,url
Examples:
python3 skills/fuelclock-nz/scripts/cli.py news
python3 skills/fuelclock-nz/scripts/cli.py news --limit 3
python3 skills/fuelclock-nz/scripts/cli.py news --limit 5 --json
Resources
- CLI entrypoint:
scripts/cli.py - Live smoke test:
scripts/smoke_test.py
Notes
- No API key required
- Pure Python 3 standard library (
urllib); no third-party dependencies - Default output is human-readable and filtered for quick answers
--jsonoutput is intended for chaining into other tools or agent steps- FuelClock supply data and MBIE stock data are related but not identical, FuelClock applies its own live supply model on top of source data
- Geopolitical risk probabilities are market yes-prices from Polymarket-style data, not direct NZ fuel risk scores
Source notes
Read references/source-notes.md for source ownership, access, and freshness boundaries.