Start of Day: Delivery Jobs and Horse Stabling

At the beginning of any given day, there will be a number of delivery jobs that need to be completed by the various horses that are currently on duty, and where they are stabled.

The start-of-day/stabling service provides the necessary information about the horses on duty and the depots they are at. Each depot is assigned a list of horse ids, which denotes the horses in the fleet that are working on the given day and who are starting the day at that particular depot. If a depot is given an empty list of horse ids, then no horses are starting the day at that depot - the depot will need to rely on loaned horses.

The start-of-day/jobs service provides information about the delivery jobs that need to be conducted on a given day. The delivery jobs themselves are fixed at the start of the day - no new jobs are added after the day starts. This service returns a csv file with 4 columns:

• jobID: An ID code for the delivery job. This typically comes from when a customer places an order and is an internal identifier that CLtd use.
• dispatch: The integer node ID of a depot in the road network. This is the depot that the delivery job must be dispatched from, equivalently the delivery depot that is responsible for conducting this delivery.
• destination: The integer node ID of any location in the road network. This is the location to which the delivery needs to be made.
• weight: A floating-point value giving the weight of the package to be delivered as part of this job.
• items: A text description of the contents of the parcel, if known.

Querying

To query for information about which horses are stabled at which depots, on a given day:

• start-of-day/stabling?date=YYYY-MM-DD

To query for the delivery jobs that need to be conducted on a given day:

• start-of-day/jobs?date=YYYY-MM-DD

Parameters

• date: The date to fetch the information for. Must be given in the format YYYY-MM-DD, and must be between 2024-01-01 and 2025-12-31 (inclusive). Defaults to the present day if not provided.

Examples

• https://rse-with-python.arc.ucl.ac.uk/delivery-info/start-of-day/stabling?date=2024-09-01 - retrieve the list of stabled horses on 1st September 2024.
• https://rse-with-python.arc.ucl.ac.uk/delivery-info/start-of-day/jobs?date=2025-09-01 - retrieve the delivery jobs are scheduled for 1st September 2025.
• https://rse-with-python.arc.ucl.ac.uk/delivery-info/start-of-day/jobs - retrieve the delivery jobs that are scheduled for today.

Return format

The start-of-day/stabling service will return a .json file (of a single entry). The keys of the entry will be (strs that can be safely cast to) ints, corresponding to the node index of a depot in the road network. The values associated with the keys will be lists of horse ids, giving the horses on duty that will be starting the day at that depot. All depots will appear as keys in the response, though some depots might have empty lists of horses.

If for example, we have depots with node indexes 0, 1, 2, and 3, and horses with ids horse-1, horse-2, horse-3, horse-4, then the output

{
    "0": ["horse-1", "horse-3"],
    "2": ["horse-2"],
    "3": [], 
}

indicates that horse-1 and horse-3 start the day at depot 0. horse-2 starts the day at depot 2. Depots 1 (no key) and 3 (empty list) do not have any horses based there at the start of the day. horse-4 is not on active duty on this day (since it does not appear in any of the lists).

The start-of-day/jobs service will return a .csv file with headers where each row contains the following information about the requested locations:

dispatch, destination, weight, items, jobID

Values in the columns are (respectively) of type int, int, float, str, and str.