Optimize a route from plain addresses

Turn a spreadsheet of address strings into coordinates, then into an optimized route — the two calls in the right order, and when one call is enough.

What you have is a column of addresses from a CRM or a spreadsheet. What the optimizer needs is coordinates. You can let the optimization geocode them for you (send the strings with `geocoding.region`), but geocoding first lets you review ambiguous matches before anything is routed.

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

—One call: send addresses without lat/lng plus geocoding.region and the optimization geocodes them, refusing with 422 GEOCODING_UNRESOLVED (and the candidates) rather than guessing.
—One POST /api/v1/geocoding/bulk call geocodes the whole list — far cheaper than one call per address.
—One result per distinct address, in the order first sent — match by original, never by position; a status of ambiguous or not_found needs a better input, and only precision: "address" is exact enough to drive to.
—Geocoding is charged per distinct address, priced through at what it costs us.
—Feed the returned coordinates straight into the optimization body.

Step 1 — geocode the addresses

Send the raw strings and get one result per distinct address back, keyed by `original`. Keep the ones with status `ok`.

curl -X POST https://r4m.ai/api/v1/geocoding/bulk \
  -H "Authorization: Bearer acc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "addresses": [
    "25 Kent Ave, Brooklyn, NY 11249",
    "1 Front St, Brooklyn, NY 11201",
    "445 Albee Square W, Brooklyn, NY 11201"
  ]
}'

Step 2 — optimize

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": 900
    },
    {
      "address": "1155 Manhattan Ave, Brooklyn, NY",
      "lat": 40.7304,
      "lng": -73.954,
      "serviceTimeSeconds": 600,
      "timeWindowStart": "09:00",
      "timeWindowEnd": "10:30",
      "priority": 1
    },
    {
      "address": "238 Bedford Ave, Brooklyn, NY",
      "lat": 40.7135,
      "lng": -73.967,
      "serviceTimeSeconds": 900
    },
    {
      "address": "1 Front St, Brooklyn, NY",
      "lat": 40.7033,
      "lng": -73.9881,
      "serviceTimeSeconds": 600,
      "priority": 2
    },
    {
      "address": "445 Albee Square W, Brooklyn, NY",
      "lat": 40.6926,
      "lng": -73.9873,
      "serviceTimeSeconds": 1200
    }
  ],
  "parameters": {
    "travelMode": "driving",
    "optimizeMode": "Time",
    "roundTrip": true,
    "routeStartAt": "2026-04-14T08:00",
    "timezone": "America/New_York"
  },
  "webhookUrl": "https://your-server.com/webhooks/r4m"
}'

# 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": 900
      },
      {
        "address": "1155 Manhattan Ave, Brooklyn, NY",
        "lat": 40.7304,
        "lng": -73.954,
        "serviceTimeSeconds": 600,
        "timeWindowStart": "09:00",
        "timeWindowEnd": "10:30",
        "priority": 1
      },
      {
        "address": "238 Bedford Ave, Brooklyn, NY",
        "lat": 40.7135,
        "lng": -73.967,
        "serviceTimeSeconds": 900
      },
      {
        "address": "1 Front St, Brooklyn, NY",
        "lat": 40.7033,
        "lng": -73.9881,
        "serviceTimeSeconds": 600,
        "priority": 2
      },
      {
        "address": "445 Albee Square W, Brooklyn, NY",
        "lat": 40.6926,
        "lng": -73.9873,
        "serviceTimeSeconds": 1200
      }
    ],
    "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(900)},
            {Address: "1155 Manhattan Ave, Brooklyn, NY", Lat: r4m.Ptr(40.7304), Lng: r4m.Ptr(-73.954), ServiceTimeSeconds: r4m.Ptr(600), TimeWindowStart: r4m.Ptr("09:00"), TimeWindowEnd: r4m.Ptr("10:30"), Priority: r4m.Ptr(1)},
            {Address: "238 Bedford Ave, Brooklyn, NY", Lat: r4m.Ptr(40.7135), Lng: r4m.Ptr(-73.967), ServiceTimeSeconds: r4m.Ptr(900)},
            {Address: "1 Front St, Brooklyn, NY", Lat: r4m.Ptr(40.7033), Lng: r4m.Ptr(-73.9881), ServiceTimeSeconds: r4m.Ptr(600), Priority: r4m.Ptr(2)},
            {Address: "445 Albee Square W, Brooklyn, NY", Lat: r4m.Ptr(40.6926), Lng: r4m.Ptr(-73.9873), ServiceTimeSeconds: r4m.Ptr(1200)},
        },
        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

Optimize a multi-stop delivery runTurn a depot and a list of stops into the order to drive them in, with per-stop service time and a return to the depot.Plan deliveries with customer time windowsGive each stop the window the customer agreed to and let the optimizer sequence the day around them.Split a day's stops across a fleetHand the optimizer more stops than one vehicle can finish and cap each route, so the work comes back split across drivers.