Cargo Insurance

Cargo Insurance Protocol

The following document describes the communication protocol for a cargo insurance service provided by an insurance provider to a user or a courier. It includes the format for both the request for insurance (also referred to as need) and the response sent by insurance providers that bid on providing the service.

For example, an autonomous drone that is about to deliver an expensive diamond ring would send a request for an insurance service, along with the estimated value of the ring, and the delivery path.

Need

curl "discovery_endpoint_here" \
  --data "{ \
    \"start_at\": \"1513005534000\", \
    \"end_at\": \"1513008000000\", \
    \"pickup_latitude\": \"40.958123\", \
    \"pickup_longitude\": \"-74.169388\", \
    \"dropoff_latitude\": \"40.875103\", \
    \"dropoff_longitude\": \"-74.570389\", \
    \"planned_path\": \"40.958123,-74.169388,40.7899,-74.463272,40.875103,-74.570389\", \
    \"vehicle_type\": \"drone\", \
    \"cargo_type\": \"11\", \
    \"insured_value\": \"3000.00\", \
    \"insured_value_currency\": \"USD\" \
  }"

const discoveryEndPoint = 'discovery_endpoint_here';

fetch(discoveryEndPoint, {
  method: 'POST',
  body: JSON.stringify({
    start_at: '1513005534000',
    end_at: '1513008000000',
    pickup_latitude: '40.958123',
    pickup_longitude: '-74.169388',
    dropoff_latitude: '40.875103',
    dropoff_longitude: '-74.570389',
    planned_path:
      '40.958123,-74.169388,40.7899,-74.463272,40.875103,-74.570389',
    vehicle_type: 'drone',
    cargo_type: '11',
    insured_value: '3000.00',
    insured_value_currency: 'USD',
  }),
});

import requests
payload = {
    "start_at": "1513005534000",
    "end_at": "1513008000000",
    "pickup_latitude": "40.958123",
    "pickup_longitude": "-74.169388",
    "dropoff_latitude": "40.875103",
    "dropoff_longitude": "-74.570389",
    "planned_path": "40.958123,-74.169388,40.7899,-74.463272,40.875103,-74.570389",
    "vehicle_type": "drone",
    "cargo_type": "11",
    "insured_value": "3000.00",
    "insured_value_currency": "USD",
  }
requests.post("discovery_endpoint_here", data=payload)

In response, an insurance provider might send back a bid with the policy price, the type of coverage, and the deductible amount required.

Bid

curl "bidding_endpoint_here" \
--data "{ \
    \"need_id\": \"ae7bd8f67f3089c\", \
    \"expires_at\": \"1513005539000\", \
    \"coverage_type\": \"all_risk\", \
    \"price\": \"100000000000000000\", \
    \"price_type\": \"flat\", \
    \"price_description\": \"Policy cost\", \
    \"deductible\": \"1400000000000000000\" \
  }"

const biddingEndPoint = 'bidding_endpoint_here';

fetch(biddingEndPoint, {
  method: 'POST',
  body: JSON.stringify({
    need_id: 'ae7bd8f67f3089c',
    expires_at: '1513005539000',
    coverage_type: 'all_risk',
    price: '100000000000000000',
    price_type: 'flat',
    price_description: 'Policy cost',
    deductible: '1400000000000000000',
  }),
});

import requests
payload = {
    "need_id": "ae7bd8f67f3089c",
    "expires_at": "1513005539000",
    "coverage_type": "all_risk",
    "price": "100000000000000000",
    "price_type": "flat",
    "price_description": "Policy cost",
    "deductible": "1400000000000000000",
  }
requests.post("bidding_endpoint_here", data=payload)

Need

A statement of need for a cargo insurance service. Typically this will be sent by a user or a courier that plans to deliver a package from one point to another.

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 "{ \
    \"start_at\": \"1513005534000\", \
    \"end_at\": \"1513008000000\", \
    \"start_latitude\": \"40.746217\", \
    \"start_longitude\": \"-73.970261\", \
    \"pickup_latitude\": \"40.958123\", \
    \"pickup_longitude\": \"-74.169388\", \
    \"dropoff_latitude\": \"40.875103\", \
    \"dropoff_longitude\": \"-74.570389\", \
    \"end_latitude\": \"40.746217\", \
    \"end_longitude\": \"-73.970261\", \
    \"planned_path\": \"40.958123,-74.169388,40.7899,-74.463272,40.875103,-74.570389\", \
    \"requester_name\": \"Megadronix\", \
    \"requester_phone_number\": \"+31-338-594332\", \
    \"external_reference_id\": \"200982447\", \
    \"vehicle_type\": \"drone,ship,drone\", \
    \"vehicle_is_autonomous\": \"true,false,true\", \
    \"cargo_type\": \"11\", \
    \"hazardous_goods\": \"8\", \
    \"ip_protection_level\": \"68\", \
    \"height\": \"8\", \
    \"width\": \"2\", \
    \"length\": \"2\", \
    \"weight\": \"50\", \
    \"insured_value\": \"3000.00\", \
    \"insured_value_currency\": \"USD\" \
  }"

const discoveryEndPoint = 'discovery_endpoint_here';

fetch(discoveryEndPoint, {
  method: 'POST',
  body: JSON.stringify({
    start_at: '1513005534000',
    end_at: '1513008000000',
    start_latitude: '40.746217',
    start_longitude: '-73.970261',
    pickup_latitude: '40.958123',
    pickup_longitude: '-74.169388',
    dropoff_latitude: '40.875103',
    dropoff_longitude: '-74.570389',
    end_latitude: '40.746217',
    end_longitude: '-73.970261',
    planned_path:
      '40.958123,-74.169388,40.7899,-74.463272,40.875103,-74.570389',
    requester_name: 'Megadronix',
    requester_phone_number: '+31-338-594332',
    external_reference_id: '200982447',
    vehicle_type: 'drone,ship,drone',
    vehicle_is_autonomous: 'true,false,true',
    cargo_type: '11',
    hazardous_goods: '8',
    ip_protection_level: '68',
    height: '8',
    width: '2',
    length: '2',
    weight: '50',
    insured_value: '3000.00',
    insured_value_currency: 'USD',
  }),
});

import requests
payload = {
    "start_at": "1513005534000",
    "end_at": "1513008000000",
    "start_latitude": "40.746217",
    "start_longitude": "-73.970261",
    "pickup_latitude": "40.958123",
    "pickup_longitude": "-74.169388",
    "dropoff_latitude": "40.875103",
    "dropoff_longitude": "-74.570389",
    "end_latitude": "40.746217",
    "end_longitude": "-73.970261",
    "planned_path": "40.958123,-74.169388,40.7899,-74.463272,40.875103,-74.570389",
    "requester_name": "Megadronix",
    "requester_phone_number": "+31-338-594332",
    "external_reference_id": "200982447",
    "vehicle_type": "drone,ship,drone",
    "vehicle_is_autonomous": "true,false,true",
    "cargo_type": "11",
    "hazardous_goods": "8",
    "ip_protection_level": "68",
    "height": "8",
    "width": "2",
    "length": "2",
    "weight": "50",
    "insured_value": "3000.00",
    "insured_value_currency": "USD",
  }
requests.post("discovery_endpoint_here", data=payload)

`start_at` optional	The time at which the requester would like the insurance to be activated (if undefined, the activation will be immediate). This should be Specified as time in seconds since Epoch/Unix Time
`end_at` required	The time at which the requester would like the insurance to stop. This should be Specified as time in seconds since Epoch/Unix Time
`start_latitude` optional	The latitude coordinate of the take off location, prior to the arrival at the pickup location
`start_longitude` optional	The longitude coordinate of the take off location, prior to the arrival at the pickup location
`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
`end_latitude` optional	The latitude coordinate of the end location, after the departure from the dropoff destination
`end_longitude` optional	The longitude coordinate of the end location, after the departure from the dropoff destination
`planned_path` optional	The planned trip described as a polyline using geodesic geometry. Specified as a comma separated list of coordinates (e.g., "lat,long,lat,long,lat,long")
`requester_name` optional	The name of the person or the company requesting the insurance service
`requester_phone_number` optional	The phone number of the person or the company requesting the insurance service
`external_reference_id` optional	An identification string that might be needed for providing the insurance service
`vehicle_type` required	The type of vehicle (one or more) used for the trip, specified as a comma separated list. See full list of options here
`vehicle_is_autonomous` optional	A boolean or a comma separated list of booleans, stating if the vehicle used for the trip is autonomous (`true`) or human controlled (`false`). Default is `true`
`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 that may be provided to the cargo (see full list of options here). This is optional but recommended as it may affect the price of policy
`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
`insured_value` required	The declared value of the cargo to be insured. Specified as a float
`insured_value_currency` required	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 cargo insurance. Typically sent from an insurance provider to a user or a courier that plans to deliver a package from one point to another.

Arguments

Post request to a local/remote bidding endpoint

curl "bidding_endpoint_here" \
  --data "{ \
    \"need_id\": \"ae7bd8f67f3089c\", \
    \"expires_at\": \"1513005539000\", \
    \"coverage_type\": \"all_risk\", \
    \"price\": \"20000000000000000,100000000000000000\", \
    \"price_type\": \"minute,flat\", \
    \"price_description\": \"Price per minute,City tax\", \
    \"deductible\": \"1400000000000000000\", \
    \"insurer_contact\": \"Airsurance LTD, Tel: +1 415 982 3342\", \
    \"insurer_dav_id\": \"0x17325a469aef3472aa58dfdcf672881d79b31d58\" \
  }"

const biddingEndPoint = 'bidding_endpoint_here';

fetch(biddingEndPoint, {
  method: 'POST',
  body: JSON.stringify({
    need_id: 'ae7bd8f67f3089c',
    expires_at: '1513005539000',
    coverage_type: 'all_risk',
    price: '20000000000000000,100000000000000000',
    price_type: 'minute,flat',
    price_description: 'Price per minute,City tax',
    deductible: '1400000000000000000',
    insurer_contact: 'Airsurance LTD, Tel: +1 415 982 3342',
    insurer_dav_id: '0x17325a469aef3472aa58dfdcf672881d79b31d58',
  }),
});

import requests
payload = {
    "need_id": "ae7bd8f67f3089c",
    "expires_at": "1513005539000",
    "coverage_type": "all_risk",
    "price": "20000000000000000,100000000000000000",
    "price_type": "minute,flat",
    "price_description": "Price per minute,City tax",
    "deductible": "1400000000000000000",
    "insurer_contact": "Airsurance LTD, Tel: +1 415 982 3342",
    "insurer_dav_id": "0x17325a469aef3472aa58dfdcf672881d79b31d58",
  }
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
`coverage_type` required	The type of coverage provided in the insurance policy. See full list of options here
`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
`deductible` required	The amount that must be paid by the policy holder before an insurance provider will pay any expenses. A comma Specified as an integer representing Vinci 1 DAV == 1e18 Vinci == 1000000000000000000 Vinci
`insurer_contact` optional	Human readable information regarding the insurance company (e.g., `Airsurance LTD, Tel: +1 415 982 3342`)
`insurer_dav_id` optional	If the insurer is a registered DAV member, include their ID here

Vehicle Types

The type of vehicles and their unique identifier.

Vehicle Type
`drone`
`car`
`truck`
`van`
`ship`
`robot`
`bike`
`rail`

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

Insurance Coverage Types

The type of coverage provided in the insurance policy to the cargo, according to international cargo insurance standards.

Coverage ID	Coverage Type	Description
`general`	General Average	Basic coverage, only covering partial losses
`fpa`	Free From Particular Average	Limited coverage, only covering losses caused from stranding, sinking, burning, or collision
`all_risk`	All Risk	Extensive coverage, including damage or loss due to external factors

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