Data & Delivery Format

Introduction

This document describes the data format that contains all necessary information, so that an external system can use Bettermile as a route optimization system. Drivers using Bettermile App will get an optimized route sequence, routing support (turn by turn navigation), consignee addresses, timeframes and other helpful information. Furthermore, it is a prerequisite for route optimization analysis and monitoring within the Bettermile Backoffice. The top level object in the data format is job, which is an abstraction of a single task a delivery driver has to perform. Currently there are three different types of jobs:

• delivery - job type for which the consignee-contact will be considered for tour calculation.
• pickup - pickup of a specific parcel with an already known parcel id. Shipper-contact will be considered for tour-calculation.
• collection - collecting an unknown number of parcels at the shipper-contact location (e.g. parcel shop, drop box).

Although all required information could technically be combined in one single job object, the different aspects typically become available at different points in time in the lifecycle of a parcel. Bettermile considers three phases of data transmission:

• master data - job properties that do not change (id, type, depot) or that are unlikely to change (shipper & consignee information) until the job is done. This information can be transmitted to Bettermile as soon as it is available in the tenants IT system. The actual date of delivery does not need to be final at this time.
• assignment data - contains assignment information for one job to a specific driver (or route, vehicle, etc) on a specific date. This is required for all jobs designated for a specific driver/route before Better Route is able to calculate optimized sequences and navigation routes for the driver. The ultimate goal is that assignments reflect 100% of the parcels physically present in a driver's vehicle when he/she leaves the depot in the morning and logs into Bettermile App.
  Please note that it is quite common that there will be multiple assignments for one job:
  • Drivers trade/swap parcels after the initial assignment was transmitted: in that case the tenant's connector should send a new assignment for the same job id with the new assignment value and a later scan date.
  • A parcel was not delivered today and it will be assigned to the same (or another) driver/route tomorrow: in this case the connector needs to transmit a new assignment for the next day, so that Better Route can include it on a new delivery sequence for the next day.
• status updates - are typically sent after the driver left the depot and a parcel gets a new status (e.g. “delivered”) in the tenants IT systems. Main purpose is to know which jobs need to be considered for tour (re-)calculation and which can be ignored because they are done.

General remarks on the format

Bettermile expects that all the data that is required for a certain date is exported daily before any driver activity takes place. The standard delivery mechanism is a periodic upload to an AWS S3 bucket.

The data is sent in JSON format as a top level array of elements (preferred) or as concatenated JSON.

Array example:

[
  {
    "id": "dc5a6618-66ac-4128-b198-fabcfca45423",
    "date": "2020-01-02",
    "...": "..."
  },
  {
    "id": "f30f3f1c-2115-4f36-8be3-c0fda62a78aa",
    "date": "2020-01-02",
    "...": "..."
  }
]

Concatenated JSON (Wikipedia):

{
  "id": "dc5a6618-66ac-4128-b198-fabcfca45423",
  "date": "2020-01-02",
  "...": "..."
}
{
  "id": "f30f3f1c-2115-4f36-8be3-c0fda62a78aa",
  "date": "2020-01-02",
  "...": "..."
}

The encoding of the data must be in UTF-8.

Additionally, the data has to be compliant with the JSON schema (see https://json-schema.org/). The D&D schema can be found under the following URLs:

• https://api.dgw.secondscreen.delivery/api/v1/dad-schema-array.json or
• https://api.dgw.secondscreen.delivery/api/v1/dad-schema.json (single job element)

Any particular payload should be validated against the schema by using a JSON schema validator (eg. JSON Schema Validator). Invalid job objects will not be processed by Bettermile Data Gateway.

Example

This is an example of import file, representing a Job object.

{
    "id" : "54365964-xyz",
    "date" : "2021-12-07",
    "created" : "2021-12-06T17:25:51.443-08:00",
    "source" : "manifest",
    "depot" : "ORC",
    "type" : "delivery",
    "shipper" : {
      "names" : [
        "Thalia Bücher GMBH"
      ]
    },
    "consignee" : {
      "type": "private",
      "names" : [
        "Firstname Lastname"
      ],
      "address" : {
        "street" : "4400 MacArthur BLVD",
        "postalCode" : "92660",
        "locality" : "NEWPORT BEACH",
        "province" : "CA",
        "country" : "US"
      },
      "email" : "user@foo.com",
      "phone" : "+4916012345678",
      "timeFrames" : [
        {
          "type" : "required",
          "earliest" : "09:00:00",
          "latest" : "14:00:00",
          "timezone" : "Europe/Brussels"
        }
     ]
   },
    "assignment" : {
      "scantime" : "2021-12-06T17:25:51.443-08:00",
      "properties" : {
        "route" : "4711"
      }
    },
    "services" : [
      {
        "acronym" : "PRI",
        "description" : "Priority Delivery"
      },
      {
        "acronym" : "SIG",
        "description" : "Adult Signature Required"
      }
    ],
    "physicalProperties" : [
      {
        "property" : "quantity",
        "value" : 1
      },
      {
        "property" : "weight",
        "value" : 12.0
      }
    ]
 }

Types

Job

A job contains everything that is necessary for a driver to perform a task. Most of the time, it is about delivering a parcel to a particular address.

Assignment

Note - Currently, an assignment has no specific source and date referred to it directly. This information is specified in the containing job object.

Assignment Tags

Assignment tags allow Bettermile to receive custom tenant-specific fields to enrich the required assignment property values. Assignment tags are enabled on a tenant-by-tenant basis and serve complimentary details to various Bettermile platform components such as Route, RTT, and Backoffice on tenant-specific operational contexts surrounding the submitted assignment values.

Assignment tags have the same lifespan as the parent assignment object: they expire when a new assignment for the Job is received or at midnight local time.

Example

{
    "id": "624717089",
    "date": "2021-09-01",
    "created": "2021-09-01T14:03:08.190+02:00",
    "depot": "687",
    "source": "assignment",
    "assignment": {
        "scantime": "2021-09-01T02:34:00Z",
        "priorityGroup": 1,
        "properties": {
            "vehicle": "2003"
        },
    "assignmentTags": {
        "driverName": "Jane Doe",
        "loadingZone": "Zone 2",
        "tourGroup": "5001",
        "subcontractorName": "John Doe"
    }
  }
}

Unassignment

Note - Currently, an unassignment has no specific source and date referred to it directly. This information is specified in the containing job object.

Example

{
  "id": "5743897964",
  "date": "2022-05-12",
  "created": "2022-05-12T13:11:23.264+02:00",
  "depot": "CT",
  "source": "assignment",
  "unassignment": {
    "assignment": {
      "properties": {
        "vehicle": "2003"
      }
    }
  }
}

Contact

Address

GeoCoordinates

Geo coordinates can be sent in one of the following data structures:

Timeframe

Services

Physical Property

RealtimeTracking

The realtimeTracking (RTT) object contains additional configuration data required specifically for Better Tracking services.

"redirect" : {
  "neighbor": true,
  "deposit": false,
  "parcelshop": true 
}

Notification

Describes how and when to contact the consignee via Real-Time Tracking.

"invite": {
    "email": true,
    "sms": false
  }

"reminder": {
    "email": true,
    "sms": false
  }

Full example

{
  "enabled": true,
  "notification": {
      "invite": {
        "email": true,
        "sms": false
      },
      "reminder": {
        "email": true,
        "sms": false
      }
  },
  "redirect": {
      "neighbor": true,
      "deposit": false,
      "parcelShop": true
  }
}

StatusChange

Example

{
  "id": "9200313150",
  "date": "2022-05-23",
  "source": "scan",
  "created": "2022-05-23T09:21:58.123+02:00",
  "statusChanges": [
    {
      "state": "processed",
      "timestamp": "2022-05-23T09:17:12.876+02:00",
      "outcome": "success",
      "outcomeDetails": {
        "type": "neighbor",
        "names": [
          "Beauty Hair Berlin",
          "c/o Jane Doe"        ]
      },
      "description": "to neighbour",
      "geoCoordinates": {
        "latitude": 37.72525,
        "longitude": 15.19114      }
    }
  ]
}

StatusChange - OutcomeDetails

The information here is largely used for Bettermile Real-time Tracking

Outcome Details - Parcel shop example

"outcomeDetails": {
  "type": "parcel_shop",
  "names": [
    "Kiosk & Bakery"
  ],
  "address": {
    "street": "Gubener Str. 23",
    "postalCode": "10243",
    "locality": "Berlin",
    "province": "BE",
    "country": "DE"
  }
}

Outcome Details - Neighbor example

"outcomeDetails": {
  "type": "neighbor",
  "names": [
    "Beauty Hair Berlin",
    "c/o Jane Doe"
  ]
}

Outcome Details - Deposit example

"outcomeDetails": {
  "type": "deposit",
  "hint": "on the terrace"
}

Outcome Details - Unsuccessful outcome because parcel was refused

"outcomeDetails": {
  "type": "not_accepted"
}

Notes for the types

• Mandatory means that it must be present and not empty.
• Date and times must follow the RFC 3339 section 5.6 standard . Timestamps must be UTC or include a timezone to be unambiguous.