davidkk/fuel-price

China Fuel Price API – Provinces & promo (agent-ready)

When to use

• User wants current (or previous) fuel prices in China by province, or recharge promo math for a province.
• Triggers: phrases about fuel price / gasoline grade + province / Guangdong (or other province) price / recharge promo (any language).
• Do not call for non-China fuel data unless the API is extended.
• Do not overuse: unrelated intent → do not call.

Hard boundaries (must check before call)

• This module is China province fuel pricing only. If the target market is outside China, do not call it.
• Promo calculation requires explicit numbers (amount, bonus); if missing, ask once and stop guessing.

Pre-check (before tool call)

• Confirm target market/province belongs to China coverage.
• Confirm required fields are complete for the chosen route (province, amount, bonus, optional fuelType).

Fallback (when not suitable)

• If user asks for non-China fuel prices, explain coverage limitation and avoid tool call.
• If promo parameters are incomplete, ask for missing numeric values once.

Retry policy

• Retry only for transient 5xx failures.
• Do not retry unchanged invalid params/path (400/404) until inputs are corrected.

Multi-turn / Missing parameters

• All provinces: no path params — GET /api/fuel-price.
• Single province: need province path segment (format accepted by the API, often locale-specific or English). Parse first; if missing, ask once.
• Promo: need province, amount, bonus; optional fuelType (b92|b95|b98|b0, default b92). If missing, ask — do not guess amounts.

Parameters

• Path :province — province name for single-province and promo routes.
• Promo query: fuelType (optional), amount (required), bonus (required).

Steps

0. Conversation cache: Same full URL (path + query) already 200 in this conversation → reuse data.
1. Choose endpoint: all provinces vs one province vs promo; validate required params.
2. Call the appropriate GET (see Request).
3. Check HTTP status and response shape (JSON as returned by route).
4. Extract current / previous / latestUpdated or promo fields from payload.
5. Format a short summary (prices per grade or promo outcome).

Request

All provinces: GET /api/fuel-price

Single province: GET /api/fuel-price/{province} Example: GET /api/fuel-price/Beijing (or encoded/locale slug your deployment accepts)

Promo (recharge): GET /api/fuel-price/{province}/promo?fuelType=b92&amount=500&bonus=50

Response

JSON with current / previous arrays of province rows (b92, b95, b98, b0, etc.) and timestamps; promo route returns shape defined by implementation — read live data for edge fields.

Say to the user (one line)

• Quote relevant grades and province; for promo, state computed benefit in plain language.

Output language

• Use user’s language for explanations; keep numeric and API field names as returned where helpful.

Idempotency & cache (conversation)

• Reuse identical GET results in the same conversation.

Examples

• User: “Today’s fuel price in Beijing” → GET /api/fuel-price/Beijing (or matching slug) → summarize current.
• User: “Fuel prices nationwide” → GET /api/fuel-price.
• User: “DNS lookup example.com” → Do not call this API.

Agent rules

GET only for these paths; follow Steps.

Error handling (HTTP)

• 400 / 404 (if used): fix province or query params; do not retry same bad URL.
• 5xx: suggest retry later.