NAV Navbar
shell javascript python
  • Cargo Insurance Protocol
  • Need
  • Bid
  • Vehicle Types
  • Cargo Types
  • Hazardous Goods
  • Insurance Coverage Types
  • IP Protection Level
  • Price Types
  • 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