iCarryUP Routing System — API Documentation

Public / partner documentation This version is intended for customers and partners integrating the APIs. Some sections reserved for administrators (user management, tiers, infrastructure details) are not included.

Base URL & Environments

Endpoints are versioned under /api/v1. Always use HTTPS.

Environment	Base URL	Notes
Production	`https://flow.icarry.it`	Connected to real fleet and jobs scheduled by iCarryUP.

In this partner version, links to Swagger and ReDoc are not shown. Access to /api/docs, /api/redoc, and /openapi.json is restricted to superadmins only (other accounts get 403). For partners, the endpoint list on this page is the reference.

Authentication

The API uses JWT tokens with Bearer. Obtain the token by sending credentials to the OAuth2 token endpoint.

POST /api/v1/auth/token
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=OPS_USER&password=********

The returned token must be sent in the header:

Authorization: Bearer <ACCESS_TOKEN>

⚠️ Set server-side token rotation every 24h or use scheduled refresh. For server-to-server integrations, create dedicated technical users (role: system).

Recommended Workflow

Load logistics data (drivers + deliveries) in the format expected by RoutingOptimizationRequest.
Send POST /api/v1/routing/optimize with async_processing=true; receive a job_id.
Monitor status via GET /api/v1/routing/jobs/{job_id} (polling 5-10s) or via WebSocket /ws/jobs.
When status=completed read result, export files or generate maps with dedicated endpoints.
Optional: set webhook_url in the request to receive push callbacks (payload identical to result).

Critical Endpoints

POST /api/v1/routing/optimize

Submits a new optimization. Supports both modern and legacy payloads (automatic conversion of lat/lng to start_lat, etc.).

{
  "async_processing": true,
  "session_id": "tms-session-example-001",
  "webhook_url": "https://your-tms.example.com/webhooks/routing",
  "delivery_points": [
    {
      "tracking_number": "SHIP-EXAMPLE-0001",
      "delivery_company": "Example SpA",
      "address": "Via Esempio 1, Milano",
      "lat": 45.4642,
      "lng": 9.1900,
      "tot_items": 4,
      "priority": 1
    }
  ],
  "drivers": [
    {
      "name": "Driver example 01",
      "start_lat": 45.5342,
      "start_lng": 9.3265,
      "end_lat": 45.5342,
      "end_lng": 9.3265,
      "capacity": 90,
      "vehicle_type": "van_standard",
      "max_distance_km": 220
    }
  ],
  "algorithms": ["standard"],
  "optimization_objective": "time",
  "optimization_params": {
    "max_iterations": 120,
    "time_limit_seconds": 420,
    
    "distance_weight": 0.5,
    "time_weight": 0.3,
    "balance_weight": 0.2
    
  },
  "constraints": {
    "max_route_distance": 250,
    "max_route_duration": 480,
    "max_stops_per_route": 45
  }
}

Immediate response:

{
  "job_id": "6b758bee-65e5-473e-add8-8cecc36f6fda",
  "status": "queued",
  "estimated_completion": "2025-11-26T09:11:37.123Z",
  "result_url": "/api/v1/routing/jobs/6b758bee-65e5-473e-add8-8cecc36f6fda"
}

GEL (locker pickup): if the user does not have the gel_proximity plan feature (tenant with GEL on map + flag on tier/profile), the backend silently strips pickup_point_id from deliveries and gel_cost_to_time_equivalent_minutes_per_eur from optimization_params before optimization.

Which objective to send

The same four choices as the console wizard. The field is optimization_objective on POST /api/v1/routing/optimize. Default is time. An unknown value is treated as time. They exist because one number cannot be the shortest tour, the most punctual tour, and the cheapest tour at once.

Less time `time`

WhyWithout this, a short-kilometre tour can leave recipients waiting. It penalises waiting and fills time windows.

WhenUse it for SLAs, tight windows, or promised arrival times.

Fewer km `distance`

WhyUse it when kilometres dominate, not the clock. Waiting is not penalised.

WhenUse it when fuel and tolls dominate, stops are sparse, or time windows are few.

Balanced `balanced`

WhyA compromise between time and kilometres, without pushing either extreme.

WhenUse it for a mixed fleet or an ordinary day.

Lower cost `cost`

WhyTurns kilometres and hours into euros using the driver fields hourly_cost, fuel_consumption, prezzo_litro, and costo_pedaggio_km.

WhenUse it for a fleet budget or a cost comparison. budget_max_eur in optimization_params is the cap, not this objective.

This is not balance_options: that splits workload across drivers (similar stop counts, km, or minutes). The weights distance_weight, time_weight, and balance_weight in optimization_params are fine-tuning; for an integration, optimization_objective is enough.

{
  "optimization_objective": "time"
}

Replace time with distance, balanced, or cost. The rest of the optimize request stays as in the example above.

GET /api/v1/routing/jobs/{job_id}

Returns status, progress and, if completed, the full RoutingResultResponse (routes, geometries, global metrics). Results are persisted in shared cache and deleted during scheduled maintenance.

A completed result may include savings_report: estimated savings (km/time/cost) versus a nearest-neighbor baseline on the same job.

GET /api/v1/routing/jobs

Lists the user's latest jobs. Accepts ?limit=50 and ?status=processing/completed... for operational dashboards.

DELETE /api/v1/routing/jobs/{job_id}

Cancels queued or running jobs. Returns 400 if job is already completed.

GET /api/v1/routing/eta

Estimates wall-clock optimization duration (seconds) from similar historical runs (P50/OLS) or the TSP budget. Typical query params: deliveries, drivers, algorithm, routing_provider, has_time_windows, pickup_count, optimization_objective.

GET /api/v1/routing/history

Persistent optimization history for the user/tenant (optionally excludes simulations). Supports q= to search by name or job_id. Useful for dashboards and audit.

GET /api/v1/routing/calendar

Calendar events (planned runs and drafts) for a date range. Powers the console calendar view.

GET /api/v1/routing/status

Enriched health-check (active jobs, version, uptime). Can be used for monitoring systems or readiness probes.

The algorithms_available field is reserved for administrative accounts; for others it is always an empty array.

POST /api/v1/routing/simulate

Starts a what-if simulation (Control Tower) from a baseline job. Returns a simulation_id; the result is an optimization job with is_simulation=true.

{
  "baseline_job_id": "6b758bee-65e5-473e-add8-8cecc36f6fda",
  "baseline_scope": "PLANNED",
  "simulation_mode": "reoptimize",
  "patches": [
    {
      "type": "add_delivery",
      "point_type": "delivery",
      "lat": 41.9028,
      "lng": 12.4964,
      "tracking_number": "NEW-001",
      "pickup_point_id": "HUB-1"
    },
    { "type": "remove_delivery", "tracking_number": "OLD-042" }
  ]
}

Supported patches: add_delivery (also pickups with point_type=pickup and pickup_point_id), remove_delivery, add_driver, remove_driver, delivery_time_window, balance_options, invalidate_matrices. baseline_scope=PLANNED (LIVE not supported in v1).

GET /api/v1/routing/simulations/{simulation_id}

Returns simulation metadata and comparison (baseline vs what-if result).

POST /api/v1/routing/estimate-workload

Estimates workload (minutes/drivers) before choosing the fleet. mode=quick (fast heuristic) or precise (solver with virtual fleet).

GET /api/v1/routing/delivery-execution/summary

Delivery execution KPI (e.g. on-time %) aggregated across the user's recent jobs.

GET /api/v1/routing/jobs/{job_id}/delivery-execution

Per-job delivery execution detail and proof of delivery (POD).

POST /api/v1/routing/manual-assignments

Allows fixing deliveries → driver before launching optimization. Other GET/DELETE /manual-assignments endpoints allow reading/resetting preferences.

POST /api/v1/routing/jobs/{job_id}/generate-real-map

Creates persistent HTML maps (web/static/maps folder) ready for distribution to drivers. GET .../download-map and GET .../export generate maps and Excel respectively.

POST /api/v1/routing/jobs/{job_id}/generate-geometries

Generates road geometries for a completed job (JWT required). Optional If-Match header with routes_version_hash; mismatch returns 409 routes_version_mismatch — retry without the header (geometries come from the stored job).

GET /api/v1/routing/driver-maps

Lists driver maps for the current tenant (JWT required; 401 without token). Superuser without impersonation may see all tenants.

Geocoding (authenticated)

JWT required. POST /optimize does not geocode: numeric lat/lng in the JSON stay mandatory. Call these endpoints first. source is a diagnostic resolver label, not a business contract.

POST /api/v1/geocoding/lookup

Cache only, up to 500 addresses. hit false means not cached (use forward). Does not start an external resolve.

{
  "addresses": ["Via Roma 1, Milano", "Piazza Duomo, Firenze"]
}

{
  "results": [
    { "index": 0, "hit": true, "lat": 45.46, "lng": 9.19, "source": "…", "low_confidence": false, "cache_id": 12 },
    { "index": 1, "hit": false, "lat": null, "lng": null, "source": null, "low_confidence": null, "cache_id": null }
  ]
}

POST /api/v1/geocoding/forward

Resolves up to 10 addresses (raw + query). origin: api (default), wizard, mobile, one_driver, simulator, rubrica. Budget about 25 seconds. status: ok, not_found, pending (retry the same call), error.

{
  "origin": "api",
  "items": [{ "raw": "Via Roma 1, Milano", "query": "Via Roma 1, Milano" }]
}

{
  "results": [
    {
      "status": "ok",
      "lat": 45.46,
      "lng": 9.19,
      "confidence": 90,
      "matched": true,
      "low_confidence": false,
      "source": "…",
      "cache_id": 12
    }
  ]
}

GET /api/geocode_address?address=

Single address, same resolver as forward. 200 with lat/lng; 400 if address is missing; 404 if nothing matched; 503 if the resolve is still pending.

GET /api/reverse_geocode?lat=&lng=

Coordinates to address. 200 { address, source }; 400 if lat or lng is missing; 404 if nothing matched.

Coordinate pins Enterprise

Enterprise plan: store addresses and coordinates. Tenant pins take precedence in lookup/forward. Optional auto-capture from POST /optimize (settings).

POST /api/v1/geocoding/pins

Upsert up to 500 pins. Same role as DELETE and PUT settings: owner, admin, or superuser, plus the geocode_pins feature. A member gets 403 owner_or_admin_required. Each results item has index, status, pin_id, address_key, error.

status: created (new), updated (same address, coordinates moved by at least 5 m), unchanged (move under 5 m), rejected (error: invalid_address, invalid_coordinates, zero_coordinates, swapped_lat_lng, out_of_area), limit_reached (tenant pin cap). summary uses the same counts.

address_key uses the same normalization as lookup and forward: Unicode NFKC, lowercase, collapsed spaces, commas rendered as ", ", leading and trailing spaces and commas removed, 500 characters max. The same string on POST and lookup finds the pin: use the returned value. Civic number, postal code, or extra words change the key; case and double spaces do not.

{
  "items": [
    { "address": "Via Roma 1, 20121 Milano MI", "lat": 45.46, "lng": 9.19, "external_id": "CLI-1" }
  ]
}

{
  "results": [
    { "index": 0, "status": "created", "pin_id": 12, "address_key": "via roma 1, 20121 milano mi", "error": null }
  ],
  "summary": { "created": 1, "updated": 0, "unchanged": 0, "rejected": 0, "limit_reached": 0 }
}

GET /api/v1/geocoding/pins

List pins for anyone with the feature (q from 3 characters, external_id, limit, after_id).

DELETE /api/v1/geocoding/pins/{pin_id}

Delete a pin in your tenant. Owner, admin, or superuser only. Another tenant’s pin returns 404.

GET / PUT /api/v1/geocoding/pins/settings

GET (feature): enabled, auto_capture, count, max_pins. PUT (owner/admin): required body { "auto_capture": true|false }. PUT response: enabled, auto_capture, max_pins.

{ "auto_capture": true }