Fleet Route Optimizer

List the built-in example routing problems. Use one to see a realistic input, or solve it as-is to show what the tool does.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Return the full input of one example, in exactly the shape optimize_routes accepts. Edit it (depot, stops, vehicles, windows) to match the user's situation.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "lang": {
      "type": "string",
      "enum": [
        "en",
        "es"
      ],
      "description": "es = Spanish labels."
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false
}

Plan routes for one or more vehicles from one depot and return, per vehicle, the stop order with arrival times and load so far, plus stops that could not be served, totals, Google Maps links and warnings. Uses real road driving times. Solves take 10-60 s (more when many addresses must be looked up). Pass either `example` or the fields below. If the result has status 'running', call get_route_result with its job_id. Minimal example: {"depot": {"address": "1600 Pennsylvania Ave NW, Washington, DC 20500"}, "stops": [{"id": "Ana", "address": "..."}, {"id": "Bob", "lat": 38.9, "lon": -77.03, "window_open": "09:00", "window_close": "12:00", "service_minutes": 10}], "vehicles": 2}. Omitted: capacity = unlimited, no time windows, 1 vehicle, stops are dropped only when they cannot be served at all. Call get_route_example for complete, realistic inputs.

{
  "type": "object",
  "properties": {
    "example": {
      "type": "string",
      "description": "Solve this built-in example instead of passing the fields below."
    },
    "depot": {
      "type": "object",
      "description": "Where every vehicle starts and ends. Needs an address or lat+lon.",
      "properties": {
        "id": {
          "type": "string"
        },
        "address": {
          "type": "string",
          "description": "Street address to geocode. Include city and ZIP/postcode. Not needed when lat and lon are given (lat/lon is faster and never fails)."
        },
        "lat": {
          "type": "number",
          "description": "Latitude, decimal degrees."
        },
        "lon": {
          "type": "number",
          "description": "Longitude, decimal degrees."
        },
        "open": {
          "type": [
            "string",
            "number"
          ],
          "description": "Earliest departure. Clock time 'HH:MM' (24 h), '8:30 AM', or minutes after midnight (480 = 08:00). Default 00:00."
        },
        "close": {
          "type": [
            "string",
            "number"
          ],
          "description": "Latest return. Clock time 'HH:MM' (24 h), '8:30 AM', or minutes after midnight (480 = 08:00). Default 24:00."
        }
      }
    },
    "stops": {
      "type": "array",
      "minItems": 1,
      "maxItems": 100,
      "description": "The places to visit (not the depot). Each needs an address or lat+lon.",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Your label for the stop (customer name, order no.). Used in results and in previous_routes. Default 'stop N' (1-based)."
          },
          "address": {
            "type": "string",
            "description": "Street address to geocode. Include city and ZIP/postcode. Not needed when lat and lon are given (lat/lon is faster and never fails)."
          },
          "lat": {
            "type": "number",
            "description": "Latitude, decimal degrees."
          },
          "lon": {
            "type": "number",
            "description": "Longitude, decimal degrees."
          },
          "demand": {
            "type": "number",
            "description": "Quantity delivered here (boxes, kg...). Counts against vehicle capacity. Default 0."
          },
          "demand2": {
            "type": "number",
            "description": "Second quantity (e.g. weight), against capacity2."
          },
          "demand3": {
            "type": "number",
            "description": "Third quantity (e.g. pallets), against capacity3."
          },
          "service_minutes": {
            "type": "number",
            "description": "Minutes spent at the stop. Default 0."
          },
          "window_open": {
            "type": [
              "string",
              "number"
            ],
            "description": "Earliest arrival. Clock time 'HH:MM' (24 h), '8:30 AM', or minutes after midnight (480 = 08:00). Default 00:00."
          },
          "window_close": {
            "type": [
              "string",
              "number"
            ],
            "description": "Latest arrival. Clock time 'HH:MM' (24 h), '8:30 AM', or minutes after midnight (480 = 08:00). Default 24:00. Hard unless parameters.LatePenaltyPerMinute > 0."
          },
          "closed_from": {
            "type": [
              "string",
              "number"
            ],
            "description": "Start of a period inside the window when the stop cannot be visited (e.g. lunch). Clock time 'HH:MM' (24 h), '8:30 AM', or minutes after midnight (480 = 08:00)."
          },
          "closed_to": {
            "type": [
              "string",
              "number"
            ],
            "description": "End of that period."
          }
        }
      }
    },
    "vehicles": {
      "description": "Either a number of identical vehicles (unlimited capacity), or one object per vehicle.",
      "oneOf": [
        {
          "type": "integer",
          "minimum": 1,
          "maximum": 25
        },
        {
          "type": "array",
          "minItems": 1,
          "maxItems": 25,
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Name, e.g. 'Van 1'."
              },
              "capacity": {
                "type": "number",
                "description": "Max total demand. Omitted = unlimited."
              },
              "capacity2": {
                "type": "number"
              },
              "capacity3": {
                "type": "number"
              },
              "fixed_cost": {
                "type": "number",
                "description": "Cost of using this vehicle at all, in driving minutes. Raise it to use fewer vehicles. Default 0."
              },
              "max_route_minutes": {
                "type": "number",
                "description": "Longest route, depot to depot, waiting included."
              },
              "speed_factor": {
                "type": "number",
                "description": "Driving time multiplier: 1.2 = 20% slower. Default 1."
              },
              "service_factor": {
                "type": "number",
                "description": "Service time multiplier. Default 1."
              }
            }
          }
        }
      ]
    },
    "country": {
      "type": "string",
      "enum": [
        "US",
        "OTHER"
      ],
      "description": "Which geocoder reads the addresses: US (US Census, then OpenStreetMap) or OTHER (OpenStreetMap). Default US."
    },
    "previous_routes": {
      "type": "array",
      "description": "Re-optimize from existing routes: one list of stop ids (or 1-based stop numbers) per vehicle, in visiting order. The solver starts from these and improves them; new stops are fitted in.",
      "items": {
        "type": "array",
        "items": {
          "type": [
            "string",
            "integer"
          ]
        }
      }
    },
    "parameters": {
      "type": "object",
      "description": "Optional engine settings: SearchParametersTimeLimit (seconds, default 30, max 60), NoImprovementSeconds (20), RouteTimeLimit (minutes, default 1440), DroppedOrderCost (100000 = serve every stop that can be served), MinuteCost (1), LatePenaltyPerMinute (0 = windows are hard), MaxWaitMinutes (1440), MinimumDriveTime (5)."
    },
    "wait_seconds": {
      "type": "integer",
      "minimum": 0,
      "maximum": 45,
      "description": "How long to wait for the solve inside this call (default 25)."
    }
  }
}

Fetch the result of an optimize_routes job that returned status 'running'. Waits up to wait_seconds; call again while status is 'running'. Jobs expire 15 minutes after they finish.

{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "string"
    },
    "wait_seconds": {
      "type": "integer",
      "minimum": 0,
      "maximum": 45
    }
  },
  "required": [
    "job_id"
  ],
  "additionalProperties": false
}