Plan deliveries with customer time windows

Give each stop the window the customer agreed to and let the optimizer sequence the day around them.

Your customers were promised slots — 9 to 10:30, 1 to 4 — and a route that ignores them is worse than no route at all.

The prompt is a complete brief — the task, this request body, the rules the API validates against, and the result shape to check against. Paste it into Claude Code, Cursor or any coding agent. The MCP setup connects an agent to the live API instead, so it can run the optimization itself.

What this shows

—timeWindowStart / timeWindowEnd are LOCAL times of day, written without a zone suffix.
—Because they are local, routeStartAt (which day) and timezone (whose clock) are both required.
—A stop must finish inside its window, so a window shorter than the stop's serviceTimeSeconds is rejected before it reaches the solver.
—priority breaks ties between stops the windows leave equally free.

The request

You send

curl -X POST https://r4m.ai/api/v1/optimizations \
  -H "Authorization: Bearer acc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "addresses": [
    {
      "address": "Depot — 25 Kent Ave, Brooklyn, NY",
      "lat": 40.7218,
      "lng": -73.9615,
      "isDepot": true,
      "serviceTimeSeconds": 600
    },
    {
      "address": "1155 Manhattan Ave, Brooklyn, NY",
      "lat": 40.7304,
      "lng": -73.954,
      "serviceTimeSeconds": 900,
      "timeWindowStart": "09:00",
      "timeWindowEnd": "10:30"
    },
    {
      "address": "238 Bedford Ave, Brooklyn, NY",
      "lat": 40.7135,
      "lng": -73.967,
      "serviceTimeSeconds": 600,
      "timeWindowStart": "09:30",
      "timeWindowEnd": "12:00"
    },
    {
      "address": "1 Front St, Brooklyn, NY",
      "lat": 40.7033,
      "lng": -73.9881,
      "serviceTimeSeconds": 1200,
      "timeWindowStart": "13:00",
      "timeWindowEnd": "16:00",
      "priority": 1
    },
    {
      "address": "445 Albee Square W, Brooklyn, NY",
      "lat": 40.6926,
      "lng": -73.9873,
      "serviceTimeSeconds": 900,
      "timeWindowStart": "14:00",
      "timeWindowEnd": "17:00"
    }
  ],
  "parameters": {
    "travelMode": "driving",
    "optimizeMode": "Time",
    "roundTrip": true,
    "routeStartAt": "2026-04-14T08:00",
    "timezone": "America/New_York"
  }
}'

# 202 Accepted — this call returns immediately; the solver keeps working (2-60s)
# { "success": true, "data": { "id": "550e8400-…", "status": "pending" } }
#
# That id is how you collect the finished plan. Either:
#   webhook — we POST it to your webhookUrl the moment it is ready, or
#   polling — GET /api/v1/optimizations/{id} until status is "completed"

import { createClient } from "@r4mai/sdk";

const r4m = createClient({ apiKey: "acc_your_api_key" });

// Submits, waits out the solve, and hands back the finished plan.
// Pass a webhookUrl instead if you would rather be notified.
const { data: optimization, error } = await r4m.createOptimizationAndWaitForRoutes({
  body: {
    "addresses": [
      {
        "address": "Depot — 25 Kent Ave, Brooklyn, NY",
        "lat": 40.7218,
        "lng": -73.9615,
        "isDepot": true,
        "serviceTimeSeconds": 600
      },
      {
        "address": "1155 Manhattan Ave, Brooklyn, NY",
        "lat": 40.7304,
        "lng": -73.954,
        "serviceTimeSeconds": 900,
        "timeWindowStart": "09:00",
        "timeWindowEnd": "10:30"
      },
      {
        "address": "238 Bedford Ave, Brooklyn, NY",
        "lat": 40.7135,
        "lng": -73.967,
        "serviceTimeSeconds": 600,
        "timeWindowStart": "09:30",
        "timeWindowEnd": "12:00"
      },
      {
        "address": "1 Front St, Brooklyn, NY",
        "lat": 40.7033,
        "lng": -73.9881,
        "serviceTimeSeconds": 1200,
        "timeWindowStart": "13:00",
        "timeWindowEnd": "16:00",
        "priority": 1
      },
      {
        "address": "445 Albee Square W, Brooklyn, NY",
        "lat": 40.6926,
        "lng": -73.9873,
        "serviceTimeSeconds": 900,
        "timeWindowStart": "14:00",
        "timeWindowEnd": "17:00"
      }
    ],
    "parameters": {
      "travelMode": "driving",
      "optimizeMode": "Time",
      "roundTrip": true,
      "routeStartAt": "2026-04-14T08:00",
      "timezone": "America/New_York"
    }
  },
});
if (error) throw error;

console.log(optimization.result);

package main

import (
    "context"
    "fmt"
    "log"

    r4m "github.com/r4m-ai/sdk-go"
)

func main() {
    ctx := context.Background()

    client, err := r4m.New("acc_your_api_key")
    if err != nil {
        log.Fatal(err)
    }

    // Submits, waits out the solve, and hands back the finished plan.
    // Set WebhookUrl instead if you would rather be notified.
    optimization, err := client.CreateOptimizationAndWaitForRoutes(ctx, r4m.CreateOptimizationRequest{
        Addresses: []r4m.Address{
            {Address: "Depot — 25 Kent Ave, Brooklyn, NY", Lat: r4m.Ptr(40.7218), Lng: r4m.Ptr(-73.9615), IsDepot: r4m.Ptr(true), ServiceTimeSeconds: r4m.Ptr(600)},
            {Address: "1155 Manhattan Ave, Brooklyn, NY", Lat: r4m.Ptr(40.7304), Lng: r4m.Ptr(-73.954), ServiceTimeSeconds: r4m.Ptr(900), TimeWindowStart: r4m.Ptr("09:00"), TimeWindowEnd: r4m.Ptr("10:30")},
            {Address: "238 Bedford Ave, Brooklyn, NY", Lat: r4m.Ptr(40.7135), Lng: r4m.Ptr(-73.967), ServiceTimeSeconds: r4m.Ptr(600), TimeWindowStart: r4m.Ptr("09:30"), TimeWindowEnd: r4m.Ptr("12:00")},
            {Address: "1 Front St, Brooklyn, NY", Lat: r4m.Ptr(40.7033), Lng: r4m.Ptr(-73.9881), ServiceTimeSeconds: r4m.Ptr(1200), TimeWindowStart: r4m.Ptr("13:00"), TimeWindowEnd: r4m.Ptr("16:00"), Priority: r4m.Ptr(1)},
            {Address: "445 Albee Square W, Brooklyn, NY", Lat: r4m.Ptr(40.6926), Lng: r4m.Ptr(-73.9873), ServiceTimeSeconds: r4m.Ptr(900), TimeWindowStart: r4m.Ptr("14:00"), TimeWindowEnd: r4m.Ptr("17:00")},
        },
        Parameters: &r4m.OptimizationParameters{
            TravelMode: r4m.Ptr(r4m.Driving),
            OptimizeMode: r4m.Ptr(r4m.Time),
            RoundTrip: r4m.Ptr(true),
            RouteStartAt: r4m.Ptr("2026-04-14T08:00"),
            Timezone: r4m.Ptr("America/New_York"),
        },
    }, r4m.WaitOptions{})
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(optimization.Result)
}

You get back

The POST answers immediately with a pending id; this is the completed optimization, abridged. Collect it by polling or webhook.

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "priceMicros": 10000,
    "webhookUrl": "https://your-server.com/webhooks/r4m",
    "webhookStatus": "delivered",
    "result": {
      "routes": [
        {
          "routeStartAt": "2026-04-14T08:00:00-04:00",
          "totalDistanceMeters": 19473,
          "totalTimeSeconds": 8285,
          "polyline": "ulpwFpplbMl@qA@CLOYYIIIK…",
          "waypoints": [
            {
              "index": 0,
              "arrivalAt": "2026-04-14T08:00:00-04:00",
              "departureAt": "2026-04-14T08:15:00-04:00",
              "waitTimeSeconds": 0,
              "cumulativeDistanceMeters": 0,
              "cumulativeTimeSeconds": 0,
              "polylineToNext": "ulpwFpplbMl@qA@CLOYYIIIK…"
            },
            {
              "index": 1,
              "arrivalAt": "2026-04-14T09:00:00-04:00",
              "departureAt": "2026-04-14T09:10:00-04:00",
              "waitTimeSeconds": 2543,
              "cumulativeDistanceMeters": 1416,
              "cumulativeTimeSeconds": 3600,
              "polylineToNext": "}brwFhckbMI{A?IGkAIqBMkC…"
            }
          ]
        }
      ],
      "unroutedStops": []
    },
    "createdAt": "2026-04-14T11:58:12Z",
    "updatedAt": "2026-04-14T11:58:41Z"
  }
}

Other recipes