google support, local osrm, numba

Author: soodoku

.github/workflows/python-publish.yml

@@ -2,8 +2,9 @@
 name: Publish to PyPI
 
 on:
-  release:
-    types: [published]
+  push:
+    tags:
+      - 'v*'
   workflow_dispatch:
     inputs:
       use_test_pypi:
@@ -47,6 +48,8 @@ jobs:
 
     steps:
     - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
 
     - name: Install uv
       uses: astral-sh/setup-uv@v7

.gitignore

@@ -148,6 +148,7 @@ Thumbs.db
 
 # Project specific
 /allocator/kahip/
+allocator/_version.py
 *.csv
 *.png
 *.svg
@@ -159,4 +160,4 @@ Thumbs.db
 *-output.csv
 *-output.png
 *-output.html
-*-output.json
+*-output.jsonscripts/osrm/data/

CHANGELOG.md

@@ -2,6 +2,37 @@
 
 All notable changes to the allocator project are documented in this file.
 
+## [1.3.0] - 2025-04-22
+
+### Added
+
+**Google Routes API Support:**
+- New `google_routes_distance_matrix()` function using official `google-maps-routing` library
+- Service account authentication with proper rate limiting handled by Google's client
+- Support for multiple travel modes: DRIVE, BICYCLE, WALK, TWO_WHEELER, TRANSIT
+- Returns duration (seconds) or distance (meters)
+
+**Progress Reporting:**
+- Added `on_progress` callback to all distance matrix functions
+- Callback signature: `(current: int, total: int, message: str | None) -> None`
+- Useful for progress bars in long-running API requests
+
+**Local OSRM Server:**
+- Added `scripts/osrm/` with Docker setup for running local OSRM
+- `setup.sh` script to download and preprocess OSM data for any region
+- `docker-compose.yml` for easy server management
+
+### Changed
+
+- Legacy `method="google"` now emits `DeprecationWarning` recommending `google_routes`
+- Added `google-maps-routing>=0.6.0` to dependencies
+
+### Dependencies
+
+- Added: `google-maps-routing>=0.6.0` (official Google Routes API client)
+
+---
+
 ## [1.2.0] - 2025-04-12
 
 ### Changed

README.md

@@ -13,6 +13,7 @@ Field teams, delivery services, and survey organizations waste time and money on
 - **Route**: Find the shortest path through locations (TSP)
 - **Assign**: Match locations to nearest workers or depots
 - **Random Walk**: Generate survey itineraries on road networks
+- **Distance Matrix**: Calculate travel times/distances via OSRM or Google Routes API
 
 ## Install
 
@@ -68,6 +69,31 @@ result = allocator.random_walk(G, n_walks=10, walk_length_m=5000)
 print(result.data)  # DataFrame with waypoints
 ```
 
+### Calculate distance matrix
+
+```python
+from allocator.distances import get_distance_matrix
+import numpy as np
+
+points = np.array([
+    [-122.4194, 37.7749],  # SF downtown
+    [-122.4089, 37.7855],  # North Beach
+])
+
+# Local calculation (fast, no API)
+dist = get_distance_matrix(points, method="haversine")
+
+# OSRM (free, real driving times)
+dist = get_distance_matrix(points, method="osrm")
+
+# Google Routes API (requires service account)
+dist = get_distance_matrix(
+    points,
+    method="google_routes",
+    credentials_file="/path/to/service-account.json"
+)
+```
+
 ## CLI
 
 ```bash

allocator/__init__.py

@@ -71,7 +71,10 @@
 )
 from .viz.plotting import plot_assignments, plot_clusters, plot_comparison, plot_route
 
-__version__ = "1.2.0"
+try:
+    from ._version import __version__
+except ImportError:
+    __version__ = "dev"
 
 __all__ = [
     # Result types

allocator/core/itinerary.py

@@ -11,9 +11,22 @@
 """
 
 import numpy as np
+from numba import njit
 from ortools.constraint_solver import pywrapcp, routing_enums_pb2
 
 
+@njit(cache=True)
+def _compute_route_distance_jit(route: np.ndarray, distance_matrix: np.ndarray) -> float:
+    """JIT-compiled route distance computation."""
+    n = len(route)
+    if n <= 1:
+        return 0.0
+    total = 0.0
+    for i in range(n - 1):
+        total += distance_matrix[route[i], route[i + 1]]
+    return total
+
+
 def _ensure_rng(rng: np.random.Generator | None) -> np.random.Generator:
     """Return rng if provided, otherwise create a new default RNG."""
     return rng if rng is not None else np.random.default_rng()
@@ -145,10 +158,8 @@ def compute_route_distance(route: list[int], distance_matrix: np.ndarray) -> flo
     """
     if len(route) <= 1:
         return 0.0
-    total = 0.0
-    for i in range(len(route) - 1):
-        total += distance_matrix[route[i], route[i + 1]]
-    return total
+    route_arr = np.asarray(route, dtype=np.int64)
+    return float(_compute_route_distance_jit(route_arr, distance_matrix))
 
 
 def tsp_optimize_route(

allocator/distances/__init__.py

@@ -1,14 +1,19 @@
 """Distance matrix calculations."""
 
 from .euclidean import euclidean_distance_matrix, latlon2xy, pairwise_distances, xy2latlog
-from .external_apis import google_distance_matrix, osrm_distance_matrix
+from .external_apis import (
+    google_distance_matrix,
+    google_routes_distance_matrix,
+    osrm_distance_matrix,
+)
 from .factory import get_distance_matrix
 from .haversine import haversine_distance_matrix
 
 __all__ = [
     "euclidean_distance_matrix",
     "get_distance_matrix",
     "google_distance_matrix",
+    "google_routes_distance_matrix",
     "haversine_distance_matrix",
     "latlon2xy",
     "osrm_distance_matrix",