Demonstrates the user registration and login flow. The script first calls POST /v1/auth/register to create a new portal account, then calls POST /v1/auth/login to obtain a JWT access token. The token is printed as an export AUTH_TOKEN=... command you can paste into your shell. Use this example first to bootstrap credentials for all JWT-authenticated examples.

Shows how to create a programmatic API key through the portal. Using a JWT token (from login), it calls POST /v1/portal/api-keys with explicit scopes. The returned key is printed as an export API_KEY=... command. Use this to generate keys for all API-key-authenticated examples.

The primary "hello world" example for the optimization API. It loads a real-world VRPTW payload (2 MECH technicians, 48 maintenance orders in Liege) and calls POST /v1/optimize synchronously with an API key. The response includes optimized routes, assignment metrics, distance, duration, and carbon footprint. Demonstrates the simplest integration path: load JSON, POST, read result.

The same Liege field-service optimization as above, but implemented as a Bash/curl one-liner. Useful for quick testing from the terminal without Python. It also documents the field mapping from the legacy payload format (orders/workers/teams) to the new API format (tasks/vehicles/objectives), serving as a migration reference.

Demonstrates the asynchronous job workflow. Instead of blocking on POST /v1/optimize, it submits the job via POST /v1/solve (returns immediately with a job ID), then polls GET /v1/jobs/{id} every second until the status transitions to COMPLETED or FAILED. Prints a summary of routes, assigned/unassigned tasks, distance, and carbon. Use this pattern for large problems or when you need non-blocking execution.

Same asynchronous job pattern as above, but authenticated with a JWT token instead of an API key. Submits via POST /v1/portal/solve and polls GET /v1/portal/jobs/{id}. Demonstrates the portal-authenticated async flow for web app integrations where users are logged in rather than using machine-to-machine API keys.

Shows how to run the same base scenario with domain-specific profile defaults: last-mile delivery, field service, and sales routes. Useful to compare baseline behavior without rewriting objective and constraint blocks manually.

Acceptance-style scenario that compares minimize_total_duration vs minimize_total_cost, validates required_skills_mode='all' + min_technician_rating constraints, and verifies async submit/polling with /v1/solve and /v1/jobs/{id}.

Shows how vehicle cost parameters affect optimization results. Loads the Liege payload and injects cost_per_km, cost_per_hour, and fixed_cost on each vehicle before calling POST /v1/optimize. The response includes total cost breakdowns. Demonstrates the cost-based objective (minimize_total_cost) and how per-vehicle economics influence route assignments.

Demonstrates advanced optimization options: route geometry generation (polylines for map rendering), carbon footprint calculation, solution quality control, and requesting multiple alternative solutions. Configures the options and optimization blocks with include_route_geometry, calculate_carbon_footprint, return_alternative_solutions, and solution_quality.

Runs a side-by-side benchmark with POST /v1/optimize/compare, using the same payload under several strategies (duration, cost_first, sla_first) and returns metrics + best strategy.

Shows the re-optimization (hot-start) workflow for mid-day schedule changes. Takes the Liege payload as a base_request, then applies incremental changes: removes one task (removed_task_ids) and adds a new urgent task (added_tasks). Calls POST /v1/reoptimize with minimize_changes: true to keep disruption minimal.

Computes a distance and travel-time matrix between 4 Belgian cities (Brussels, Liege, Antwerp, Charleroi) using POST /v1/matrix. Uses the OSRM driving profile. Returns an NxN matrix of distances (km) and durations (minutes). Useful standalone for travel-time analysis or pre-computing matrices for external solvers.

Extends the matrix example by requesting three transport profiles in one call: driving, cycling, and walking. Returns separate distance/duration matrices for each mode. Demonstrates multi-modal routing analysis for fleet planning where different vehicle types (cars, bikes, pedestrians) operate in the same service area.

A migration utility that converts a legacy orders/teams/workers JSON payload into the API's /v1/optimize format. Geocodes street addresses to lat/lng coordinates using Nominatim, maps orders to tasks with time windows and skills, maps workers to vehicles with shift schedules and depot locations, and writes the resulting optimize-ready JSON to a file. Demonstrates the full ETL pipeline for integrating legacy scheduling systems.

Lists recent asynchronous optimization jobs using GET /v1/jobs?limit=20. Authenticated with an API key (jobs:read or solve:write). Returns job IDs, statuses (PENDING/RUNNING/COMPLETED/FAILED), creation timestamps, and result summaries. Useful for monitoring batch optimization workloads or building a job dashboard.

Queries route analytics over a date range using GET /v1/analytics/routes. Requests metrics like total_distance_km, total_tasks_completed, and average_utilization, grouped by day. Also demonstrates CSV export by adding format=csv to the query. Requires JWT authentication. Useful for building operational dashboards and KPI tracking.

Retrieves the current billing summary for the authenticated organization using GET /v1/billing/summary. Returns usage counts, plan limits, and cost breakdown. Requires a JWT token. Demonstrates how to programmatically monitor API consumption for cost management and quota tracking.

Walks through the full reporting lifecycle: creates a report template (with summary and utilization sections), schedules it for weekly generation, triggers an immediate run via POST /v1/reports/run, and lists the generated report artifacts. Demonstrates automated reporting for operations teams who need recurring route performance summaries.

Demonstrates webhook integration for event-driven architectures. Creates a webhook endpoint subscribed to job.completed and job.failed events, sends a test event to verify delivery, and lists the delivery log. Shows how to receive real-time notifications when optimization jobs finish, enabling automated downstream workflows (dispatch, notifications, ERP updates).