> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hudhud.sa/llms.txt
> Use this file to discover all available pages before exploring further.

# Plan Vehicle Routes (Alpha)

> Plans routes by assigning jobs to vehicles and ordering the stops for each vehicle.

The contract may change before general availability.



## OpenAPI

````yaml /swagger.json post /routing/optimization
openapi: 3.1.0
info:
  description: >-
    Hudhud Maps provides the most accurate, real-time mapping data for the
    Kingdom of Saudi Arabia.
  title: Next-Generation Geospatial Intelligence for Saudi Arabia
  version: '1.0'
servers:
  - description: Production
    url: https://b.hudhud.sa/v1
security: []
externalDocs:
  description: ''
  url: ''
paths:
  /routing/optimization:
    post:
      tags:
        - Route Optimization
      summary: Plan Vehicle Routes (Alpha)
      description: >-
        Plans routes by assigning jobs to vehicles and ordering the stops for
        each vehicle.


        The contract may change before general availability.
      operationId: RouteOptimization
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RouteOptimizationRequest'
              summary: request
              description: Jobs and vehicles
        description: Jobs and vehicles
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response-RouteOptimizationResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response-any'
          description: Invalid request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response-any'
          description: Missing or invalid API key
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response-any'
          description: No route satisfies the request
        '501':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response-any'
          description: Not supported by the current optimization backend
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response-any'
          description: Route optimization service unavailable
        '504':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response-any'
          description: Route optimization timed out
      security:
        - BearerAuth: []
components:
  schemas:
    RouteOptimizationRequest:
      properties:
        model:
          $ref: '#/components/schemas/VehicleRoutingModel'
      required:
        - model
      type: object
    Response-RouteOptimizationResponse:
      properties:
        data:
          $ref: '#/components/schemas/RouteOptimizationResponse'
        error:
          description: Error message (only present when ok is false)
          example: ''
          type: string
        ok:
          description: Whether the request was successful
          example: true
          type: boolean
      type: object
    Response-any:
      properties:
        data:
          description: Response payload
        error:
          description: Error message (only present when ok is false)
          example: ''
          type: string
        ok:
          description: Whether the request was successful
          example: true
          type: boolean
      type: object
    VehicleRoutingModel:
      properties:
        jobs:
          items:
            $ref: '#/components/schemas/RouteOptimizationJob'
          type: array
          uniqueItems: false
        vehicles:
          items:
            $ref: '#/components/schemas/RouteOptimizationVehicle'
          type: array
          uniqueItems: false
      required:
        - jobs
        - vehicles
      type: object
    RouteOptimizationResponse:
      description: Response payload
      properties:
        metrics:
          $ref: '#/components/schemas/RoutePlanMetrics'
        routes:
          items:
            $ref: '#/components/schemas/PlannedVehicleRoute'
          type: array
          uniqueItems: false
        unassigned_job_ids:
          items:
            type: string
          type: array
          uniqueItems: false
      type: object
    RouteOptimizationJob:
      properties:
        demand:
          example: 1
          type: integer
        id:
          example: delivery-1
          type: string
        location:
          $ref: '#/components/schemas/GeoPoint'
      required:
        - id
        - location
      type: object
    RouteOptimizationVehicle:
      properties:
        capacity:
          example: 100
          type: integer
        end_location:
          $ref: '#/components/schemas/GeoPoint'
        id:
          example: vehicle-1
          type: string
        routing_profile:
          $ref: '#/components/schemas/RoutingProfile'
        start_location:
          $ref: '#/components/schemas/GeoPoint'
      required:
        - id
        - routing_profile
        - start_location
      type: object
    RoutePlanMetrics:
      properties:
        travel_distance_meters:
          type: number
        travel_duration_seconds:
          type: number
        used_vehicle_count:
          type: integer
      type: object
    PlannedVehicleRoute:
      properties:
        metrics:
          $ref: '#/components/schemas/RouteMetrics'
        vehicle_id:
          type: string
        visits:
          items:
            $ref: '#/components/schemas/RouteOptimizationVisit'
          type: array
          uniqueItems: false
      type: object
    GeoPoint:
      description: A geographic coordinate in WGS84 decimal degrees
      properties:
        lat:
          example: 24.7136
          format: double
          type: number
        lon:
          example: 46.6753
          format: double
          type: number
      required:
        - lat
        - lon
      type: object
    RoutingProfile:
      enum:
        - car
        - truck
      example: car
      type: string
      x-enum-varnames:
        - RoutingProfileCar
        - RoutingProfileTruck
    RouteMetrics:
      properties:
        travel_distance_meters:
          type: number
        travel_duration_seconds:
          type: number
      type: object
    RouteOptimizationVisit:
      properties:
        job_id:
          type: string
      type: object
  securitySchemes:
    BearerAuth:
      description: >-
        JWT Bearer token for authentication. Example: "Bearer
        YOUR_API_TOKEN_HERE"
      in: header
      name: Authorization
      type: apiKey

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.