What Is Iterinary and How Do You Actually Use It
Iterinary is a tool I ended up using after a few projects where I was manually stitching together schedule data and route calculations. It automates the creation of itineraries from raw inputs like times, locations, and constraints. The basic workflow is: feed it your stops, set your time windows, and it outputs a structured plan. You start by installing it. The repository is on GitHub under iterinary/iterinary, and it supports both npm and pip depending on which version you're pulling. Once installed, the CLI is the main interface, though there is a Python API if you prefer scripting. The core command looks like this: iterinary build --input schedule.json --output plan.json --optimize time
The first time I ran this, I expected it to just work out of the box. It doesn't. The input format matters a lot, and the documentation assumes you already know what a valid schedule object looks like. Here's what a minimal input looks like: {
"stops": [
{ "id": "A", "location": {"lat": 40.7128, "lng": -74.006}, "time_window": {"start": "09:00", "end": "09:30"}, "duration": 30 },
{ "id": "B", "location": {"lat": 34.0522, "lng": -118.2437}, "time_window": {"start": "14:00", "end": "15:00"}, "duration": 45 }
],
"travel_mode": "driving"
} One thing the docs don't emphasize enough: the time windows are hard constraints. If the optimizer can't fit a stop within its window given travel time between nodes, it drops that stop silently. I spent about three hours debugging a plan that was missing a stop, only to realize the travel time between two points exceeded the gap between the two time windows. The workaround was to add a small buffer parameter: --buffer-minutes 15. That flag is not in the README but exists in the code. It's worth adding to every run.
How Iterinary Actually Performs
The optimizer uses a combination of constraint programming and a nearest-neighbor heuristic for initial solution generation. For small inputs under 20 stops, it finishes in under 30 seconds on a standard laptop. Beyond that, runtime grows non-linearly because the search space expands combinatorially. At 50 stops, I've seen it take 4 to 6 minutes, sometimes timing out depending on how tight your constraints are. A counter-intuitive thing I learned the hard way: adding more constraints does not always produce a better result. When I added a constraint that every stop must be visited within exactly a 10-minute window, the optimizer either failed or produced a schedule that was worse than the unconstrained version. Looser constraints gave it room to find a globally better arrangement. Only tighten constraints where they matter. Another pitfall is the travel matrix. By default, Iterinary calls a public routing API to calculate distances and durations. If you're running this in batch mode with hundreds of requests, you will hit rate limits fast. The fix is to precompute the distance matrix using iterinary matrix --input stops.json --output matrix.csv and then point the build command at the cached matrix with --matrix matrix.csv. This cut my typical processing time from about 2 hours down to roughly 15 minutes on a batch of 80 stops.
Known Limitations and When to Walk Away
Iterinary is not designed for real-time dynamic rerouting. If a vehicle breaks down mid-route or a stop gets cancelled last minute, the tool doesn't have live re-optimization built in. You have to rebuild the entire plan from scratch. For static planning it's fine. For operations that need constant rescheduling, I'd look at something like OR-Tools or a dedicated fleet management platform instead. The output format is JSON only. There's no native export to CSV, KML, or GPX. I ended up writing a small post-processing script to convert the output into KML for Google Earth. It took about an hour to write but saved me from manual conversion every time after that.
Where to Download
You can find the source and installation instructions at github.com/iterinary/iterinary. There is no commercial version or hosted SaaS that I'm aware of. It is free and open source under the MIT license. The package is also available on PyPI as pip install iterinary. If you're dealing with simple itinerary generation and don't need real-time updates, Iterinary handles it without much fuss. Just pay attention to your time windows and cache your distance matrices. Otherwise you'll be waiting around or debugging silent failures.
