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

# Solve a vehicle routing problem



## OpenAPI

````yaml /openapi/optimize.json post /optimize
openapi: 3.1.0
info:
  title: JustRouting Optimize API
  version: v1
  description: >-
    Hosted VROOM vehicle routing solver. Send a JSON problem description
    (vehicles + jobs/shipments), receive optimized routes. Distances and
    durations come from the real road network (OSRM). The input/output format is
    compatible with the upstream VROOM API; JustRouting adds `profile:
    car|motorcycle` per vehicle and `geometry: true` for polyline output.
  contact:
    email: hello@justrouting.tech
    name: JustRouting
    url: https://justrouting.tech
servers:
  - url: https://api.justrouting.tech
    description: Production
security:
  - bearerAuth: []
paths:
  /optimize:
    post:
      summary: Solve a vehicle routing problem
      operationId: solveOptimize
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VroomInput'
            examples:
              twoVehiclesSixJobs:
                summary: Two vehicles, six jobs
                value:
                  vehicles:
                    - id: 1
                      profile: car
                      start:
                        - 103.79234106
                        - 1.32463108
                      end:
                        - 103.79234106
                        - 1.32463108
                    - id: 2
                      profile: car
                      start:
                        - 103.82324228
                        - 1.32408622
                      end:
                        - 103.82324228
                        - 1.32408622
                  jobs:
                    - id: 1
                      location:
                        - 103.79751693
                        - 1.31035001
                    - id: 2
                      location:
                        - 103.78432387
                        - 1.31490148
                    - id: 3
                      location:
                        - 103.79763397
                        - 1.31980519
                    - id: 4
                      location:
                        - 103.81234512
                        - 1.31824846
                    - id: 5
                      location:
                        - 103.82152987
                        - 1.30984208
                    - id: 6
                      location:
                        - 103.83701939
                        - 1.32143977
      responses:
        '200':
          description: Problem solved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VroomOutput'
        '400':
          description: Invalid input (code 2) — details in the `error` field
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VroomError'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthError'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
components:
  schemas:
    VroomInput:
      type: object
      required:
        - vehicles
        - jobs
      properties:
        vehicles:
          type: array
          items:
            $ref: '#/components/schemas/Vehicle'
          description: 'Available vehicles. Free plan: up to 10; Hobby: up to 50.'
        jobs:
          type: array
          items:
            $ref: '#/components/schemas/Job'
          description: 'Tasks to serve. Free plan: up to 100; Hobby: up to 1,000.'
        shipments:
          type: array
          items:
            $ref: '#/components/schemas/Shipment'
          description: Pickup-and-delivery tasks (pickup must precede delivery).
        matrices:
          $ref: '#/components/schemas/CustomMatrices'
          description: >-
            Optional custom travel-time matrices per profile; skips OSRM table
            calls.
        geometry:
          type: boolean
          default: false
          description: Add polyline geometry to each route in the response.
      minProperties: 1
    VroomOutput:
      type: object
      properties:
        code:
          type: integer
          enum:
            - 0
            - 1
            - 2
            - 3
          description: 0 = ok, 1 = internal error, 2 = input error, 3 = routing error.
        error:
          type: string
          description: Present when code != 0.
        summary:
          $ref: '#/components/schemas/Summary'
        unassigned:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
              type:
                type: string
              location:
                type: array
                items:
                  type: number
              description:
                type: string
        routes:
          type: array
          items:
            $ref: '#/components/schemas/Route'
    VroomError:
      type: object
      properties:
        code:
          type: integer
        error:
          type: string
    AuthError:
      type: object
      properties:
        code:
          type: string
          enum:
            - missing_auth
            - invalid_api_key
        message:
          type: string
    RateLimitError:
      type: object
      properties:
        code:
          type: string
          enum:
            - rate_limited
        message:
          type: string
    Vehicle:
      type: object
      required:
        - id
      properties:
        id:
          type: integer
        profile:
          type: string
          enum:
            - car
            - motorcycle
          default: car
          description: Routing profile (JustRouting extension).
        description:
          type: string
        start:
          type: array
          items:
            type: number
          minItems: 2
          maxItems: 2
          description: Depot as `[lng, lat]`.
        end:
          type: array
          items:
            type: number
          minItems: 2
          maxItems: 2
          description: >-
            Return depot as `[lng, lat]`; same as start for a round trip; omit
            to stop at the last task.
        start_index:
          type: integer
          description: Row/column in custom matrices.
        end_index:
          type: integer
        capacity:
          type: array
          items:
            type: integer
          description: Multidimensional capacity (e.g. weight, volume).
        skills:
          type: array
          items:
            type: integer
          description: Job skills must be a subset of vehicle skills.
        type:
          type: string
          description: Vehicle type, referenced by per-type service times.
        time_window:
          $ref: '#/components/schemas/TimeWindow'
        breaks:
          type: array
          items:
            $ref: '#/components/schemas/Break'
        speed_factor:
          type: number
          exclusiveMinimum: 0
          maximum: 5
          description: Scales all travel times for this vehicle.
        max_tasks:
          type: integer
        max_travel_time:
          type: integer
          description: Seconds.
        max_distance:
          type: integer
          description: Meters.
        costs:
          $ref: '#/components/schemas/VehicleCosts'
        steps:
          type: array
          items:
            $ref: '#/components/schemas/VehicleStep'
          description: Custom route in plan mode, or search warm start in solving mode.
    Job:
      type: object
      required:
        - id
        - location
      properties:
        id:
          type: integer
        description:
          type: string
        location:
          type: array
          items:
            type: number
          minItems: 2
          maxItems: 2
          description: '`[lng, lat]`.'
        location_index:
          type: integer
        setup:
          type: integer
          description: Setup duration in seconds.
        service:
          type: integer
          description: Service duration in seconds.
        delivery:
          type: array
          items:
            type: integer
          description: Amounts to deliver (loaded at vehicle start).
        pickup:
          type: array
          items:
            type: integer
          description: Amounts to pick up (returned at vehicle end).
        skills:
          type: array
          items:
            type: integer
        priority:
          type: integer
          minimum: 0
          maximum: 100
          description: Higher priority tasks are preferred when not all tasks fit.
        time_windows:
          type: array
          items:
            $ref: '#/components/schemas/TimeWindow'
          description: Valid slots for service start.
    Shipment:
      type: object
      required:
        - pickup
        - delivery
      properties:
        pickup:
          $ref: '#/components/schemas/ShipmentStep'
        delivery:
          $ref: '#/components/schemas/ShipmentStep'
        amount:
          type: array
          items:
            type: integer
        skills:
          type: array
          items:
            type: integer
        priority:
          type: integer
          minimum: 0
          maximum: 100
    CustomMatrices:
      type: object
      description: >-
        Per-profile custom matrices. Providing durations for all profiles makes
        task locations optional.
      additionalProperties:
        type: object
        properties:
          durations:
            type: array
            items:
              type: array
              items:
                type: integer
          distances:
            type: array
            items:
              type: array
              items:
                type: integer
          costs:
            type: array
            items:
              type: array
              items:
                type: integer
    Summary:
      type: object
      properties:
        cost:
          type: integer
        routes:
          type: integer
        unassigned:
          type: integer
        setup:
          type: integer
        service:
          type: integer
        duration:
          type: integer
          description: Total travel time in seconds.
        waiting_time:
          type: integer
        priority:
          type: integer
        distance:
          type: integer
          description: Total distance in meters (when requested).
        delivery:
          type: array
          items:
            type: integer
        pickup:
          type: array
          items:
            type: integer
        violations:
          type: array
          items:
            $ref: '#/components/schemas/Violation'
    Route:
      type: object
      properties:
        vehicle:
          type: integer
        cost:
          type: integer
        setup:
          type: integer
        service:
          type: integer
        duration:
          type: integer
          description: Travel time in seconds.
        waiting_time:
          type: integer
        priority:
          type: integer
        distance:
          type: integer
          description: Meters (when requested).
        geometry:
          type: string
          description: 'Encoded polyline (when geometry: true).'
        delivery:
          type: array
          items:
            type: integer
        pickup:
          type: array
          items:
            type: integer
        description:
          type: string
        steps:
          type: array
          items:
            $ref: '#/components/schemas/Step'
        violations:
          type: array
          items:
            $ref: '#/components/schemas/Violation'
    TimeWindow:
      type: array
      minItems: 2
      maxItems: 2
      items:
        type: integer
      description: >-
        `[start, end]` in seconds relative to the planning horizon, or absolute
        UNIX timestamps (consistent within one request).
    Break:
      type: object
      required:
        - id
      properties:
        id:
          type: integer
        time_windows:
          type: array
          items:
            $ref: '#/components/schemas/TimeWindow'
        service:
          type: integer
          description: Break duration in seconds.
        description:
          type: string
        max_load:
          type: array
          items:
            type: integer
    VehicleCosts:
      type: object
      properties:
        fixed:
          type: integer
          default: 0
        per_hour:
          type: integer
          default: 3600
        per_task_hour:
          type: integer
          default: 0
        per_km:
          type: integer
          default: 0
    VehicleStep:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - start
            - job
            - pickup
            - delivery
            - break
            - end
        id:
          type: integer
        service_at:
          type: integer
        service_after:
          type: integer
        service_before:
          type: integer
    ShipmentStep:
      type: object
      required:
        - id
        - location
      properties:
        id:
          type: integer
        description:
          type: string
        location:
          type: array
          items:
            type: number
          minItems: 2
          maxItems: 2
        setup:
          type: integer
        service:
          type: integer
        time_windows:
          type: array
          items:
            $ref: '#/components/schemas/TimeWindow'
    Violation:
      type: object
      properties:
        cause:
          type: string
          enum:
            - delay
            - lead_time
            - load
            - max_tasks
            - skills
            - precedence
            - missing_break
            - max_travel_time
            - max_distance
            - max_load
        duration:
          type: integer
    Step:
      type: object
      properties:
        type:
          type: string
          enum:
            - start
            - job
            - pickup
            - delivery
            - break
            - end
        id:
          type: integer
          description: Task id for job/pickup/delivery/break steps.
        arrival:
          type: integer
          description: Arrival time (same clock as input).
        duration:
          type: integer
          description: Cumulated travel time in seconds.
        setup:
          type: integer
        service:
          type: integer
        waiting_time:
          type: integer
        distance:
          type: integer
          description: Cumulated distance in meters (when requested).
        location:
          type: array
          items:
            type: number
          description: '[lng, lat].'
        load:
          type: array
          items:
            type: integer
          description: Vehicle load after this step.
        description:
          type: string
        violations:
          type: array
          items:
            $ref: '#/components/schemas/Violation'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key created in the JustRouting dashboard.

````