Data

POST /data/global

This service updates global parameters.

Headers parameters:

Authorization (mandatory): User's token as Bearer <token>.

Body parameters (at least one of them is mandatory):

driver_categories (optional): Driver categories with their service time factors.
service_time (optional): Default service time in seconds.

Example request URL:

/data/global

Example body:

{
  "driver_categories": {
    "rookie": 1.7,
    "experienced": 1
  },
  "service_time": 30
}

Example response:

{
  "message": "global data successfully updated"
}

GET /data/global

This service returns the global parameters.

Headers parameters:

Authorization (mandatory): User's token as Bearer <token>.

Example request URL:

/data/global

Example response:

{
  "driver_categories": {
    "rookie": 1.7,
    "experienced": 1
  },
  "service_time": 30
}

POST /data/depot/:depot_id

This service create or updates depot parameters.

Headers parameters:

Authorization (mandatory): User's token as Bearer <token>.

Path parameters:

depot_id (mandatory): The depot ID.

Body parameters (at least one of them is mandatory):

vehicle_fill (optional): A float that indicates a percentage for the maximum filling capacity of the vehicles.
slow_down (optional): A float that indicates a percentage for slowing down the vehicles transit.
activated (optional): A boolean that indicates if the depot is active.
work_days (optional): An array with 7 booleans, indicating from Monday to Sunday if the depot is activated for those days.
priority(optional): Depot priority when run optimization engine.

Example request URL:

/data/depot/2

Example response:

{
  "vehicle_fill": 95.0,
  "slow_down": 5.0,
  "activated": true,
  "work_days": [true, true, true, true, true, false, false],
  "priority": 1
}

Example response:

{
  "message": "depot successfully updated"
}

GET /data/depot/:depot_id

This service returns a depot information.

Headers parameters:

Authorization (mandatory): User's token as Bearer <token>.

Path parameters:

depot_id (mandatory): The depot ID.

Example request URL:

/data/depot/2

Example response:

{
  "vehicle_fill": 95.0,
  "slow_down": 5.0,
  "activated": true,
  "work_days": [true, true, true, true, true, false, false],
  "priority": 1
}

POST /data/depot/:depot_id/drivers/:date

This service uploads the available drivers for a depot and a day. The driver has an assigned vehicle.

Headers parameters:

Authorization (mandatory): User's token as Bearer <token>.

Query string parameters:

depot_id (mandatory): The depot ID.
date (mandatory): The day in ISO8601.

Body parameters for each object of the array:

id (mandatory): The driver ID.
start_time (optional): Work start time. Default to 8:00 UTC.
working_hours (optional): Total number of working hours for the driver. Default to 8.
lunch_break (optional): Break time in minutes. Default to 30.
vehicle:
id (mandatory): The vehicle ID.
payload (mandatory): Payload in kg.
cargo_volume (mandatory): Volume in m^3.
type (optional): A string with the vehicle type.
brand (optional).
model (optional).
plate (optional).
max_speed (optional). Max speed limit (in km/h) for the vehicle. Default to 120 km/h

Example request URL:

/data/depot/2/drivers/2018-05-02

Example body:

[
  {
    "id": "D12345DFCG",
    "category": "rookie",
    "start_time": "08:00",
    "working_hours": 8,
    "lunch_break": 30,
    "vehicle": {
      "id": "43",
      "payload": 600,
      "cargo_volume": 2.40,
      "type": "H1",
      "brand": "Ford",
      "model": "Transit",
      "plate": "12345-ABC",
      "max_speed": 100
    }
  }
]

Example response:

{
  "message": "drivers successfully uploaded"
}

POST /data/deliveries

This service uploads a JSON array with all the deliveries for a depot. It expects a JSON with a low number of deliveries. For bigger data uploads use POST /data/deliveries/batch.

Updates: If a delivery was previously uploaded, the last one remains. If a delivery changes its address and it already has a route assigned it will be rejected.

Headers parameters:

Authorization (mandatory): User's token as Bearer <token>.

Body parameters for each object of the array:

id (mandatory): The delivery ID.
depot_id (mandatory).
delivery_point_id (mandatory): unique delivery point unique identifier.
customer_phone (optional).
customer_name (optional).
customer_email (optional).
address_1 (*1).
address_2 (*1).
town (*1).
county (*1).
postal_code (*1).
volume (mandatory): volume in m^3.
weight (mandatory): weight in kg.
lat (*2).
lng (*2).
service_time (mandatory): Seconds of service time.
after_time (optional): The beginning of the time window. The format is an ISO8601 without date.
before_time (optional): The ending of the time window. The format is an ISO8601 without date.

Body parameters caveats: A delivery without (*1) parameters needs all the (*2) ones, lat and lng, and vice versa. But the optimal behaviour is having both, (*1) and (*2).

Example request URL:

/data/deliveries

Example body:

[
  {
    "id": "32205731",
    "depot_id": "2",
    "delivery_point_id": "3737FTSO",
    "customer_phone": "086 1234567",
    "customer_name": "John McClane",
    "customer_email": "john@broccoli.com",
    "address_1": "Main Building",
    "address_2": "address2",
    "town": "City",
    "county": "County",
    "postal_code": null,
    "volume": 0.03,
    "weight": 0.2,
    "lat": 37.5,
    "lng": -6.5,
    "service_time": null,
    "after_time": "11:30:00Z",
    "before_time": null
  }
]

Response content description:

status (string): the status of the job. Its possible values are:
- QUEUED: the job is in the queue and has not started. This status returns 200 OK.
- IN_PROGRESS: the job started and is currently in execution. This status returns 200 OK.
- ERROR: the job was cancelled due to an error. See reason for more details. This status returns 400 Bad Request.
- FINISHED: the job successfully finished. This status returns 201 Created.
errors (object): details about the errors encountered
warning (object): details about the errors encountered
msg (string): optional message about the process execution

Example responses:

Code: 201 Created

{
    "status": "FINISHED",
    "errors": {
        "bad_categories": [4, 7],
        "empty_delivery_point_id": [2],
        "empty_id": [3, 5]
    }
}

Code: 201 Created

{
    "status": "FINISHED",
    "warnings": {
      "missing_geom": [8]
    },
    "errors": {
        "bad_categories": [4, 7],
        "empty_delivery_point_id": [2],
        "empty_id": [3, 5],
        "invalid_elements": [1]
    }
}

Code: 500 Bad Request

{
  "status": "ERROR",
  "msg": "Internal error",
}

GET /data/batch/:job_id

Check the status of a batch upload. This service makes it possible to detect errors in uploaded data and to check if any error ocurred during the upload process.

Headers parameters:

Authorization (mandatory): User's token as Bearer <token>.

Path parameters:

job_id (mandatory): The job ID given by a batch endpoint and URL encoded.

Example request URL:

/data/batch/7-2018-12-24T12%3A21%3A41Z

Response content description:

The same as in POST /data/deliveries.

Example responses:

Code: 200 OK

{
  "status": "IN_PROGRESS",
  "errors": null,
  "warnings": null
}

Code: 201 Created

{
    "status": "FINISHED",
    "warnings": {
      "missing_geom": [8]
    },
    "errors": {
        "bad_categories": [4, 7],
        "empty_delivery_point_id": [2],
        "empty_id": [3, 5],
        "invalid_elements": [1]
    }
}

POST /data/deliveries/batch

This service uploads a JSON array with all the deliveries for a depot. This endpoint is designed for large request bodies with a great number of deliveries.

Updates: If a delivery was previously uploaded, the last one remains. If a delivery changes its address and it already has a route assigned it will be rejected.

This service requieres the same parameters as POST /data/deliveries.

Example request URL:

/data/depot/7/deliveries/2018-12-21/batch

Example body:

[
  {
    "id": "32205731",
    "depot_id": "2",
    "delivery_point_id": "3737FTSO",
    "customer_phone": "086 1234567",
    "customer_name": "John McClane",
    "customer_email": "john@broccoli.com",
    "address_1": "Main Building",
    "address_2": "address2",
    "town": "City",
    "county": "County",
    "postal_code": null,
    "volume": 0.03,
    "weight": 0.2,
    "lat": 37.5,
    "lng": -6.5,
    "service_time": null,
    "after_time": "11:30:00Z",
    "before_time": null
  }
]

Example response:

Code: 202 Accepted

{
  "job_id": "7-2018-12-20T12:21:41Z",
  "message": "Deliveries uploaded"
}

DELETE /data/deliveries

Delete future (non-delivered) deliveries.

Headers parameters:

Authorization (mandatory): User's token as Bearer <token>.

Body parameters: An array with the deliveries IDs.

Example request URL:

/data/deliveries

Example body:

[
  "759283614",
  "759283616"
]

Example response:

{
  "message": "Matched deliveries successfully deleted.",
  "deleted_deliveries": ["759283614", "759283616"]
}