Usage of Pickup and Delivery API is mostly identical with the normal Vehicle Routing API, with only one difference: the way we define pickup and delivery orders in the visits object.

In this case, visits is a hash of order objects where the key represents the ID of the order. Each order has a pickup and dropoff object. Both the pickup and dropoff objects require a location object, and optionally can have independent time-window and duration parameters.

PROPERTY	TYPE	REQUIRED
pickup	Visit object	required
dropoff	Visit object	required
load	Number (any unit)	optional
type	String or Array	optional

The pickup and dropoff parameters must be defined and are just like regular visit objects:

PROPERTY	TYPE	REQUIRED
location	Location object	required
start	String ("hh:mm")	optional
end	String ("hh:mm")	optional
duration	Number (minutes)	optional

Each order can also have an optional load parameter. This is used when you want to account for the maximum capacity of your vehicles. This capacity must be defined on your fleet as well, otherwise this parameter will be ignored.

type is an optional parameter if you want to restrict a visit to be served by a particular type of vehicle. The value of this parameter can be a String or an Array of Strings for multiple types. For example, if a visit has the type ["A","B"] it can be served by a vehicle of type "A" or "B". If none of the vehicles match the type, it will be unserved. Visits without any type parameters can be served by any vehicle.

📘
Note that the load and type parameters are defined on the order object and not on the individual pick up and drop off objects

{
    "visits": {
        "order_1": {
            "load": 1,
            "pickup": {
                "location": {
                    "name": "3780 Arbutus",
                    "lat": 49.2474624,
                    "lng": -123.1532338
                },
                "start": "9:00",
                "end": "12:00",
                "duration": 10
            },
            "dropoff": {
                "location": {
                    "name": "6800 Cambie",
                    "lat": 49.227107,
                    "lng": -123.1163085
                },
                "start": "9:00",
                "end": "12:00",
                "duration": 10
            }
        },
        "order_2": {
            "load": 1,
            "pickup": {
                "location": {
                    "name": "3780 Arbutus",
                    "lat": 49.2474624,
                    "lng": -123.1532338
                },
                "start": "9:00",
                "end": "12:00",
                "duration": 10
            },
            "dropoff": {
                "location": {
                    "name": "800 Robson",
                    "lat": 49.2819229,
                    "lng": -123.1211844
                },
                "start": "9:00",
                "end": "12:00",
                "duration": 10
            }
        }
    },
    "fleet": {
        "vehicle_1": {
            "start_location": {
                "id": "depot",
                "name": "800 Kingsway",
                "lat": 49.2553636,
                "lng": -123.0873365
            },
            "end_location": {
                "id": "depot",
                "name": "800 Kingsway",
                "lat": 49.2553636,
                "lng": -123.0873365
            },
            "shift_start": "8:00",
            "shift_end": "12:00",
            "capacity": 2
        },
        "vehicle_2": {
            "start_location": {
                "id": "depot 2",
                "name": "800 Robson",
                "lat": 49.2819229,
                "lng": -123.1211844
            },
            "end_location": {
                "id": "depot",
                "name": "800 Kingsway",
                "lat": 49.2553636,
                "lng": -123.0873365
            },
            "shift_start": "8:00",
            "shift_end": "12:00",
            "capacity": 1
        }
    }
}

{
  "status": "success",
  "total_travel_time": 31.283333,
  "total_idle_time": 0,
  "num_unserved": 0,
  "unserved": null,
  "solution": {
    "vehicle_1": [
      {
        "location_id": "depot",
        "location_name": "800 Kingsway",
        "arrival_time": "08:50"
      },
      {
        "location_id": "order_2",
        "location_name": "3780 Arbutus",
        "arrival_time": "09:00",
        "finish_time": "09:10",
        "type": "pickup"
      },
      {
        "location_id": "order_1",
        "location_name": "3780 Arbutus",
        "arrival_time": "09:10",
        "finish_time": "09:20",
        "type": "pickup"
      },
      {
        "location_id": "order_1",
        "location_name": "6800 Cambie",
        "arrival_time": "09:26",
        "finish_time": "09:36",
        "type": "dropoff"
      },
      {
        "location_id": "order_2",
        "location_name": "800 Robson",
        "arrival_time": "09:45",
        "finish_time": "09:55",
        "type": "dropoff"
      },
      {
        "location_id": "depot",
        "location_name": "800 Kingsway",
        "arrival_time": "10:02"
      }
    ],
    "vehicle_2": [
      {
        "location_id": "depot 2",
        "location_name": "800 Robson",
        "arrival_time": "08:00"
      },
      {
        "location_id": "depot",
        "location_name": "800 Kingsway",
        "arrival_time": "08:06"
      }
    ]
  }
}

Another thing to note in the example on the right: in the output, each visit contains a type to indicate if it is a pick up or a drop off.