How to Use PathPay

This section demonstrates typical CLI workflows and expected outputs.

Basic invocation

python fuel_route_recommender.py \
  --csv_dir price_csv \
  --fuel 휘발유 \
  --liters 40 \
  --eff 12.5 \
  --alpha 600 \
  --origin "서울특별시 광진구 세종대길 1" \
  --dest "서울특별시 송파구 올림픽로 300"

Explanation of core parameters:

--csv_dir – Directory containing station CSVs (alternatively pass one or more --csv paths).
--fuel – Fuel type column to optimize (휘발유, 경유, 고급휘발유).
--liters – Planned fueling amount so total cost can be computed.
--eff – Vehicle efficiency in km/L (required).
--alpha – Value of time in KRW per minute (defaults to 600).
--origin / --dest – Text addresses that Kakao Local can geocode.

Sample output

=== 추천 Top 3 (유효단가 기준) ===
[1] OO주유소 (SK)  서울시 송파구 ...
  주유단가: 1479 ₩/L | 유효단가: 1505 ₩/L
  우회: +0.80 km, +1.2 분  (연료비 200₩, 시간비 720₩)
  총비용: 60200 ₩

=== 의사결정 ===
→ 경유 추천: OO주유소 로 들르면 총비용 1800₩ 절감(근사).
경유 안내(첫 단계): https://map.kakao.com/link/to/...

Interpretation tips

유효단가 (effective price) – The per-liter cost after factoring in detour time and fuel penalties. This is the primary ranking metric.
우회 metrics – Positive values indicate additional distance/time compared to driving directly from origin to destination. Large detours can negate cheap fuel prices.
Gain estimate – gain = avg_price * liters - best.total_cost. If the number is negative, skip the detour.

Optional map export

Use the companion script to render Folium HTML maps:

python fuel_route_recommender_with_map.py \
  --csv_dir price_csv \
  --eff 12.5 --liters 40 --fuel 휘발유 \
  --origin "..." --dest "..." \
  --save_map recommend_map.html

Open the generated HTML file in a browser to visualize start/end points and the top 3 stations along the route.