RouteSportLocation

A Python/Jupyter system for computing and visualizing traveling-salesman routes across USA baseball stadiums using direct-distance and car-route distance methods.

The default sample is for Baseball stadiums. It accepts:

• A stadium CSV with name, address, location, coordinates, and characteristics.
• A square stadium-to-stadium distance matrix where values are driving distances, not aerial distances.

It produces:

• output/tsp_route.csv: ordered route legs and driving distances.
• output/usa_tsp_route.html: interactive USA map showing the computed route order.
• output/tsp_route_graph.dot: Graphviz directed route graph. If the dot executable is installed, an SVG is rendered too.

Quick Start

python3 route_sport_location.py

The notebooks default to use_pandas_tables = "no" so they avoid importing pandas/numpy and are less sensitive to Anaconda binary compatibility issues. Install the lightweight dependencies with:

pip install -r requirements.txt

If you want notebook route tables rendered by pandas, set use_pandas_tables = "yes" in the notebook input cell and install the optional dependency:

pip install -r requirements-pandas.txt

Use a specific start stadium:

python3 route_sport_location.py --start YANKEE

Use custom inputs:

python3 route_sport_location.py \
  --sport Baseball \
  --stadiums data/baseball_stadiums.csv \
  --matrix data/baseball_driving_distances.csv \
  --start YANKEE \
  --output-dir output

Input Files

Stadiums CSV

Required columns:

id,sport,name,address,city,state,latitude,longitude,characteristics

Each id must be unique and must match the row and column identifiers in the distance matrix.

Driving Distance Matrix CSV

Required shape:

stadium_id,YANKEE,FENWAY,CITIZENS
YANKEE,0,219,111
FENWAY,219,0,330
CITIZENS,111,330,0

The matrix values should be road-route driving distance, typically from a routing source such as Google Maps Distance Matrix, Mapbox Directions, HERE, OSRM, or another routing engine. The sample matrix is a small demonstration dataset and should be replaced with authoritative routing distances for production use.

Solver Behavior

• Up to 12 stadiums: exact Held-Karp dynamic programming.
• More than 12 stadiums: nearest-neighbor route improved with 2-opt.
• The route returns to the starting stadium.

Notes

The map connects stadium coordinates in the TSP order and labels each leg with the driving-distance value from the matrix. If you also need exact road geometry on the map, add route polyline data from the same routing engine that produced the distance matrix.