OpenAPI (Swagger) Specification (v1)
openapi: 3.0.3
info:
title: AlgoStack Route Optimization API
description: High-performance route optimization powered by Google OR-Tools
version: “1.0.0”
servers:
– url: https://api.algostack.cloud
security:
– bearerAuth: []
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API_KEY
paths:
/health:
get:
summary: Health check
responses:
“200”:
description: API health status
/ortools/optimize:
post:
summary: Submit a route optimization job
security:
– bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
use_traffic:
type: boolean
gmaps_api_key:
type: string
warehouses:
type: array
items:
$ref: “#/components/schemas/Warehouse”
orders:
type: array
items:
$ref: “#/components/schemas/Order”
responses:
“200”:
description: Job accepted
content:
application/json:
schema:
type: object
properties:
job_id:
type: string
status:
type: string
/ortools/status/{job_id}:
get:
summary: Get optimization job status
parameters:
– name: job_id
in: path
required: true
schema:
type: string
security:
– bearerAuth: []
responses:
“200”:
description: Job status and result
components:
schemas:
Warehouse:
type: object
required: [latitude, longitude]
properties:
id:
type: string
name:
type: string
latitude:
type: number
longitude:
type: number
capacity:
type: integer
Order:
type: object
required: [client_object_latitude, client_object_longitude]
properties:
order_id:
type: string
priority:
type: integer
client_object_latitude:
type: number
client_object_longitude:
type: number
order_items:
type: array
items:
type: object
properties:
quantity:
type: number
Advanced Constraint Examples (Developer-Focused)
These examples map directly to your OR-Tools logic.
Capacity Constraints (Per Vehicle)
json
Copy code
{
“warehouses”: [
{
“id”: “wh_1”,
“capacity”: 150
}
],
“orders”: [
{
“order_id”: “ord_101”,
“order_items”: [
{ “quantity”: 40 }
]
}
]
}
✔ Automatically enforced via OR-Tools AddDimensionWithVehicleCapacity
✔ Over-capacity orders become unassigned instead of breaking routes
Time Windows & Service Time
json
Copy code
{
“orders”: [
{
“order_id”: “ord_202”,
“priority”: 10,
“time_window”: {
“start”: 480,
“end”: 720
}
}
]
}
✔ Modeled using the OR-Tools Time Dimension
✔ Service time added per stop
✔ Violations handled via penalties or disjunctions
Soft Constraints (Penalties)
Orders may be skipped, but at a cost:
json
Copy code
{
“orders”: [
{
“order_id”: “ord_optional”,
“priority”: 1
}
]
}
✔ Low-priority orders receive lower penalties
✔ Solver decides whether skipping is optimal
✔ Ideal for overflow, optional, or SLA-flexible jobs
Task Sequencing / Prerequisites
Model tool pickup → delivery → return flow:
json
Copy code
{
“orders”: [
{
“order_id”: “pickup_tools”,
“priority”: 20
},
{
“order_id”: “job_site”,
“priority”: 10
}
]
}
✔ Sequencing enforced through solver ordering
✔ Service time differs by node type
✔ Enables real-world workflows
Traffic-Aware Optimization
json
Copy code
{
“use_traffic”: true,
“gmaps_api_key”: “YOUR_GMAPS_KEY”
}
✔ Google Maps Distance Matrix
✔ duration_in_traffic used automatically
✔ Falls back to Haversine if unavailable