API docs by Redocly

Optibus Operations API (2.3.6)

Download OpenAPI specification:

API Support: api_support@optibus.com License: Optibus Ltd, All rights reserved

Welcome to the Optibus Operations API documentation!

Optibus Operations is a cloud-based software solution that enables public transport providers to optimize their operations, planning, and scheduling. Our API provides programmatic access to Optibus Operations' functionality, allowing you to integrate it with your own applications and systems.

Authentication

The Optibus Operations API requires authentication via a stable API_KEY sent in the HTTP request Authorization header in the form of Authorization: API_KEY. Additionally requests against our API expect the X-Optibus-Api-Client header to be set using your ACCOUNT_NAME.

If you are considering programmatic access the Optibus Operations platform, please contact your Optibus Customer Success Manager who can provide the API_KEY and ACCOUNT_NAME above, as well as your account-specific BASE_URL for the API endpoints documented below.

Example:

CURL -H "Authorization:API_KEY" -H 'X-Optibus-Api-Client: API_USER' https://BASE_URL/driver

Versioning

We may in the future make changes to the Optibus Operations API described on this page. This could be to fix bugs, enhance the richness of information made available in existing endpoints, or to introduce new API functionality via new endpoints.

The Optibus Operations team treats API changes in the following way:

  • we follow Semantic Versioning for the version number of the overall API as documented on this page. Individual endpoints may be provided with versions indicated as prefix such as /v{version}/{endpoint}. These endpoint specific numbers may lag behind the major version of the overall API, but will never exceed it.
  • we will NOT change existing API endpoints in a breaking way suddently. Breaking changes in this sense would be to
    • remove previously documented endpoints
    • remove previously documented properties in responses
    • change the type of documented properties in responses (e.g. number to string, or YYYY-MM-DD string to proper ISOtime string)
    • remove or change documented request parameters for endpoints
    • add new required request parameters to existing endpoints
  • we MAY without considering this a breaking change
    • add additional properties to response objects
    • add additional optional request parameters (e.g. new filtering options)
    • add new endpoints

In case we do introduce breaking changes to existing endpoints, this will happen in the following way:

  • we will add a new version of the affected endpoint, prepended with a version prefix with an increased version number. E.g. if we would make a breaking change to {baseURL}/v1/driver, we would introduce a new endpoint {baseURL}/v2/driver with adjusted behavior
  • may deprecate the old endpoint. We will wait at least 3 months after announcing such a change on this page before shutting down the deprecated endpoint
  • may consider the announcement of deprecation of an endpoint as a major change to the overall API version (as indicated in the title of this document) and increase the version number accordingly

Preferences

GetHolidays

Returns the configured holidays (as in bank holidays). This is distinct from individual driver absences. If startDate and endDate are provided, the response will include only holidays within that date range. If neither is provided, all configured holidays are returned.

Important Notes:

  • Both startDate and endDate must be provided together.
  • Dates are expected in the format YYYY-MM-DD.
Authorizations:
api_key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Regions

GetRegions

Returns the configured organizational Regions including the corresponding Units for each Region.

Authorizations:
api_key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Drivers

GetDriversInfo

Returns the driver information, with filters.

Authorizations:
api_key
query Parameters
driversIds
Array of strings (UUID)
  • Returns the driver information for the given driver IDs
date
string <date> (StringifyDate)
  • Returns the attributes information for the given date

Responses

Response samples

Content type
application/json
[
  • {
    }
]

GetDriverGroupsInfo

Returns the information for driver groups, with filters.

Authorizations:
api_key
query Parameters
depotsIds
Array of strings (UUID)
  • Returns the information for the given depot IDs

Responses

Response samples

Content type
application/json
[
  • {
    }
]

PostDrivers

Adds or updates a specific driver

Authorizations:
api_key
Request Body schema: application/json
required
Array
driverType
string
driverUnion
string
driverGrade
string
attributes
object

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{ }

GetDriversSigningDeviations

Calculate the signing deviations for the drivers in the given date range and region. If driverIds is empty, all drivers will be returned Signing deviations are calculated as the difference between the expected and actual signing times, for each sign on or sign off event. Deviation might be either early or late, calculated according to a defined threshold.

Authorizations:
api_key
query Parameters
from
required
string <date> (StringifyDate)

The start of the date range to get the signing deviations from

to
required
string <date> (StringifyDate)

The end of the date range to get the signing deviations from

regionUuid
required
string (DepotId)

The region to get the signing deviations from

driverIds
Array of strings (DriverId)

The driver IDs for which to get the signing deviations. if empty all drivers will be returned

Responses

Response samples

Content type
application/json
{
  • "property1": {
    },
  • "property2": {
    }
}

GetDriversDepotPeriods

Returns the information about the drivers depot periods by driver ID.

Authorizations:
api_key
query Parameters
driver
Array of strings (UUID)
  • Returns the depot periods for the given driver IDs

Responses

Response samples

Content type
application/json
{
  • "property1": [
    ],
  • "property2": [
    ]
}

GetDriversSigningDeviations_old Deprecated

This route is deprecated, please use /v1/drivers/signing-deviations instead

Calculate the signing deviations for the drivers in the given date range and region. If driverIds is empty, all drivers will be returned Signing deviations are calculated as the difference between the expected and actual signing times, for each sign on or sign off event. Deviation might be either early or late, calculated according to a defined threshold.

Authorizations:
api_key
query Parameters
from
required
string <date> (StringifyDate)

The start of the date range to get the signing deviations from

to
required
string <date> (StringifyDate)

The end of the date range to get the signing deviations from

regionUuid
required
string (DepotId)

The region to get the signing deviations from

driverIds
Array of strings (DriverId)

The driver IDs for which to get the signing deviations. if empty all drivers will be returned

Responses

Response samples

Content type
application/json
{
  • "property1": {
    },
  • "property2": {
    }
}

GetDriverAttributes

Returns the driver attributes.

Authorizations:
api_key
query Parameters
driverIds
Array of strings (DriverId)
  • Returns the driver attributes by driver ID
from
string
  • Returns the attributes for a specified date range (both from and to are required)
to
string
  • Returns the attributes for a specified date range (both from and to are required)

Responses

Response samples

Content type
application/json
{
  • "attributes": {
    },
  • "attributeMap": {
    }
}

GetAbsenceByDrivers

Returns absences of drivers.

  • this does include absences configured for specific Driver Groups
  • this does not include Public Holidays as configured in preferences
Authorizations:
api_key
query Parameters
driver
Array of strings (UUID)
  • Returns the absences of drivers by driver ID
from
string <date> (StringifyDate)
  • Returns the absences for a specified date range (both from and to are required)
to
string <date> (StringifyDate)
  • Returns the absences for a specified date range (both from and to are required)

Responses

Response samples

Content type
application/json
{
  • "property1": [
    ],
  • "property2": [
    ]
}

PostDriverAbsences

Add the absences from the body into operations. Notice that absenceId need to be unique (in the entire system), this allow modification to existing absences when using the same id

Authorizations:
api_key
Request Body schema: application/json
required
Array
endTimeNextDay
boolean
startTimeNextDay
boolean

for partial absence

endTime
integer <int32> (MinutesFromMidnightTime)
endDate
string <date> (StringifyDate)

Stringified ISO8601 date in the form of YYYY-MM-DD, for example 2017-07-21

startTime
integer <int32> (MinutesFromMidnightTime)
startDate
required
string <date> (StringifyDate)

Stringified ISO8601 date in the form of YYYY-MM-DD, for example 2017-07-21

metadata
object

Additional data about the absence

note
string

The note provided by the user

absenceCode
required
string

The absence code provided by the user

absenceId
required
string (UUID)

Stringified UUID for a resource.

driver
required
string (UUID)

Stringified UUID for a resource.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{ }

Vehicles

GetVehiclesInfo

Returns the information for vehicles, with filters.

Authorizations:
api_key
query Parameters
vehicleIds
Array of strings (UUID)
  • Returns the information for the given vehicles by vehicle ID
depotIds
Array of strings (UUID)
  • Returns the information for vehicles that are that are loaned or assigned to the given depot IDs, on the given date or today if date is not provided
date
string <date> (StringifyDate)
  • Returns the attributes information for the given date

Responses

Response samples

Content type
application/json
[
  • {
    }
]

GetVehiclesDepotPeriods

Returns the information about the vehicles depot periods by vehicle ID.

Authorizations:
api_key
query Parameters
vehicleId
Array of strings
  • Returns the depot periods for the given vehicle IDs

Responses

Response samples

Content type
application/json
{
  • "property1": [
    ],
  • "property2": [
    ]
}

GetVehicleAttributes

Returns the vehicle attributes.

Authorizations:
api_key
query Parameters
vehicleIds
Array of strings (VehicleId)
  • Returns the vehicle attributes by vehicle ID
from
string
  • Returns the attributes for a specified date range (both from and to are required)
to
string
  • Returns the attributes for a specified date range (both from and to are required)

Responses

Response samples

Content type
application/json
{
  • "attributes": {
    },
  • "attributeMap": {
    }
}

Roster

A roster describes the daily operator runs grouped into packages of (repeating) weekly work assignments.

GetRoster

Returns the roster information by roster ID.

Authorizations:
api_key
query Parameters
rosterId
required
string (UUID)
  • The roster ID to retrieve.
operationalDay
string <date> (StringifyDate)
  • Get the roster information for a specific date

Responses

Response samples

Content type
application/json
{
  • "stops": [
    ],
  • "assignmentsInfo": [
    ],
  • "lineInfo": [
    ],
  • "events": [
    ],
  • "blocks": [
    ],
  • "tasks": [
    ],
  • "rosterDataInfo": {
    }
}

Operational Plan

GetDepotOperationalPlan

WARNING: This is deprecated - you should use /v2/operational-plan described below. This API will not be supported beyond 2024-06-30. Returns the daily operational plans for a specified date range and a specific depot.

Authorizations:
api_key
path Parameters
depotId
required
string
  • Returns the daily operational plans for this depot ID
query Parameters
from
required
string <date> (StringifyDate)
  • Returns the operational plans from this date (both from and to are required)
to
required
string <date> (StringifyDate)
  • Returns the daily operational plans to this date (both from and to are required)
driversIds
string
  • Returns the daily operational plans for the filtered driver IDs (when this filter is used, the response won't include unassigned tasks)
vehicleIds
string
  • Returns the daily operational plans for the filtered vehicle IDs (when this filter is used, the response won't include unassigned blocks)
includeStops
string
  • When true, the response will include a full stop list on each trip (requests may take a long time or even time out)
assignedOnly
string
  • When true, the response will only contain tasks that have drivers assigned to them
includeUnassigned
string
  • In conjunction with supplying driver ids, When true return unassigned tasks as well as assigned tasks according to the driver filter.
fetchPlannedAssignmentsProperties
boolean
  • When true, the response will include the properties of the plannedAssignments

Responses

Response samples

Content type
application/json
{
  • "vehicles": [
    ],
  • "drivers": [
    ],
  • "assignments": [
    ],
  • "blocks": [
    ],
  • "tasks": [
    ]
}

GetOperationalPlan

WARNING: This is deprecated - you should use /v2/operational-plan described below. This API will not be supported beyond 2024-06-30. Returns the daily operational plans for a specified date range for every depot.

Authorizations:
api_key
query Parameters
from
required
string <date> (StringifyDate)
  • Returns the operational plans from this date (both from and to are required)
to
required
string <date> (StringifyDate)
  • Returns the daily operational plans to this date (both from and to are required)

Responses

Response samples

Content type
application/json
{
  • "depots": {
    }
}

GetOperationalPlanV2

This API provides access to the Operational Plan of a public transport organization managed via Optibus Operations for a specified date range. It returns the daily operational plans grouped by depot. Each depot has it's own operational plan. Each item in the response represents one of the requested depots. If no specific depots are requested then all depots are returned.

Brief overview of the returned concepts for the operational plan of a depot:

  • Vehicles: This entity represents the buses or transportation units within the fleet, equipped with various operational capabilities and passenger amenities. Attributes cover technological features (e.g., videoSurveillance, passengerCounting), accessibility options (e.g. ramp), and ecological considerations (e.g. ecological). Each vehicle is uniquely identified, allowing for precise tracking and operational assignments.

  • Drivers: Individuals responsible for operating the vehicles. The entity stores personal and operational information, including a unique identifier (id, uuid), name attributes (firstName, lastName, middleName), and an archived status indicating whether the driver is currently active.

  • Assignments: A complex record of operations for each calendar date. Each assignment links vehicles and drivers with their respective operational blocks and tasks. Where assignments have not been allocated vehicles and/or drivers these fields will be empty - an assignment can be "uncovered" so to say.

  • Blocks: Blocks represent a sequence of trips or duties assigned to a vehicle, encapsulating its journey from the start to the end of service, including depot movements. Blocks are crucial for organizing daily operations and are characterized by attributes like disabled and type, indicating their status and category.

  • Tasks: Operational activities detailed within the system, signifying specific duties or responsibilities. Tasks are associated with blocks and assignments, indicating the scheduled activities for vehicles and drivers. Attributes within tasks include type, startTime, endTime, and related operational details, providing a granular view of daily duties.

Notes:

  • The RosterDutyEventReference is an instance that occurs within the "blocks" section, serving as a pointer to the "tasks" section. Each block comprises an array of events, each with a dutyId, an eventId, and an originRosterId. Within the "tasks" array, the same event can be identified by examining the Id field of the task, which will match the dutyId specified in the block's section. When referencing the eventId in the block's array, it directs to the "events" array, where its uuId corresponds to the eventId previously identified in the block's array. This event contains information such as start time, end time, and other relevant details. In rare cases, an event may be designated as vehicle-only, such as a recharge event. In these instances, it won't have a dutyId or eventId, and instead, the event's information will be directly displayed within the block section itself.
  • Regarding deadhead event data, each event is categorized by its own event type. Specifically, deadhead events encompass three distinct sub-types: OnScheduleEventsTypes.Deadhead , OtherEventTypes.PullIn and OtherEventTypes.PullOut A pull-in signifies the idle trip from the service to the depot, while a pull-out denotes the idle trip from the depot to the service. A standard deadhead represents an idle trip between these two services. Apart from the event type, all other parameters and the amount of data remain consistent. To distinguish between a pull-in, pull-out, or plain deadhead, it's necessary to inspect the subtype information associated with the event.
Authorizations:
api_key
query Parameters
fromDate
required
string <date> (StringifyDate)
  • Returns the operational plans from this date (both fromDate and toDate are required). Date format is YYYY-MM-DD
toDate
required
string <date> (StringifyDate)
  • Returns the daily operational plans to this date (both fromDate and toDate are required). Date format is YYYY-MM-DD
depotUuids
string
Example: depotUuids=72999313-c6d3-44a3-9e64-a8cbce779ed7,e09cc074-b949-4d39-97b5-d2fa5eb1cdc5
  • When specified, the response will contain only these depots. When including more than one depot the request param can be a comma separated list (eg depotUuids=A,B) or you can use several request params (eg depotUuids=A?depotUuids=B)"
driverUuids
string
  • When specified, the response wil include only assignments for these drivers. When including more than one driver the request param can be a comma separated list (eg driverUuids=A,B) or you can use several request params (eg driverUuids=A?driverUuids=B)
includeStops
string
  • When true, the response will include a full stop list on each trip. Otherwise only origin and destination are included in request. (Usage may cause requests to take a long time)
includeUnassigned
string
  • In conjunction with supplying driver ids, When true return unassigned tasks as well as assigned tasks according to the driver filter.
fetchPlannedAssignmentsProperties
boolean
  • When true, the response will include the properties of the plannedAssignments

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Tasks

GetCalendarInfo

Returns the Daily and Weekly tasks for a specified date range, with filters. Responds with 302 redirect when payload is too big. OriginalDriverId refers to the driver that was assigned to the task in the plan page

Authorizations:
api_key
path Parameters
depotId
required
string (UUID)
  • The depot to get the tasks from
query Parameters
from
required
string <date> (StringifyDate)
  • The start of the date range to return the tasks from
to
required
string <date> (StringifyDate)
  • The end of the date range to return the tasks from
plan
Array of strings (UUID)
  • Returns tasks from the given plans
group
Array of strings
  • Returns tasks from deployed plans for the given groups
type
Array of strings (TaskType)
Items Enum: "duty" "day_off" "standby" "spare" "custom"
  • Returns tasks from the given types
assignedOnly
boolean
  • Returns tasks that are either assigned or unassigned (depending on the input)
includeStops
boolean
  • Returns the stops of tasks (false by default)
driversIds
Array of strings (UUID)
  • Returns the assignments of filtered driver

Responses

Response samples

Content type
application/json
{
  • "calendarVehicleAssignments": [
    ],
  • "blocks": [
    ],
  • "tasks": [
    ],
  • "DailyTasks": [
    ],
  • "deployedPlans": [
    ],
  • "depotId": "string"
}

Stops

GetStops

Returns the stops for all depots of a user domain.

Authorizations:
api_key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

workEntities

GetWorkEntities

Retrieves workEntities values for depots within a specified date range and for specified driver IDs or by depotId. There is a limit of 204k work-entities calculation per request to avoid timeouts. This limit enables, for example, a calculation of 100 drivers for 30 days with 100 daily work-entities defined. In case the limit is exceeded, a 413 error code will be returned, together with the allowed amount of drivers for the existing configuration.

Authorizations:
api_key
query Parameters
depotId
string (DepotId)
  • Optional. The ID of a specific depot for which workEntities are to be retrieved.
driverIds
Array of strings (DriverUuid)
  • Optional. An array of driver IDs for whom workEntities are to be retrieved.
startDate
string <date> (StringifyDate)
  • The start date of the workEntities period.
endDate
string <date> (StringifyDate)
  • The end date of the workEntities period.
exportAllEntities
boolean
  • Optional. If true, all workEntities will be exported, regardless of the configuration.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

GetAPICalculationLimit

Fetches the maximum number of drivers allowed per API request of payroll or work-entities for the given dates for a particular client. To prevent timeouts, there is a cap of 204000 work-entity calculations per request. This cap allows, for instance, the calculation of 100 drivers over a 30-day period with 100 daily work-entities specified.

Authorizations:
api_key
query Parameters
startDate
string <date> (StringifyDate)
  • The start date of the workEntities period.
endDate
string <date> (StringifyDate)
  • The end date of the workEntities period.

Responses

Response samples

Content type
application/json
{
  • "limit": 0.1
}

Payroll

GetPayroll

Retrieves payroll values for depots within a specified date range and for specified driver IDs or by depotId. There is a limit of 204k work-entities calculation per request to avoid timeouts. This limit enables, for example, a calculation of 100 drivers for 30 days with 100 daily work-entities defined. In case the limit is exceeded, a 413 error code will be returned, together with the allowed amount of drivers for the existing configuration.

This endpoint is only available if the Use Payroll V2 feature flag is enabled and work-entity as well as payroll rules have been properly setup.

Authorizations:
api_key
query Parameters
depotId
string
  • Optional. The ID of a specific depot for which payroll is to be retrieved.
driverIds
Array of strings
  • Optional. An array of driver IDs for whom payroll is to be retrieved.
startDate
string <date> (StringifyDate)
  • The start date of the payroll period
endDate
string <date> (StringifyDate)
  • The end date of the payroll period
paycodes
Array of strings (CodeId)
  • Optional. An array of paycodes to filter the payroll values by. If not provided, all paycodes are returned.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Private Hires

PostPrivateHireOrder

Creation of a private hire order with one or more trips

This endpoint operates on eventual consistency. This means the private hire order is validated and enqueued for processing which is confirmed by a http 202 status response. The actual processing happens asynchronously and typically takes a few seconds. To verify the order was successfully added, use the GetPrivateHireOrder endpoint below specifying the the orderId you used in this request.

Private hire orders and trips should be unique by orderId and taskId respectively in the system.

Once the order is created, resources to fulfill the trips, such as drivers and vehicles, can be only assigned through the Optibus OPS platform.

An order can be created directly with a status 'confirmed' or the status of an order can be updated using the endpoint PATCH /private_hires/order/{orderId}. By default on creation, if there's no status being set, the order is being consider virtually as pending.

Multi-day trips:

Multi-day trips must be divided into individual trips per operational day. Trips can commence as early as 00:00 and extend up to a maximum of 36:00 local time, meaning trips can conclude as late as 12:00 noon the following day. Use cases that require trips to start and finish in different time zones are currently not supported.

Authorizations:
api_key
Request Body schema: application/json
required
orderStatus
string
Value: "confirmed"
orderId
required
string (OrderIdString) [ 1 .. 255 ] characters

External identifier of a private hire order that should be unique within the system

required
Array of objects (PrivateHireTask)

Representation of trips within a private hire order

Array
noVehicleNeeded
boolean

In case there's no need to allocate a vehicle.

note
string

Additional information about the trip that might be relevant for dispatchers. Information in the note can be used as a simplistic way of specifying vehicle requirements until it's being implemented. Expects plaintext without additional formatting such as html or markdown.

labelCodes
Array of strings

A collection of label codes, where each label specifies a particular characteristic of the private hire trip. For example, a label might indicate that the trip crosses a national border. It must exist in OPS Preferences

required
Array of objects (PrivateHireAPIEvent)

Array of sub-trips containing time and geographical information about their start and end.

Array
distance
number <double>

Estimated distance in meters for the sub-trip that the vehicle will have to travel.

note
string

Additional information relating to the sub-trip that could be relevant for the dispatchers.

labelCodes
Array of strings

A collection of label codes where each label specifies a particular characteristic of the private hire event.

required
object (PrivateHireLocation)
required
object (PrivateHireLocation)
required
ISO8601Time (string) or HourMinuteDuration (string) (TimeHHmmOrISO8601)
required
ISO8601Time (string) or HourMinuteDuration (string) (TimeHHmmOrISO8601)
type
required
string
Value: "private_hire"
date
required
string

Operational date when the trip is meant to start, in format "YYYY-MM-dd".

depotName
required
string

Name of the depot the trip should be/is allocated to.

taskId
required
string (TaskDisplayIdString) [ 1 .. 1000 ] characters

External identifier of a private hire trip that should be unique within the system and that will be used internally in Optibus as the display ID.

Responses

Request samples

Content type
application/json
{
  • "orderStatus": "confirmed",
  • "orderId": "string",
  • "privateHires": [
    ]
}

Response samples

Content type
application/json
Example
null

GetPrivateHireOrder

Get information about a private hire order and its trips

As details of a private hire order and its trips can be modified in the OPS platform, external parties can use this endpoint to get the current state and details of a specific order, its trips, as well as the vehicle and driver resources associated.

Getting updates

Currently there's no support of a pushing mechanism in order to notify API consumers when something changes in resources that belong to a private hire order. As an alternative, until the push mechanism is implemented, this endpoint can be used following a polling strategy in order to identify changes that happen in a private hire order and the trips that belong to it.

Authorizations:
api_key
path Parameters
orderId
required
string

External identifier of a private hire order that should be unique within the system

Responses

Response samples

Content type
application/json
Example
{
  • "privateHires": [
    ],
  • "cancelledAt": "2019-08-24",
  • "confirmedAt": "2019-08-24",
  • "orderId": "string"
}

PatchPrivateHireOrder

Update a private hire order status

  • confirmed: status to determine that the order has been paid by the hiring entity. In the OPS Optibus platform, when a trip has any driver or vehicle associated to a confirmed order, a warning message will be displayed to inform the dispatchers about this fact.
  • cancelled: status to cancel the order, freeing up resources associated to trips belonging to the order, such as drivers and vehicles.
Authorizations:
api_key
path Parameters
orderId
required
string

External identifier of a private hire order that should be unique within the system

Request Body schema: application/json
required
orderStatus
required
string (SupportedOrderStatus)
Enum: "confirmed" "cancelled"

Private hire order status.

  • confirmed: the order is meant to have been paid by the hiring entity. In the OPS Optibus platform, when a trip has any driver or vehicle associated, a warning message will be displayed to the inform the dispatchers about this fact.
  • cancelled: all trips of a private hire order have been cancelled and the resources associated to it, such as drivers and vehicles, have been freed up.

Responses

Request samples

Content type
application/json
{
  • "orderStatus": "confirmed"
}

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

PatchPrivateHireOrderTrips

Update or cancel private hire tasks of an order

One or more private hire tasks can be updated/cancelled in the same request. Only send the private hire tasks that are meant to be updated or cancel, if tasks don't need to be modified, refrain to include them in the request. Updates for a subset of private hire tasks won't be supported, the request should be successful for all the intended private hire trips included in the request.

Splitting tasks in Optibus OPS platform

The private hire attribute taskId is what's being used to find the private hire trip to be updated or cancelled.

Dispatchers can split/cut these trips (a.k.a. driver duties), creating 2 trips or more. This action causes as a side effect, the renaming of the original value for the attribute taskId. As an example, if an original private hire trip had the attribute taskId as the value task-display-id, after a dispatcher splits the trip in the OPS Optibus platform, it will create 2 trips whose taskIds values will be task-display-id (1/2) and task-display-id (2/2).

Supported update use cases for private hire trips:

  • Cancellation
  • Events addition or removal
  • Modification of startTime or/and endTime in an event (sub-trip)
  • Update of the date

Note: At this moment, all the supported modifications will free up all the vehicles and drivers associated to the private hire trip, if there were any, given that it will cause a risk to violate regulation compliance rules, which are currently computed in the Optibus OPS web application.

If there's a modification that's not supported, the response status code returned will be a 400 malformed request, with an informative error that will point out that the change is not supported.

Authorizations:
api_key
path Parameters
orderId
required
string

External identifier of a private hire order that should be unique within the system

Request Body schema: application/json
required
required
Array of PrivateHireTask (object) or PatchPrivateHireCancellation (object)
Array
Any of
noVehicleNeeded
boolean

In case there's no need to allocate a vehicle.

note
string

Additional information about the trip that might be relevant for dispatchers. Information in the note can be used as a simplistic way of specifying vehicle requirements until it's being implemented. Expects plaintext without additional formatting such as html or markdown.

labelCodes
Array of strings

A collection of label codes, where each label specifies a particular characteristic of the private hire trip. For example, a label might indicate that the trip crosses a national border. It must exist in OPS Preferences

required
Array of objects (PrivateHireAPIEvent)

Array of sub-trips containing time and geographical information about their start and end.

Array
distance
number <double>

Estimated distance in meters for the sub-trip that the vehicle will have to travel.

note
string

Additional information relating to the sub-trip that could be relevant for the dispatchers.

labelCodes
Array of strings

A collection of label codes where each label specifies a particular characteristic of the private hire event.

required
object (PrivateHireLocation)
required
object (PrivateHireLocation)
required
ISO8601Time (string) or HourMinuteDuration (string) (TimeHHmmOrISO8601)
required
ISO8601Time (string) or HourMinuteDuration (string) (TimeHHmmOrISO8601)
type
required
string
Value: "private_hire"
date
required
string

Operational date when the trip is meant to start, in format "YYYY-MM-dd".

depotName
required
string

Name of the depot the trip should be/is allocated to.

taskId
required
string (TaskDisplayIdString) [ 1 .. 1000 ] characters

External identifier of a private hire trip that should be unique within the system and that will be used internally in Optibus as the display ID.

Responses

Request samples

Content type
application/json
{
  • "privateHires": [
    ]
}

Response samples

Content type
application/json
Example
null

Driver App Notifications

GetPublicKey

Returns the public key that can be used to verify the payloads attached to URLs opened via a custom action attached to a notification received in the Optibus Driver App.

No authentication is required to access this endpoint.

Responses

Response samples

Content type
application/json
{
  • "publicKeyType": "string",
  • "publicKey": "string"
}

Real Time Stream

RealTimeStreamPost

Real-time operation stream from Optibus OPS system

The Optibus OPS real-time stream delivers changes in entities triggered by user in the OPS platform to subscribers via webhook requests.

ODS format based

Actions supported will be sent in requests to the subscribers, containing all the entities that were changed, such as runs, run_assignments, run_events, blocks and block_assignments with a format that has been inspired by ODS, following the same terminology for the name of attributes and entities, despite there's additional information to enrich the data streamed.

ODS format based

The subscriber will need to provide a URL, the days previous and next days they want to subscribe to receive these events and the operations.

Auth

The subscriber will receive a secret token that will be used to validate the request comes from Optibus as a trusted source. Before sending the webhook, we generate an HMAC signature using the same secret key for the request body, then include the result in a header X-HMAC-SIGNATURE. The subscriber will need to validates the request by generating the signature following the same process on their side and then comparing it to the X-HMAC-SIGNATURE header. If there's a match, the request should be accepted; otherwise, it should be rejected as it might come from an unauthorized source.

To generate a signature is a simple as:

 import crypto from "crypto";
 return crypto
   .createHmac("sha256", subscriber.secret)
   .update(Buffer.from(JSON.stringify(realTimeOperation)).toString("base64"))
   .digest("base64");

Sequential processing of events

It's important that real-time operations that belong to an aggregate_id, value that's always included in every request payload, are sequentially processed by the consumers in order to guarantee correctness, given that operations could depend on each and if not processed chronologically in the order they were triggered, it could lead to data inconsistencies.

aggregate_id represents a funnel for all actions in a specific operational region and parallelism across different aggregate_id should be considered by the subscribers.

Retry mechanism

In case the subscriber fails to process the request or the server where the endpoint to receive these events is down, not returning a 2XX code, the request will be sent again, following an exponential backoff mechanism. Real-time operations for an aggregate_id will have to be executed sequentially and therefore, if a request fails to be processed, until is either successful or stops retrying, no new operations will be streamed for that aggregate_id.

Request Body schema: application/json
required
required
Array of objects (OperationalAction)

List of operational actions triggered by a user in OPS platform. A single action triggered by a user has the potential of creating multiple operational actions. A user action could cause multiple operational action types for an operational day, such as [example] or actions for multiple operational days, such as adding a driver absence that could unassign the driver along multiple days.

Array
required
Array of objects (EntityChanges)

The payload containing the detailed operational creating, deleting or updating entities such as blocks, block_assignments, runs, run_assignments and run_events.

Array
required
Array of objects (RunEventODS)
required
Array of objects (RunAssignmentODS)
required
Array of objects (RunODS)
required
Array of objects (BlockAssignmentODS)
required
Array of objects (BlockODS)
operational_date
required
string

The date of the operation in "YYYY-MM-DD" format

action_type
required
string (RealTimeOperationType)
Enum: "cut_duty" "assign_duty" "unassign_duty" "swap_duty_assignment" "assign_block" "unassign_block"
customer
required
string

The customer or agency the operation applies to

aggregate_id
required
string

Aggregate identifier, typically to group related operations Sequentiality in processing real-time events for an aggregateId should be guaranteed by the provider. Parallelism in the processing of events could be performed across events belonging to different aggregateId.

region_id
required
string

Identifier of the region the operation pertains to

created_at
required
string

Timestamp of the operation

id
required
string

UUID for the real-time operation

Responses

Request samples

Content type
application/json
{
  • "id": "90cb367f-3680-48c2-93a2-b162cb11ce9a",
  • "customer": "superbus",
  • "created_at": "2024-10-09T16:19:01.300Z",
  • "aggregate_id": "operational-calendar-0d277b74-ab79-493f-8f1d-ec307420868d",
  • "region_id": "0d277b74-ab79-493f-8f1d-ec307420868d",
  • "operational_actions": [
    ]
}

Changelog

Below, we use the following icons to indicate the type of changes:

  • 🐞 Bugfix: correcting API behavior to what was previously indicated. No breaking change
  • 🌟 Addition: New properties, request filtering capabilities, or endpoints. No breaking change
  • 💥 Breaking change. This would typically result in us adding a new version of an endpoint prepended with an increased version prefix such as /v2/endpointName to /v3/endpointName. See section Versioning.

v2.3.7 - 2025-03-18 🌟

  • 🌟 POST /v1/drivers: add support for custom attributes

v2.3.6 - 2024-10-20 🌟🐞

  • 🌟 new /v1/preferences/holidays endpoint added

v2.3.5 - 2024-09-16 🌟🐞

  • Apidoc improvements
    • 🐞 fix wrongly described endpoint of /v1/regions (was incorrectly specified as /region in v2.3.4)

v2.3.4 - 2024-08-27 🌟

  • 🌟 Added new endpoint /v1/regions

v2.3.3 - 2024-08-26 🌟

  • 🌟 /group endpoint now returns regionUuid field, which is an alias of deprecated depot field
  • 🌟 /group endpoint now returns additional regionName field

v2.3.2 - 2024-07-28 🌟

🌟 Added the optibusTimeplanId field to the optibus Ids object within tasks and blocks

v2.3.1 - 2024-07-15 🌟

Op Units in assignments - we are introducing the op unit in the operational plan. in V1 and V2, the naming of depots remains unchanged although for some customers this would be considered a region. Within these customers, the lower level division is called an operational unit (opUnit). In future versions, "depots" would be renamed to "region", and units would be renamed to "depot".

  • 🌟 Addition: Op Units in the operational calendar assignment
    • in both V1/V2, Op Unit Uuid now appears in the properties of each assignment
    • in V2 only, the full list of op units is available at the region level

v2.3.0 - 2024-07-03 🌟

Introducing support for private hire endpoints

  • POST /private_hires/order: Creation of the private hire order and trips associated to it.
  • GET /private_hires/order/{orderId}/info: Retrieval of the private hire order, the trips associated and the driver/vehicle assignments, besides other useful information.
  • PATCH /private_hires/order/{orderId}: Modification of private hire order status.
  • PATCH /private_hires/order/{orderId}/trips: Modification of trips associated to a private hire order.

v2.2.1 - 2024-07-02 🌟

  • 🌟 Added a new optional parameter 'includeUnassigned' to 'v1/operational-plan' and 'v2/operational-plan'. In conjunction with supplying driver ids, this would instruct the endpoint to return unassigned tasks as well as assigned tasks according to the driver filter.

v2.2.0 - 2024-03-10 🌟

Adjustment to operational-plan endpoints. Additional properties were added, and some additional aliases introduced for a more coherent naming structure. This is intended to ease a transition from the deprecated end point v1/operational-plan to v2/operational-plan (OPS-8538). While there are breaking changes in v2/operational-plan, there are no active users at this endpoint currently yet, so we are treating it as a minor version upgrade from 2.1.0 to 2.2.0

  • 🌟 Additions to v1/operational-plan. On each event:
    • eventId has been added as an alias for the existing id property
    • eventType has been added as an alias for the existing type property
    • noteText has been added
    • reinforcedTripReference has been added to reinforcement events
    • splitTripReference has been added the parts of trips that were split
    • More properties have been typed on eventJsonData, these vary per eventType.
      • blockId has been added as an alias for the existing vehicleId
      • Each event type is now more strongly typed so it should be clearer what properties exist on what events.
  • 💥 Additions and changes to v2/operational-plan. On each event:
    • all v1 changes described above, plus:
    • type has been removed and replaced by eventType
    • id has been removed and replaced by uuid
    • eventJsonData has been removed and all properties that were inside this object are now on the event level

v2.1.0 - 2024-02-12 🌟

In v1/operational-plan and v2/operational-plan

  • Additional source ids for tasks and blocks added Optibus IDs to tasks and blocks (OPS-8855)

    • The properties are contained within a new object called optibusIds on each task and block as follows export type OptibusIds = { optibusRosterId: string; optibusRosterDatasetId: string; optibusScheduleId: string; }; It is important to document that tasks and blocks and days off that have been created inside Ops will NOT have these IDs. Therefore, we are adding additional properties called: source and wasModifiedInOperations
      • If the source is “scheduling“:
        • optibusIds will exist
        • wasModifiedInOperations will exist. True, if the task has been modified in anyway (excluding cancellations) else, False.
      • If the source is “operations“:
        • optibusIds will NOT exist
        • wasModifiedInOperations will NOT exist.

  • Adding dutyType to certain tasks added dutyType to the task, where dutyType is a property that comes from Rosters/Schedules imported into Optibus Operations from Optibus Planning/Scheduling/Rostering (OPS-8877)

v2.0.0 - 2024-01-29 💥

Changes in this release do not contain breaking changes to existing endpoints, but we are deprecating endpoint v1/operational-plan by 2024-06-30 in favor of v2/operational-plan, therefore marking this as a major release, increasing overall API version from 1.3.0 to 2.0.0:

  • 🐞 A bug was fixed where some tasks were not getting filtered when using the driver filter (OPS-8280)
  • 💥 New v2/operational-plan endpoint. (OPS-6125) which contains a number of breaking changes if switching from v1/operational-plan. Note that v1/operational-plan is still available, but will be deprecated by 2024-06-30:
    • 💥 Removed query params: assignedOnly, vehicleIds
    • 💥 depotId is no longer a path parameter, it has been replaced by query param depotUuids which is now a list
    • 💥 driverIds query parameter is now called driverUuids
    • 💥 from query parameter is now called fromDate
    • 💥 to query parameter is now called toDate
    • 💥 Response is now a list where each item is a depot. Each item now has the properties depotUuid and depotName alongside the previous operational plan properties.
    • 💥 Failure to fetch a plan for a depot will fail the whole request.
    • 💥 If one or more of the requested depots is not found then return a 404 and an error which includes the list of missing depots (OPS-8707)
    • 💥 The end point to retrieve a single depot (ie v2/operational-plan/{depotId}) has been removed. Instead their is only the v2/operational-plan endpoint and specific depots can be requested using a depotUuids query parameter on the request.
    • 💥 The block/task summary is removed in v2 (OPS-8757). Therefore:
      • destination.originStop and destination.originDepot are completely removed in v2/operational-plan
      • originStopName, originStopId, originStopLabel, originDepotName, originDepotId and originDepotLabel (and the equivalent for destination) are moved up to the task/block level.
  • Stops Properties
    • 🌟 in v1/operational-plan/{depotId} (and v2/operational-plan), added originStopName, originStopId, originStopLabel, originDepotName, originDepotId and originDepotLabel to the duty and block summary (and the equivalent for destination) (OPS-8539)
last updated: 2025-04-17