17 Appendix - REST endpoints

The following sections list the different RESTful HTTP endpoints available in ODL Live.

17.1 Gps-traces endpoint

Access GPS traces for vehicle in model. A GPS trace defines where a vehicle is (latitude and longitude) at an instant in time. A ‘trace’ event could also be manually created by a user instead of collected by GPS (e.g. if no tracking system is available but a dispatcher knows where a driver is).

17.1.1 Delete all traces for the vehicle

DELETE /models/{modelId}/vehicles/{vehicleId}/gpstraces/

17.1.2 Delete GPS trace from the vehicle

DELETE /models/{modelId}/vehicles/{vehicleId}/gpstraces/{traceId}

17.1.3 Get array of all GPS traces for the vehicle

GET /models/{modelId}/vehicles/{vehicleId}/gpstraces/

Response body JSON object: Array of ODLTracePoint

17.1.4 Get GPS trace by assigned id

GET /models/{modelId}/vehicles/{vehicleId}/gpstraces/{traceId}

Response body JSON object: ODLTracePoint

17.1.5 Put updated version of trace object

PUT /models/{modelId}/vehicles/{vehicleId}/gpstraces/{traceId}

Request body JSON object: ODLTracePoint

Notes: Put should use the id automatically assigned by the optimiser.

17.1.6 Replace all vehicle traces on the vehicle

PUT /models/{modelId}/vehicles/{vehicleId}/gpstraces/

Request body JSON object: Array of ODLTracePoint

17.2 Jobs endpoint

Access jobs in model. Jobs define either a single stop (e.g. ‘service customer’) or two stops (e.g. ‘pickup meal’, ‘deliver meal’). Post jobs to the model when they become known.

17.2.1 Delete all jobs in model

DELETE /models/{modelId}/jobs/

17.2.2 Delete single job

DELETE /models/{modelId}/jobs/{jobId}

17.2.3 Get all jobs in model

GET /models/{modelId}/jobs/

Response body JSON object: Array of ODLJob

17.2.4 Get single job

GET /models/{modelId}/jobs/{jobId}

Response body JSON object: ODLJob

17.2.5 Put all jobs in model

PUT /models/{modelId}/jobs/

Request body JSON object: Array of ODLJob

Notes: Replace all jobs, all existing jobs are deleted

17.2.6 Put single job

PUT /models/{modelId}/jobs/{jobId}

Request body JSON object: ODLJob

Notes: Put an updated version of a pre-existing job or a new job with ids set by the client.

17.3 Models endpoint

Access models. A model contains live jobs (transportation requests) and live vehicles to serve the jobs. A model therefore corresponds to a single geographic area (e.g. city, state, county, country) served by a fleet of vehicles.

17.3.1 Delete model

DELETE /models/{modelId}

17.3.2 Get all model ids

GET /models/ids

Response body JSON object: array

17.3.3 Get model

GET /models/{modelId}

Response body JSON object: ODLModel

17.3.4 Get model configuration

GET /models/{modelId}/config

Response body JSON object: ODLModelConfiguration

17.3.5 Get model data

GET /models/{modelId}/data

Response body JSON object: ODLModelData

17.3.6 Get summary statistics for all models

GET /models/summaries

Response body JSON object: array

17.3.7 Put model

PUT /models/{modelId}

Request body JSON object: ODLModel

Notes: Replaces all existing jobs and vehicles in the model.

17.3.8 Put model configuration

PUT /models/{modelId}/config 

Request body JSON object: ODLModelConfiguration

17.4 Optimiser-state endpoint

Access optimiser state in model. The optimiser state consists of the master plan and other information.

17.4.1 Get current planned vehicle routes

GET /models/{modelId}/optimiserstate/plan

Response body JSON object: ODLOptimiserPlan

Notes: The optimiser plan is the current assignment of stops to vehicles, and their ordering, that the optimiser has planned for future dispatch. Only stops which have not yet been dispatched are included in the optimiser plan as the optimiser plan holds stops which are queued for dispatching in the future. The optimiser will automatically adjust this plan as needs be.

If you want the route geometry fields in the return ODLOptimiserPlan object to be populated you must add a parameter to the URL named geometry. This parameter can take values NO_GEOMETRY, STD, HIGH, RAW which define the required accuracy. For example, for the standard accuracy geometry use https://…/plan?geometry=STD. High accuracy geometry will create a very large JSON and should be avoided. The value geometry=RAW should never be used for anything except testing.

17.4.2 Get job acceptance state

GET /models/{modelId}/optimiserstate/jobacceptance/{jobId}

Response body JSON object: ODLJobAcceptanceState

17.4.3 Get optimiser lock state

GET /models/{modelId}/optimiserstate/locks

Response body JSON object: Array of ODLVehicleLockWithVid

Notes: Get the lock state maintained by the optimiser for individual vehicles.

17.5 Planning-queries endpoint

Access planning queries and their results.

17.5.1 Delete a query result

DELETE /models/{modelId}/queries/results/{queryId}

17.5.2 Delete all query results

DELETE /models/{modelId}/queries/results/

17.5.3 Delete pending queries

DELETE /models/{modelId}/queries/pending/

Notes: Delete all pending queries which are not currently being processed.

17.5.4 Delete single pending query

DELETE /models/{modelId}/queries/pending/{queryId}

Notes: If the query has already started processing it will not be deleted.

17.5.5 Get a pending query

GET /models/{modelId}/queries/pending/{queryId}

Response body JSON object: ODLPlanningQuery

17.5.6 Get a query result

GET /models/{modelId}/queries/results/{queryId}

Response body JSON object: ODLPlanningQueryResult

17.5.7 Get all pending queries

GET /models/{modelId}/queries/pending/

Response body JSON object: Array of ODLPlanningQuery

17.5.8 Get all query results

GET /models/{modelId}/queries/results/

Response body JSON object: Array of ODLPlanningQueryResult

17.5.9 Get total count of pending queries

GET /models/{modelId}/queries/pending/count

Response body JSON object: ODLCountResponse

17.5.10 Get total count of query results

GET /models/{modelId}/queries/results/count

Response body JSON object: ODLCountResponse

17.5.11 Put pending query

PUT /models/{modelId}/queries/pending/{queryId}

Request body JSON object: ODLPlanningQuery

Notes: Put a new query or update an existing not-yet-processed one using the ID from the URL.

17.6 Stop-arrivals endpoint

Access stop arrivals events for vehicle in model. A stop arrival event tells the optimiser that a stop - defined by its id - was arrived at, at a certain time. The optimiser uses this information to estimate the state of the vehicle at the current time.

17.6.1 Delete all stop arrived events for the vehicle

DELETE /models/{modelId}/vehicles/{vehicleId}/stoparrivals/ 

17.6.2 Delete stop arrived event

DELETE /models/{modelId}/vehicles/{vehicleId}/stoparrivals/{eventId}

17.6.3 Get all stop arrival events for vehicle

GET /models/{modelId}/vehicles/{vehicleId}/stoparrivals/

Response body JSON object: Array of ODLStopArrivalEvent

17.6.4 Get stop arrival event by its event id

GET /models/{modelId}/vehicles/{vehicleId}/stoparrivals/{eventId}

Response body JSON object: ODLStopArrivalEvent

17.6.5 Put updated or new stop arrival event using its event id

PUT /models/{modelId}/vehicles/{vehicleId}/stoparrivals/{eventId}

Request body JSON object: ODLStopArrivalEvent

17.7 Stop-completeds endpoint

Access stop completed events for vehicle in model. A stop completed event tells the optimiser that a stop - defined by its id - was completed at a certain time. The optimiser uses this information to estimate the state of the vehicle at the current time.

17.7.1 Delete all stop completed events for the vehicle

DELETE /models/{modelId}/vehicles/{vehicleId}/stopcompleted/

17.7.2 Delete stop completed event using its event id

DELETE /models/{modelId}/vehicles/{vehicleId}/stopcompleted/{eventId}

17.7.3 Get all stop completed events for vehicle

GET /models/{modelId}/vehicles/{vehicleId}/stopcompleted/

Response body JSON object: Array of ODLStopCompletedEvent

17.7.4 Get stop completed event using its event id

GET /models/{modelId}/vehicles/{vehicleId}/stopcompleted/{eventId} 

Response body JSON object: ODLStopCompletedEvent

17.7.5 Put updated or new stop completed event using its event id

PUT /models/{modelId}/vehicles/{vehicleId}/stopcompleted/{eventId}

Request body JSON object: ODLStopCompletedEvent

17.8 Vehicle-dispatches endpoint

Access vehicle dispatches. If autopilot is set to off as per the standard configuration, the client can put and delete dispatches. The client can therefore accept or override the optimiser’s planned routes as needed.

17.8.1 Delete a dispatch from a vehicle

DELETE /models/{modelId}/vehicles/{vehicleId}/dispatches/{dispatchId}

Notes: Only allowed with autopilot off. Warning, the optimiser uses the dispatch list to calculate the state of a vehicle. If the driver of a vehicle is heading for a dispatched destination, and the dispatch is then deleted from the optimiser, the optimiser will incorrectly calculate the vehicle’s location. Also if a stop completed event already exists for a dispatch, it will be not be deleted.

17.8.2 Get all dispatches for the vehicle

GET /models/{modelId}/vehicles/{vehicleId}/dispatches/

Response body JSON object: Array of ODLDispatch

17.8.3 Get all dispatches without a stop completed event, for the vehicle

GET /models/{modelId}/vehicles/{vehicleId}/dispatches/incomplete/ 

Response body JSON object: Array of ODLDispatch

17.8.4 Get dispatch within the vehicle, using its dispatch id

GET /models/{modelId}/vehicles/{vehicleId}/dispatches/{dispatchId}

Response body JSON object: Array of ODLDispatch

17.8.5 Put a dispatch to the vehicle using a dispatch id

PUT /models/{modelId}/vehicles/{vehicleId}/dispatches/{dispatchId} 

Request body JSON object: ODLDispatch

Notes: Only allowed with autopilot off.. New dispatch is added to the end of the vehicle’s dispatch list.

17.9 Vehicles endpoint

Access vehicles in a model. A vehicle starts at a defined start location and time and is available to work until its end time, when it returns to its end location (if set). Vehicles therefore really define a ‘vehicle-shift’ or ‘driver-shift’ - e.g. a working period for a driver or technician.

17.9.1 Delete all vehicles within model

DELETE /models/{modelId}/vehicles/

17.9.2 Delete vehicle from model

DELETE /models/{modelId}/vehicles/{vehicleId}

Notes: Any job with one or more stops completed by this vehicle is also deleted. If a job has dispatched but incomplete stops on this vehicle, they will be considered for re-dispatch by another vehicle.

17.9.3 Get all vehicles in the model

GET /models/{modelId}/vehicles/

Response body JSON object: Array of ODLVehicle

17.9.4 Get specific vehicle by its id

GET /models/{modelId}/vehicles/{vehicleId}

Response body JSON object: ODLVehicle

17.9.5 Put a vehicle - either a new one or updated one

PUT /models/{modelId}/vehicles/{vehicleId}

Request body JSON object: ODLVehicle

17.9.6 Put all vehicles

PUT /models/{modelId}/vehicles/

Request body JSON object: Array of ODLVehicle

Notes: Replace all vehicles, all existing vehicles are hard-deleted

17.9.7 Put vehicle definition

PUT /models/{modelId}/vehicles/{vehicleId}/definition

Request body JSON object: ODLVehicleDefinition

Notes: Modify definition of existing vehicle. Vehicle must already be added.