Freight Lane Visualization Tool - A public-facing Streamlit application for geocoding and visualizing freight lane networks using yat_geo_db and Kepler.gl.
LaneViz allows users to upload CSV files containing freight lane data, automatically geocode all origins and destinations, and visualize the Origin/Destination (O/D) network on an interactive Kepler.gl map.
- CSV Upload: Easy drag-and-drop interface for uploading freight lane data
- Automatic Validation: Ensures all required columns are present
- Geocoding: Converts city/state/ZIP to latitude/longitude using yat_geo_db
- Data Processing: Automatic cleaning, deduplication, and aggregation
- Interactive Visualization: Beautiful network maps powered by Kepler.gl
- Summary Statistics: View key metrics about your freight network
Your CSV file must contain the following columns:
| Column Name | Type | Description |
|---|---|---|
lane_id |
String | Unique identifier for the lane |
origin_city |
String | Origin city name |
origin_state |
String | Origin state (2-letter code) |
origin_zip |
String | Origin ZIP code |
destination_city |
String | Destination city name |
destination_state |
String | Destination state (2-letter code) |
destination_zip |
String | Destination ZIP code |
miles |
Numeric | Distance in miles |
equipment_type |
String | Type of equipment (e.g., van, reefer) |
volume |
Numeric | Freight volume |
lane_id,origin_city,origin_state,origin_zip,destination_city,destination_state,destination_zip,miles,equipment_type,volume
L001,Chicago,IL,60601,Atlanta,GA,30301,715,Van,1500
L002,Los Angeles,CA,90001,Seattle,WA,98101,1135,Reefer,2300
L003,Dallas,TX,75201,Miami,FL,33101,1300,Flatbed,800- Python 3.8 or higher
- pip package manager
- Virtual environment (recommended)
- Clone the repository
git clone https://github.com/yourusername/LaneViz.git
cd LaneViz- Create and activate a virtual environment
# On macOS/Linux
python -m venv venv
source venv/bin/activate
# On Windows
python -m venv venv
venv\Scripts\activate- Install dependencies
pip install -r requirements.txt- Configure secrets (optional)
If you need to configure database credentials or API keys:
mkdir .streamlit
cp config/secrets.template .streamlit/secrets.toml
# Edit .streamlit/secrets.toml with your actual credentialsstreamlit run app/main.pyThe application will open in your default browser at http://localhost:8501
LaneViz can be deployed to various platforms:
- Streamlit Cloud: Push to GitHub and deploy via streamlit.io/cloud
- Heroku: Use the included
Procfile(to be added) - Docker: Use the included
Dockerfile(to be added)
LaneViz/
├── app/
│ ├── __init__.py
│ └── main.py # Main Streamlit application
├── utils/
│ ├── __init__.py
│ ├── geocode.py # Geocoding utilities (yat_geo_db)
│ ├── transform.py # Data cleaning and transformation
│ └── map_builder.py # Kepler.gl map configuration
├── data/ # Temporary uploaded files (git-ignored)
├── config/
│ └── secrets.template # Template for secrets configuration
├── .gitignore
├── requirements.txt
├── LICENSE
└── README.md
┌─────────────────┐
│ User uploads │
│ CSV file │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Validation │
│ (transform.py) │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Geocoding │
│ (geocode.py) │
│ yat_geo_db │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Data Prep │
│ (transform.py) │
│ Aggregation │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Visualization │
│ (map_builder.py)│
│ Kepler.gl │
└─────────────────┘
- Click the "Browse files" button
- Select your CSV file containing freight lane data
- The app will automatically validate the file structure
- Review the data summary statistics
- Click "Geocode All Locations"
- Wait for the geocoding process to complete
- Review the success rate and any failed locations
- Configure map options (aggregation, filters, etc.)
- Click "Generate Map"
- Explore your freight network on the interactive map
- Use tooltips to see lane details
This is the initial boilerplate setup. The following features are currently placeholders:
⚠️ Geocoding: yat_geo_db integration is stubbed out⚠️ Map Rendering: Kepler.gl integration needs Streamlit component⚠️ Export: HTML/PDF export functionality
- Implement actual yat_geo_db geocoding in
utils/geocode.py - Add Streamlit-Kepler.gl integration for map rendering
- Create sample CSV download functionality
- Add data export features (CSV, HTML map export)
- Implement caching for improved performance
- Add filters for equipment type, volume thresholds
- Create unit tests for all utility modules
- Add comprehensive error handling
- Implement logging throughout the application
- Add map customization options (colors, styles, etc.)
- Create user documentation and tooltips
- Add support for batch processing multiple files
Contributions are welcome! Please follow these guidelines:
- Fork the repository
- Create a feature branch (
git checkout -b feature/YourFeature) - Commit your changes (
git commit -m 'Add YourFeature') - Push to the branch (
git push origin feature/YourFeature) - Open a Pull Request
- Follow PEP 8 guidelines
- Use type hints where appropriate
- Include docstrings for all functions and classes
- Keep functions modular and testable
- Add comments for complex logic
# Install test dependencies
pip install pytest pytest-cov
# Run tests
pytest tests/
# Run with coverage
pytest --cov=utils tests/Add tests to the tests/ directory (to be created):
tests/
├── test_geocode.py
├── test_transform.py
└── test_map_builder.py
Issue: CSV upload fails with encoding error
- Solution: Ensure your CSV is UTF-8 encoded
Issue: Geocoding returns no results
- Solution: Check that city/state/ZIP data is properly formatted
Issue: Map doesn't render
- Solution: Verify that keplergl is properly installed
This project is licensed under the MIT License - see the LICENSE file for details.
For questions, issues, or feature requests:
- Open an issue on GitHub
- Contact the development team
- Check the documentation
- Initial project setup
- Basic file upload and validation
- Geocoding module structure (placeholder)
- Map builder module structure (placeholder)
- Data transformation utilities
- Streamlit UI framework
Built with ❤️ using Streamlit, yat_geo_db, and Kepler.gl