A robust and feature-rich routing engine built on top of OSMnx for OpenStreetMap data processing and route calculation. This project provides a simple yet powerful interface for finding optimal routes between geographical points with comprehensive visualization capabilities.

• Flexible Data Sources: Support for both place names (automatic download) and OSM XML files
• Robust Error Handling: Comprehensive validation and error handling for edge cases
• Multiple Visualization Options: Static maps, interactive HTML maps, and route statistics
• Coordinate Validation: Built-in validation for geographical coordinates
• Distance Calculations: Accurate distance calculations using haversine formula
• Graph Projection: Automatic handling of coordinate reference systems
• Comprehensive Testing: Full test suite with unit and integration tests

For full documentation, visit https://mouhamedtec.github.io/SPL-Router

• Python 3.7+
• OSMnx >= 1.3.0
• NetworkX >= 2.8.0
• Pandas >= 1.5.0
• Requests >= 2.32.3

• Matplotlib >= 3.5.0
• Folium >= 0.12.0
• NumPy >= 1.21.0

• Pytest >= 7.0.0
• Pytest-cov >= 4.0.0
• Pytest-mock >= 3.8.0

git clone https://github.com/Mouhamedtec/SPL-Router.git
SPL-Router

pip install osmnx networkx pandas matplotlib folium numpy

pip install -r requirements.txt

pip install -r requirements_test.txt

from router import SPLRouterEngine

# Initialize with a place name (downloads data automatically)
router = SPLRouterEngine(place_name="San Francisco, California")

# Define start and end points
start_point = (-122.4194, 37.7749)  # Union Square
end_point = (-122.4313, 37.8051)    # Fisherman's Wharf

# Find the shortest path
path_coords, distance = router.shortest_path(start_point, end_point)

print(f"Route found! Distance: {distance:.2f} meters")
print(f"Path has {len(path_coords)} coordinate points")

# Initialize with an OSM XML file
router = SPLRouterEngine(osm_xml_file="path/to/your/data.osm")

# Create a static map
router.visualize_route(start_point, end_point, save_path="route.png")

# Create an interactive HTML map
router.visualize_route_interactive(start_point, end_point)
# Opens route_visualization.html in your browser

# Create detailed route analysis
router.plot_route_stats(start_point, end_point)

from router import SPLRouterEngine

def main():
    # Initialize router
    router = SPLRouterEngine(place_name="San Francisco, California")
    
    # Print graph information
    print("Graph info:", router.get_graph_info())
    
    # Define route points
    start_point = (-122.4194, 37.7749)  # Union Square
    end_point = (-122.4313, 37.8051)    # Fisherman's Wharf
    
    # Calculate route
    path_coords, distance = router.shortest_path(start_point, end_point)
    
    print(f"Route distance: {distance:.2f} meters")
    
    # Create visualizations
    router.visualize_route(start_point, end_point, save_path="route_static.png")
    router.visualize_route_interactive(start_point, end_point)
    router.plot_route_stats(start_point, end_point)

if __name__ == "__main__":
    main()

# Using default Nominatim server
address = router.reverse_geocode_nominatim(-122.4194, 37.7749)
print(f"Address: {address}")

# Using custom server
custom_server = "https://your-nominatim-server.com"
address = router.reverse_geocode_nominatim(-122.4194, 37.7749, server_url=custom_server)

# Get data from multiple services
results = router.reverse_geocode_multiple(-122.4194, 37.7749)
print(f"Nominatim: {results['nominatim']}")
print(f"Photon: {results['photon']}")

Get address information using Nominatim.

• lon: Longitude coordinate
• lat: Latitude coordinate
• server_url: Optional custom Nominatim server URL
• Returns: Dictionary containing address information

Get address information using Photon.

• lon: Longitude coordinate
• lat: Latitude coordinate
• server_url: Optional custom Photon server URL
• Returns: Dictionary containing address information

Get address information from multiple services.

• Returns: Combined results from all available services

python tests/test_router.py

pytest tests/test_router.py -v

pytest tests/test_router.py --cov=router_osmnx --cov-report=html

The test suite includes:

• Unit tests for all methods
• Integration tests for real-world scenarios
• Edge case testing
• Error handling validation
• Mock testing for external dependencies

SPLRouterEngine(osm_xml_file=None, place_name=None)

• osm_xml_file: Path to OSM XML file (optional)
• place_name: Name of place to download (optional)

Find the shortest path between two coordinates.

• start_point: Tuple of (longitude, latitude)
• end_point: Tuple of (longitude, latitude)
• Returns: Tuple of (path_coordinates, distance_in_meters)

Create a static visualization of the route.

• save_path: Optional path to save the image

Create an interactive HTML map.

• Saves route_visualization.html in the current directory

Create detailed route statistics and analysis.

Get information about the loaded graph.

• Returns: Dictionary with graph statistics

Validate coordinate values.

• Returns: Boolean indicating if coordinates are valid

Calculate haversine distance between two points.

• Returns: Distance in meters

The engine automatically configures OSMnx settings for optimal performance:

• Adds 'oneway' to useful tags
• Configures network type for driving
• Handles coordinate reference systems

The engine includes comprehensive error handling for:

• Invalid coordinates
• Missing files
• Network errors
• Empty graphs
• Projection issues

1. Internet Connection: Place-based initialization requires internet access.
2. Memory Usage: Large areas may require significant memory.
3. Coordinate System: Automatic projection may not work for all areas.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

# Clone the repository
git clone https://github.com/Mouhamedtec/SPL-Router.git
SPL-Router

# Install development dependencies
pip install -r requirements_test.txt

# Run tests
python tests/test_router.py

This project is licensed under the MIT License - see the LICENSE file for details.

• OSMnx - The underlying library for OSM data processing
• NetworkX - Graph algorithms and data structures
• OpenStreetMap - The data source
• Folium - Interactive map visualization

If you encounter any issues or have questions:

1. Create a new issue with detailed information
2. Include error messages and system information

Note: This routing engine is designed for educational and research purposes. For production use, consider additional optimizations and error handling based on your specific requirements.