Drone Delivery Protocol
The following document describes the communication protocol for a cargo delivery service provided by an autonomous drone. It includes the format for both the request for a delivery service (also referred to as need) and the response sent by drones that bid on providing the delivery service.
For example, a user is looking for a drone to pick up a small tube containing corrosive materials from their doorstep and deliver it to a friend's backyard.
Need
curl "discovery_endpoint_here" \
--data "{ \
\"pickup_at\": \"1513005534000\", \
\"pickup_latitude\": \"32.787793\", \
\"pickup_longitude\": \"-79.500593\", \
\"dropoff_latitude\": \"32.937778\", \
\"dropoff_longitude\": \"-79.500593\", \
\"cargo_type\": \"11\", \
\"hazardous_goods\": \"8\" \
}"
const discoveryEndPoint = 'discovery_endpoint_here';
fetch(discoveryEndPoint, {
method: 'POST',
body: JSON.stringify({
pickup_at: '1513005534000',
pickup_latitude: '32.787793',
pickup_longitude: '-79.500593',
dropoff_latitude: '32.937778',
dropoff_longitude: '-79.500593',
cargo_type: '11',
hazardous_goods: '8',
}),
});
import requests
payload = {
"pickup_at": "1513005534000",
"pickup_latitude": "32.787793",
"pickup_longitude": "-79.500593",
"dropoff_latitude": "32.937778",
"dropoff_longitude": "-79.500593",
"cargo_type": "11",
"hazardous_goods": "8",
}
requests.post("discovery_endpoint_here", data=payload)
In response, a drone might send back a bid with a price, the estimated time of arrival at the pickup location, and the estimated time of arrival at the dropoff location.
Bid
curl "bidding_endpoint_here" \
--data "{ \
\"need_id\": \"ae7bd8f67f3089c\", \
\"expires_at\": \"1513005539000\", \
\"price\": \"2000000000000000,20000000000000000\", \
\"price_type\": \"second,flat\", \
\"price_description\": \"Price per second,Tax\", \
\"eta_pickup\": \"1513005719000\", \
\"eta_dropoff\": \"1513006460000\" \
}"
const biddingEndPoint = 'bidding_endpoint_here';
fetch(biddingEndPoint, {
method: 'POST',
body: JSON.stringify({
need_id: 'ae7bd8f67f3089c',
expires_at: '1513005539000',
price: '2000000000000000,20000000000000000',
price_type: 'second,flat',
price_description: 'Price per second,Tax',
eta_pickup: '1513005719000',
eta_dropoff: '1513006460000',
}),
});
import requests
payload = {
"need_id": "ae7bd8f67f3089c",
"expires_at": "1513005539000",
"price": "2000000000000000,20000000000000000",
"price_type": "second,flat",
"price_description": "Price per second,Tax",
"eta_pickup": "1513005719000",
"eta_dropoff": "1513006460000",
}
requests.post("bidding_endpoint_here", data=payload)
Need
A statement of need for a delivery service. Typically this will be sent by a user that is looking to deliver a package using a drone.
This request is sent to the decentralized discovery engine which responds with status 200 and a unique identifier for this request. The details of this request are then broadcasted to DAV entities that can provide this service. Bids are later received as separate calls.
Arguments
Post request to a local/remote discovery endpoint
curl "discovery_endpoint_here" \
--data "{ \
\"pickup_at\": \"1513005534000\", \
\"pickup_latitude\": \"32.787793\", \
\"pickup_longitude\": \"-79.500593\", \
\"dropoff_latitude\": \"32.937778\", \
\"dropoff_longitude\": \"-79.500593\", \
\"requester_name\": \"Jessie Bourne\", \
\"requester_phone_number\": \"+1 415 123 5983\", \
\"external_reference_id\": \"jb84723\", \
\"cargo_type\": \"11\", \
\"hazardous_goods\": \"8\", \
\"ip_protection_level\": \"68\", \
\"height\": \"8\", \
\"width\": \"2\", \
\"length\": \"2\", \
\"weight\": \"50\", \
\"insurance_required\": \"true\", \
\"insured_value\": \"675\", \
\"insured_value_currency\": \"USD\" \
}"
const discoveryEndPoint = 'discovery_endpoint_here';
fetch(discoveryEndPoint, {
method: 'POST',
body: JSON.stringify({
pickup_at: '1513005534000',
pickup_latitude: '32.787793',
pickup_longitude: '-79.500593',
dropoff_latitude: '32.937778',
dropoff_longitude: '-79.500593',
requester_name: 'Jessie Bourne',
requester_phone_number: '+1 415 123 5983',
external_reference_id: 'jb84723',
cargo_type: '11',
hazardous_goods: '8',
ip_protection_level: '68',
height: '8',
width: '2',
length: '2',
weight: '50',
insurance_required: 'true',
insured_value: '675',
insured_value_currency: 'USD',
}),
});
import requests
payload = {
"pickup_at": "1513005534000",
"pickup_latitude": "32.787793",
"pickup_longitude": "-79.500593",
"dropoff_latitude": "32.937778",
"dropoff_longitude": "-79.500593",
"requester_name": "Jessie Bourne",
"requester_phone_number": "+1 415 123 5983",
"external_reference_id": "jb84723",
"cargo_type": "11",
"hazardous_goods": "8",
"ip_protection_level": "68",
"height": "8",
"width": "2",
"length": "2",
"weight": "50",
"insurance_required": "true",
"insured_value": "675",
"insured_value_currency": "USD",
}
requests.post("discovery_endpoint_here", data=payload)
pickup_at
optional
|
The time at which the service requester would like the cargo to be picked up (if undefined, the pick up time will be ASAP). This should be Specified as time in seconds since Epoch/Unix Time |
pickup_latitude
required
|
The latitude coordinate of the pickup location |
pickup_longitude
required
|
The longitude coordinate of the pickup location |
dropoff_latitude
required
|
The latitude coordinate of the dropoff destination |
dropoff_longitude
required
|
The longitude coordinate of the dropoff destination |
requester_name
optional
|
The name of the person that is asking for the delivery service |
requester_phone_number
optional
|
The phone number of the person that is asking for the delivery service |
external_reference_id
optional
|
An identification string that might be needed for cargo dispatch |
cargo_type
required
|
The type of cargo to be delivered. See the full list of options here |
hazardous_goods
optional
|
If the cargo contains hazardous goods, the hazardous goods class must be included. See the full list of options here |
ip_protection_level
optional
|
A certain level of protection to the cargo may be requested. See full list of options here |
height
optional
|
The height of the cargo. Specified as an integer representing centimeters |
width
optional
|
The width of the cargo. Specified as an integer representing centimeters |
length
optional
|
The length of the cargo. Specified as an integer representing centimeters |
weight
optional
|
The weight of the cargo. Specified as an integer representing grams |
insurance_required
optional
|
the service requester may require that the delivery be insured. Specified as a boolean (default is false) |
insured_value
optional
|
The declared value of the cargo to be insured |
insured_value_currency
optional
|
The currency in which the declared value is denoted. This should be specified as a 3-letter ISO 4217 code or DAV |
Bid
A bid to provide a delivery service. Typically sent from a delivery drone to the user who requested the service
Arguments
Post request to a local/remote bidding endpoint
curl "bidding_endpoint_here" \
--data "{ \
\"need_id\": \"ae7bd8f67f3089c\", \
\"expires_at\": \"1519093577681\", \
\"price\": \"200000000000000\",20000000000000000”, \
\"price_type\": \"secon\",flat”, \
\"price_description\": \"Pric\" per second,Tax”, \
\"eta_pickup\": \"1513005719000\", \
\"eta_dropoff\": \"1513006460000\", \
\"insured\": \"true\", \
\"insurer_dav_id\": \"0x17325a469aef3472aa58dfdcf672881d79b31d58\", \
\"drone_contact\": \"Megadronix\", \
\"drone_manufacturer\": \"DXY\", \
\"drone_model\": \"m6000\" \
}"
const biddingEndPoint = 'bidding_endpoint_here';
fetch(biddingEndPoint, {
method: 'POST',
body: JSON.stringify({
need_id: 'ae7bd8f67f3089c',
expires_at: '1519093577681',
price: '2000000000000000,20000000000000000',
price_type: 'second,flat',
price_description: 'Price per second,Tax',
eta_pickup: '1513005719000',
eta_dropoff: '1513006460000',
insured: 'true',
insurer_dav_id: '0x17325a469aef3472aa58dfdcf672881d79b31d58',
drone_contact: 'Megadronix',
drone_manufacturer: 'DXY',
drone_model: 'm6000',
}),
});
import requests
payload = {
"need_id": "ae7bd8f67f3089c",
"expires_at": "1519093577681",
"price": "2000000000000000,20000000000000000",
"price_type": "second,flat",
"price_description": "Price per second,Tax",
"eta_pickup": "1513005719000",
"eta_dropoff": "1513006460000",
"insured": "true",
"insurer_dav_id": "0x17325a469aef3472aa58dfdcf672881d79b31d58",
"drone_contact": "Megadronix",
"drone_manufacturer": "DXY",
"drone_model": "m6000",
}
requests.post("bidding_endpoint_here", data=payload)
need_id
required
|
The unique identifier of the 'need' this bid is for. This ID arrives as part of the 'need' request |
expires_at
required
|
This bid will expire at this time. Specified as time in seconds since Epoch/Unix Time |
price
required
|
A comma separated list of prices. Each price is specified as an integer representing Vinci
1 DAV == 1e18 Vinci == 1000000000000000000 Vinci |
price_type
required
|
A list of price types describing the price parameter(s). Specified as a comma separated list. See Price Types for available values |
price_description
required
|
A comma separated list of strings describing the price parameter(s) in human readable terms |
eta_pickup
required
|
The estimate time of arrival at the pickup location. Specified as time in seconds since Epoch/Unix Time |
eta_dropoff
required
|
The estimate time of arrival at the dropoff location. Specified as time in seconds since Epoch/Unix Time |
insured
optional
|
Is this delivery insured? Specified as a boolean (default is false) |
insurer_dav_id
optional
|
If this delivery is insured by another DAV Identity, include their ID here |
ip_protection_level
optional
|
A certain level of protection that a drone may provide to the cargo. See full list of options here |
drone_contact
optional
|
Human readable information regarding the drone (e.g Megadronix Deliveries LTD. +31-338-594332) |
drone_manufacturer
optional
|
Name of the manufacturer of this drone |
drone_model
optional
|
Name of the model of this drone |
Select Bid
A selection of one bid that wins over the rest. Sent by the service requester (a user that is looking to deliver a package using a drone)
Arguments
Post request to a local/remote endpoint representing the service provider
curl "discovery_endpoint_here" \
--data "{ \
\"bid_id\": \"bv43nmw65eef03e\" \
}"
const discoveryEndPoint = 'discovery_endpoint_here';
fetch(discoveryEndPoint, {
method: 'POST',
body: JSON.stringify({
bid_id: 'bv43nmw65eef03e',
}),
});
import requests
payload = {
"bid_id": "bv43nmw65eef03e",
}
requests.post("discovery_endpoint_here", data=payload)
bid_id
required
|
The unique identifier of the selected 'bid'. This ID arrives as part of the 'bid' request |
Starting
A message sent by the service provider (the delivery drone) to the service requester, notifying it that the delivery mission has started
Arguments
Post request to a local/remote endpoint representing the service requester
curl "bidding_endpoint_here" \
--data "{ \
\"bid_id\": \"bv43nmw65eef03e\", \
\"current_latitude\": \"32.785889\", \
\"current_longitude\": \"-79.935569\", \
\"current_altitude\": \"80\", \
\"azimuth_angle\": \"15\", \
\"eta_pickup\": \"1513005719000\", \
\"eta_dropoff\": \"1513006460000\" \
}"
const biddingEndPoint = 'bidding_endpoint_here';
fetch(biddingEndPoint, {
method: 'POST',
body: JSON.stringify({
bid_id: 'bv43nmw65eef03e',
current_latitude: '32.785889',
current_longitude: '-79.935569',
current_altitude: '80',
azimuth_angle: '15',
eta_pickup: '1513005719000',
eta_dropoff: '1513006460000',
}),
});
import requests
payload = {
"bid_id": "bv43nmw65eef03e",
"current_latitude": "32.785889",
"current_longitude": "-79.935569",
"current_altitude": "80",
"azimuth_angle": "15",
"eta_pickup": "1513005719000",
"eta_dropoff": "1513006460000",
}
requests.post("bidding_endpoint_here", data=payload)
bid_id
required
|
The unique identifier of the 'bid' that initiated the delivery mission |
current_latitude
required
|
The latitude coordinate of of where the drone is currently located |
current_longitude
required
|
The longitude coordinate of where the drone is currently located |
current_altitude
required
|
The current altitude of the drone. Specified as meters above sea level. For example, if the drone is located 50 meters above sea level, the current_altitude will be 50 |
azimuth_angle
required
|
The horizontal angle the drone is currently aiming at. Specified as an integer representing degrees |
eta_pickup
required
|
The estimate time of arrival at the pickup location. Specified as time in seconds since Epoch/Unix Time |
eta_dropoff
required
|
The estimate time of arrival at the dropoff location. Specified as time in seconds since Epoch/Unix Time |
Decline
A cancellation message sent by the service provider (the delivery drone) to the service requester, notifying it that the mission has been declined
Arguments
Post request to a local/remote endpoint representing the service requester
curl "bidding_endpoint_here" \
--data "{ \
\"bid_id\": \"bv43nmw65eef03e\" \
}"
const biddingEndPoint = 'bidding_endpoint_here';
fetch(biddingEndPoint, {
method: 'POST',
body: JSON.stringify({
bid_id: 'bv43nmw65eef03e',
}),
});
import requests
payload = {
"bid_id": "bv43nmw65eef03e",
}
requests.post("bidding_endpoint_here", data=payload)
bid_id
required
|
The unique identifier of the 'bid' that declined the delivery mission |
Request Status
A request message sent by the service requester to the service provider, asking for a status update
Arguments
Post request to a local/remote endpoint representing the service provider
curl "discovery_endpoint_here" \
--data "{ \
\"bid_id\": \"bv43nmw65eef03e\" \
}"
const discoveryEndPoint = 'discovery_endpoint_here';
fetch(discoveryEndPoint, {
method: 'POST',
body: JSON.stringify({
bid_id: 'bv43nmw65eef03e',
}),
});
import requests
payload = {
"bid_id": "bv43nmw65eef03e",
}
requests.post("discovery_endpoint_here", data=payload)
bid_id
required
|
The unique identifier of the 'bid' that is currently on the delivery mission |
Status
A status update sent by the service provider to the service requester
Arguments
Post request to a local/remote endpoint representing the service requester
curl "bidding_endpoint_here" \
--data "{ \
\"bid_id\": \"bv43nmw65eef03e\", \
\"current_latitude\": \"32.785889\", \
\"current_longitude\": \"-79.935569\", \
\"current_altitude\": \"80\", \
\"azimuth_angle\": \"15\", \
\"eta_pickup\": \"1513005719000\", \
\"eta_dropoff\": \"1513006460000\" \
}"
const biddingEndPoint = 'bidding_endpoint_here';
fetch(biddingEndPoint, {
method: 'POST',
body: JSON.stringify({
bid_id: 'bv43nmw65eef03e',
current_latitude: '32.785889',
current_longitude: '-79.935569',
current_altitude: '80',
azimuth_angle: '15',
eta_pickup: '1513005719000',
eta_dropoff: '1513006460000',
}),
});
import requests
payload = {
"bid_id": "bv43nmw65eef03e",
"current_latitude": "32.785889",
"current_longitude": "-79.935569",
"current_altitude": "80",
"azimuth_angle": "15",
"eta_pickup": "1513005719000",
"eta_dropoff": "1513006460000",
}
requests.post("bidding_endpoint_here", data=payload)
bid_id
required
|
The unique identifier of the 'bid' that is currently on the delivery mission |
current_latitude
required
|
The latitude coordinate of of where the drone is currently located |
current_longitude
required
|
The longitude coordinate of where the drone is currently located |
current_altitude
required
|
The current altitude of the drone. Specified as meters above sea level. For example, if the drone is located 50 meters above sea level, the current_altitude will be 50 |
azimuth_angle
required
|
The horizontal angle the drone is currently aiming at. Specified as an integer representing degrees |
eta_pickup
required
|
The estimate time of arrival at the pickup location. Specified as time in seconds since Epoch/Unix Time |
eta_dropoff
required
|
The estimate time of arrival at the dropoff location. Specified as time in seconds since Epoch/Unix Time |
Pickup Arrival
A message sent by the service provider to the service requester, notifying it that the drone has arrived at the pickup location (for the user to load the package)
Arguments
Post request to a local/remote endpoint representing the service requester
curl "bidding_endpoint_here" \
--data "{ \
\"bid_id\": \"bv43nmw65eef03e\" \
}"
const biddingEndPoint = 'bidding_endpoint_here';
fetch(biddingEndPoint, {
method: 'POST',
body: JSON.stringify({
bid_id: 'bv43nmw65eef03e',
}),
});
import requests
payload = {
"bid_id": "bv43nmw65eef03e",
}
requests.post("bidding_endpoint_here", data=payload)
bid_id
required
|
The unique identifier of the 'bid' that is currently on the delivery mission |
Pickup Leave
A message sent by the service provider to the service requester, notifying it that the drone has left the pickup location
Arguments
Post request to a local/remote endpoint representing the service requester
curl "bidding_endpoint_here" \
--data "{ \
\"bid_id\": \"bv43nmw65eef03e\", \
\"eta_dropoff\": \"1513006460000\" \
}"
const biddingEndPoint = 'bidding_endpoint_here';
fetch(biddingEndPoint, {
method: 'POST',
body: JSON.stringify({
bid_id: 'bv43nmw65eef03e',
eta_dropoff: '1513006460000',
}),
});
import requests
payload = {
"bid_id": "bv43nmw65eef03e",
"eta_dropoff": "1513006460000",
}
requests.post("bidding_endpoint_here", data=payload)
bid_id
required
|
The unique identifier of the 'bid' that is currently on the delivery mission |
eta_dropoff
required
|
The estimate time of arrival at the dropoff location. Specified as time in seconds since Epoch/Unix Time |
Dropoff Arrival
A message sent by the service provider to the service requester, notifying it that the drone has arrived at the dropoff location
Arguments
Post request to a local/remote endpoint representing the service requester
curl "bidding_endpoint_here" \
--data "{ \
\"bid_id\": \"bv43nmw65eef03e\" \
}"
const biddingEndPoint = 'bidding_endpoint_here';
fetch(biddingEndPoint, {
method: 'POST',
body: JSON.stringify({
bid_id: 'bv43nmw65eef03e',
}),
});
import requests
payload = {
"bid_id": "bv43nmw65eef03e",
}
requests.post("bidding_endpoint_here", data=payload)
bid_id
required
|
The unique identifier of the 'bid' that is currently on the delivery mission |
Dropoff Leave
A message sent by the service provider to the service requester, notifying it that the drone has left the dropoff location
Arguments
Post request to a local/remote endpoint representing the service requester
curl "bidding_endpoint_here" \
--data "{ \
\"bid_id\": \"bv43nmw65eef03e\" \
}"
const biddingEndPoint = 'bidding_endpoint_here';
fetch(biddingEndPoint, {
method: 'POST',
body: JSON.stringify({
bid_id: 'bv43nmw65eef03e',
}),
});
import requests
payload = {
"bid_id": "bv43nmw65eef03e",
}
requests.post("bidding_endpoint_here", data=payload)
bid_id
required
|
The unique identifier of the 'bid' that had just finished the delivery mission |
Cargo Types
The following table describes the different types of cargo according to international delivery standards
| Class ID | Type |
|---|---|
1 |
Satchel 500g |
2 |
Satchel 1kg |
3 |
Satchel 3kg |
4 |
Satchel 5kg |
5 |
Unpackaged |
6 |
Other/Misc |
7 |
Envelope |
8 |
Bag |
9 |
Satchel |
10 |
Crate |
11 |
Tube |
12 |
Pallet |
13 |
Skid |
14 |
Heavy Carton |
15 |
Carton containing glass |
16 |
Carton containing liquids |
17 |
wine/beer/liquor carton |
18 |
Carton |
Hazardous Goods
The following table describes the different types of hazardous goods according to international delivery standards
| Class ID | Type |
|---|---|
1 |
Explosives |
2 |
Gases |
3 |
Flammable and combustible liquids |
4 |
Flammable solids |
5 |
Oxidizing substances, organic peroxides |
6 |
Toxic and infectious substances |
7 |
Radioactive materials |
8 |
Corrosives |
9 |
Misc Hazardous |
IP Protection Level
A drone may provide a certain level of protection from solids and/or liquids (mainly water and dust). The following table describes the standard levels of protection according to the International Protection Marking, IEC standard 60529.
The first digit indicates the level of protection that the enclosure provides against access to hazardous parts (e.g., electrical conductors, moving parts) and the ingress of solid foreign objects.
The second digit indicates the level of protection that the enclosure provides against harmful ingress of water.
For a full listing of all available codes, read more about International Protection Marking, IEC standard 60529
| Rating Code | IP Rating | Solid Particle Protection | Liquid Ingress Protection |
|---|---|---|---|
54 |
IP54 | Protected from limited dust ingress | Protected from water spray from any direction, limited ingress protection |
55 |
IP55 | Protected from limited dust ingress | Protected from low pressure water jets from any direction, limited ingress protection |
56 |
IP56 | Protected from limited dust ingress | Protected from high pressure water jets from any direction, limited ingress protection |
57 |
IP57 | Protected from limited dust ingress | Protected from immersion between 15 centimeters and 1 meter in depth, limited ingress protection |
58 |
IP58 | Protected from limited dust ingress | Protected from long term immersion up to a specified pressure, limited ingress protection |
60 |
IP60 | Protected from total dust ingress | Not protected from liquids, limited ingress protection |
61 |
IP61 | Protected from total dust ingress | Protected from condensation, limited ingress protection |
62 |
IP62 | Protected from total dust ingress | Protected from water spray less than 15 degrees from vertical, limited ingress protection |
63 |
IP63 | Protected from total dust ingress | Protected from water spray less than 60 degrees from vertical, limited ingress protection |
64 |
IP64 | Protected from total dust ingress | Protected from water spray from any direction, limited ingress protection |
65 |
IP65 | Protected from total dust ingress | Protected from low pressure water jets from any direction, limited ingress protection |
66 |
IP66 | Protected from total dust ingress | Protected from high pressure water jets from any direction, limited ingress protection |
67 |
IP67 | Protected from total dust ingress | Protected from immersion between 15 centimeters and 1 meter in depth, limited ingress protection |
68 |
IP68 | Protected from total dust ingress | Protected from long term immersion up to a specified pressure, limited ingress protection |
69k |
IP69K | Protected from total dust ingress | Protected from steam-jet cleaning, limited ingress protection |
Price Types
Price types and their unique identifier
| Price Type | Description |
|---|---|
second |
Cost per second |
minute |
Cost per minute |
hour |
Cost per hour |
day |
Cost per day |
week |
Cost per week |
flat |
The listed price is a flat price |