pitstop#

pitstop answers Italian fuel-price questions from official MIMIT open data. It downloads and caches the national station registry + daily price file and joins them locally, so you get a small JSON answer instead of multi-megabyte CSVs.

When to use#

• "Cheapest diesel / petrol near in Italy"
• "Fuel stations in <comune/province>" and their prices
• Comparing self-service vs served prices, or brands, for Italian stations
• Finding EV chargers near a coordinate or municipality (OSM)

Do not use the fuel commands for: live/intraday prices (this is daily data) or countries other than Italy. For EV charging, use pitstop chargers / MCP find_chargers — separate domain backed by OpenStreetMap. Per-station €/kWh tariffs are never returned by pitstop chargers / MCP find_chargers (it parses OSM's fee yes/no flag and no price field); each charger result includes a tariff_info_url linking to the operator's official tariff page — surface that to the user instead of guessing a price.

Commands#

Always pass --json when consuming the output programmatically, or --geojson if you have mapping/GIS capabilities.

bash

# Multi-fuel query in a municipality (supports EN/FR/DE city names)
pitstop stations --comune Milan --fuel "Benzina,Gasolio" --cheapest --limit 5 --json

# Nearest stations to a coordinate, with navigation URLs
pitstop stations --near 46.498,11.354 --radius 5 --fuel Benzina --json

# Export to GeoJSON FeatureCollection
pitstop stations --comune ROME --fuel Gasolio --geojson

# Find EV chargers with error reporting
pitstop chargers --comune Venice --json

# Public CCS chargers rated at least 50 kW
pitstop chargers --comune Bozen --radius 5 --socket ccs --fast --public --json

Key flags:

• --comune: Municipality name. Supports international names ( Rome, Milan, Venice, Florence, Bozen, Mailand, Venise, etc.).
• --fuel: Substring search. Supports comma-separated lists (e.g. Benzina,Gasolio). With --cheapest and a comma list, each station ranks by its cheapest listed fuel.
• --geojson: Emits a standard GeoJSON FeatureCollection with properties and geometry.
• Other station flags: --provincia, --brand, --near, --radius, --self/ --served, --cheapest (needs --fuel), --min-price, --fresh-within-days, --max-deviation-pct, --drop-outliers, --no-comune-validate, --limit, --json, --refresh, --max-age, --timeout.
• Charger flags: --near, --comune, --provincia, --comune-id (discover with places; use when names duplicate), --radius, --operator, --socket, --min-power, --fast, --ultra-fast, --free (only explicit fee=no; unknown fee excluded), --public (only explicit public access; unknown excluded), --limit, --json/ --geojson, --refresh, --timeout, --max-age.
• Charger power uses --min-power in kW; --fast means at least 50 kW and --ultra-fast at least 150 kW. Inspect the matching socket's power as well as the station maximum.
• CLI↔MCP names differ: --min-power is min_power_kw, --radius is radius_km, --free/ --public are free_only/ public_only, --fresh-within-days is max_age_days, --comune-id is comune_id.

JSON / GeoJSON contract#

• stations --json returns a stable envelope with stations[], query, and a quality block (how many returned prices were screened against a local median). Each station includes a navigation_url (Google Maps).
• stations --geojson returns a FeatureCollection. Geometry is Point [lon, lat]. Properties include all station metadata.
• chargers output includes an error field in the envelope when the external Overpass API fails.
• Search coverage distinguishes fetched rows, matches before the limit, and returned rows. Read freshness for cache age; generated_at is response time, not source freshness. Surface stale-cache and partial-result errors.
• For chargers, use pitstop places <name> --json to discover municipality IDs. Resolve duplicate names with --provincia or use --comune-id. The returned location identifies the mapped OSM administrative center and any coordinate discrepancy; surface its warnings. If no center is available, request explicit coordinates.

Advice for Agents#

• Discover fuel names: Run pitstop fuels --json; ordinary diesel is Gasolio. Substring matches also include premium blends, so compare exact prices[].fuel values when a specific fuel is requested.
• Choose a useful stop: When ranking within a bounded area, inspect every match ( --limit 0) and break equal-price ties by distance. Distances are straight-line; a navigation link provides the next step for checking the driving route.
• Follow the tariff handoff: Open the official tariff_info_url when answering charging-cost questions. Check membership requirements, location, and payment method; a contract rate is not automatically the walk-up price. Report failed links rather than quoting an unverified tariff.
• Use International Names: You can pass "Rome" or "Milan" directly to --comune; the tool handles the translation to the Italian dataset keys.
• Batch Fuel Queries: To compare Petrol and Diesel, use --fuel "Benzina,Gasolio" in a single call.
• Surface Maps: Always include the navigation_url in your response so the user can navigate to the station immediately.
• Handle Outliers: Every price carries a median_basis. A screened price also carries regional_median and deviation_pct, plus outlier: true when it is >15% below the local median or below the Tukey lower fence Q1−1.5·IQR. The outlier key is present only when it is true, so read it as optional ( price.get("outlier"), not price["outlier"]). Use the flag to warn users about potential data errors in the open feed.
• Don't over-trust unscreened prices: an unscreened price sits in a (fuel, provincia) bucket with too few samples to compute a median, so no outlier check ran on it — it is returned exactly as reported. The envelope's quality block counts screened vs unscreened for the answer you actually got — don't assume a fixed share — so check it before calling a suspiciously cheap price a bargain.
• Check suspect coordinates: A coordinate_suspect: true flag appears when a station's coord is far from its declared comune's centroid. Treat these with low confidence.

Machine-readable versions of these command patterns, each with the caveats that must travel with the answer, are in evals/agent/recipes.json in the repo.