Routific PDP API

openapi: 3.2.0
info:
  title: Routific Route Optimization PDP API
  description: 'Routific''s Route Optimization API solves the vehicle routing problem (VRP)

    and the pickup-and-delivery problem (PDP) for last-mile delivery fleets.'
  version: '1.11'
  contact:
    name: Routific Support
    email: support@routific.com
    url: https://docs.routific.com
  termsOfService: https://routific.com/terms
  license:
    name: Routific Terms of Service
    url: https://routific.com/terms
  x-logo:
    url: https://routific.com/favicon.ico
servers:
- url: https://api.routific.com
  description: Production Server
security:
- BearerAuth: []
tags:
- name: PDP
  description: Pickup and Delivery Problem — paired pickup/dropoff routing.
paths:
  /v1/pdp-long:
    post:
      summary: Solve Pickup And Delivery Problem (Async)
      description: 'Submit a pickup-and-delivery routing problem for asynchronous processing.

        Each visit pairs a pickup and a dropoff location with their own

        time-windows and durations. Returns a `job_id` immediately.'
      operationId: solvePdpLong
      tags:
      - PDP
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PdpRequest'
      responses:
        '202':
          description: Job accepted for asynchronous processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobAccepted'
        '400':
          $ref: '#/components/responses/InputError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    JobAccepted:
      type: object
      required:
      - job_id
      properties:
        job_id:
          type: string
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Routific error code (e.g. `ERR_DRIVER_NOT_SAME_REGION`).
        message:
          type: string
          description: Human-readable error message.
    Location:
      type: object
      description: Geocoded address for a visit, pickup, dropoff, or depot.
      required:
      - lat
      - lng
      properties:
        id:
          type: string
          description: Optional location identifier (e.g. `depot`).
        name:
          type: string
          description: Human-readable address.
        lat:
          type: number
          format: double
          description: Latitude in decimal degrees.
        lng:
          type: number
          format: double
          description: Longitude in decimal degrees.
    Visit:
      type: object
      description: A single visit with location, time-window, and service duration.
      required:
      - location
      properties:
        location:
          $ref: '#/components/schemas/Location'
        start:
          type: string
          description: Earliest time the visit can begin (`hh:mm` or UNIX seconds).
          example: '9:00'
        end:
          type: string
          description: Latest time the visit can begin (`hh:mm` or UNIX seconds).
          example: '12:00'
        duration:
          type: integer
          description: Service duration in minutes.
          minimum: 1
        load:
          oneOf:
          - type: number
          - type: object
            additionalProperties:
              type: number
          description: Load contributed by this visit (single value or per-dimension object).
        priority:
          type: integer
          description: Optional priority level.
        type:
          oneOf:
          - type: string
          - type: number
          - type: array
            items:
              oneOf:
              - type: string
              - type: number
          description: Compatibility type(s) the assigned vehicle must support.
    Vehicle:
      type: object
      description: A single vehicle/driver in the fleet.
      required:
      - start_location
      properties:
        start_location:
          $ref: '#/components/schemas/Location'
        end_location:
          $ref: '#/components/schemas/Location'
        shift_start:
          type: string
          description: Earliest time the driver can begin (`hh:mm` or UNIX seconds).
          example: '8:00'
        shift_end:
          type: string
          description: Latest time the driver must finish (`hh:mm` or UNIX seconds).
          example: '17:00'
        capacity:
          oneOf:
          - type: number
          - type: object
            additionalProperties:
              type: number
          description: Vehicle capacity (single value or per-dimension object).
        min_visits:
          type: integer
          description: Minimum number of visits the vehicle must handle.
        type:
          oneOf:
          - type: string
          - type: number
          - type: array
            items:
              oneOf:
              - type: string
              - type: number
          description: Compatibility type(s) the vehicle supports.
    PickupDeliveryVisit:
      type: object
      description: Paired pickup and dropoff entry for the pickup-and-delivery problem.
      required:
      - pickup
      - dropoff
      properties:
        pickup:
          $ref: '#/components/schemas/Visit'
        dropoff:
          $ref: '#/components/schemas/Visit'
    PdpRequest:
      type: object
      description: Pickup-and-delivery problem request.
      required:
      - visits
      - fleet
      properties:
        visits:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/PickupDeliveryVisit'
        fleet:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Vehicle'
        options:
          $ref: '#/components/schemas/Options'
    Options:
      type: object
      description: Tunable parameters that adjust how the optimization engine runs.
      properties:
        traffic:
          type: string
          enum:
          - faster
          - fast
          - normal
          - slow
          - very slow
          default: faster
          description: Traffic simulation level.
        min_visits_per_vehicle:
          type: integer
          minimum: 1
          description: Minimum number of visits per vehicle.
        balance:
          type: boolean
          description: Keep variance across driver shift times as small as possible.
        visit_balance_coefficient:
          type: number
          minimum: 0
          maximum: 1
          description: Trade off route balance vs efficiency (0.0 = efficient, 1.0 = balanced). Available on `/vrp-long` v1.10+.
        min_vehicles:
          type: boolean
          default: false
          description: Minimize the number of vehicles used.
        shortest_distance:
          type: boolean
          default: false
          description: Optimize for shortest distance rather than total driving time.
        squash_durations:
          type: integer
          minimum: 1
          description: Squash subsequent visit durations at the same address to this many minutes.
        max_vehicle_overtime:
          type: integer
          minimum: 0
          description: Maximum minutes a driver is allowed to work overtime.
        max_visit_lateness:
          type: integer
          minimum: 0
          description: Maximum minutes a stop is allowed to be late.
        polylines:
          type: boolean
          default: false
          description: Return encoded polylines and per-stop distances.
        avoid_tolls:
          type: boolean
          default: false
          description: Avoid toll roads when calculating routes.
        geocoder:
          type: string
          enum:
          - google
          - here
          default: google
          description: Geocoding provider for address strings.
  responses:
    RateLimited:
      description: Daily request limit exceeded or problem size larger than account limits.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InputError:
      description: Input error — see the error message and code for details.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Routific issues per-account JWT tokens. Send as

        `Authorization: bearer <token>`.

        '