Technical Overview

PathPay intentionally keeps a compact architecture: one primary CLI file plus a map-enabled variant. This section highlights the main components and data flow.

High-level architecture

  1. CSV ingestion – load_and_prepare concatenates every file passed via --csv/--csv_dir and filters rows to Gwangjin/Songpa.

  2. Geocoding – ensure_geocodes keeps existing lat/lon values and calls Kakao Local for the missing ones.

  3. Candidate preselection – preselect_candidates keeps stations that lie within ~1 km of the straight-line path and sorts by price and proximity.

  4. Cost evaluation – evaluate_total_cost compares the baseline route against the detour using Kakao Mobility Directions to compute distance/time deltas and monetary impact.

  5. Presentation – Results are sorted by effective price and printed, and a Kakao Map deeplink is generated for the best choice. The map variant can also produce Folium HTML visualizations.

Key modules

fuel_route_recommender.py

  • Parses CLI arguments and orchestrates the run.

  • Loads and filters CSVs for Gwangjin/Songpa.

  • Geocodes stations if latitude/longitude is missing.

  • Calls Kakao Mobility for baseline and detour routes.

  • Calculates total cost, effective price, and prints the top 3 results.

fuel_route_recommender_with_map.py

  • Extends the base logic with --save_map to render Folium maps.

  • Adds markers for origin, destination, and top 3 stations and draws simple polylines (straight lines, not polyline traces from Directions).

Technologies

  • Python Standard Library – Argument parsing, math utilities, filesystem access, rate limiting via time.sleep.

  • Pandas – Concatenating and cleaning CSVs, numeric conversion, and sorting candidates.

  • Requests – HTTP calls to Kakao Local and Mobility REST APIs.

  • Folium (optional) – Static HTML map generation.

API integrations

  • Kakao Local Search – /v2/local/search/address.json service used to convert textual addresses into WGS84 coordinates.

  • Kakao Mobility Directions – /v1/directions endpoint used twice per station: once for the baseline route (origin → destination) and once for the detour (origin → station → destination).

  • Kakao Map Deeplink – Simple https://map.kakao.com/link/to/... URLs so users can open the recommended stopover directly in the Kakao Map app.

Extensibility hooks

  • Broader geography – Modify load_and_prepare to adjust the 지역 filter and optionally bring in additional CSV columns.

  • Alternative routing – Swap out Kakao Mobility with another routing provider by implementing equivalents of route_distance_time and route_via_distance_time.

  • Web UI – Expose the same calculations via FastAPI or Django if you need a hosted experience. The CLI’s calculation routines are reusable from other entry points.