Routes API¶
Summary¶
Details¶
Parameters: - dc_id (string) – The dc id
- route_id (string) – The route id
- waypoint_id (string) – The waypoint id
Status Codes: - 200 OK – :ref:` The deliveries are marked for reattempt
- 401 Unauthorized – API key is invalid.
- 403 Forbidden – DC does not exist or user does not have permission to access it.
- 404 Not Found – Route, Waypoint, or one of the provided Deliveries does not exist.
Status 400 error codes
Error Code Description 3012 The route has already been finished (so more deliveries cannot be added). Example request
{ "deliveries": [ { "id": "an optional unique identifier for the reattempt", "delivery_id": "delivery_id_1234", "quantity": 33.0 }, { "delivery_id": "delivery_id_5678" } ], "time_window": { "start": 1000, "end": 5000 }, "notes": "An optional note to include" }
-
POST/dcs/(dc_id)/routes/(route_id)/waypoints/(waypoint_id)/deliveries¶ Parameters: - dc_id (string) – The dc id
- route_id (string) – The route id
- waypoint_id (string) – The waypoint id
Status Codes: - 200 OK – Delivery was added.
- 401 Unauthorized – API key is invalid.
- 403 Forbidden – DC does not exist or user does not have permission to access it.
- 404 Not Found – Route or Waypoint does not exist.
Status 400 error codes
Error Code Description 3007 Cannot import another delivery with the same id. 3012 The route has already been finished (so more deliveries cannot be added). Example request
{ "deliveries": [ { "product": "product", "quantity": 33.0, "id": "globally unique delivery id" }, { "product": "another product", "quantity": 53.0, "id": "another globally unique delivery id" } ] }
-
GET/dcs/(dc_id)/routes/(route_id)/waypoints/(waypoint_id)/deliveries¶ Parameters: - dc_id (string) – The dc id
- route_id (string) – The route id
- waypoint_id (string) – The waypoint id
Status Codes: - 200 OK – Delivery objects are returned.
- 401 Unauthorized – API key is invalid.
- 403 Forbidden – DC does not exist or user does not have permission to access it.
- 404 Not Found – Route or Waypoint does not exist.
Example Responses
{ "deliveries": [{ "id": "delivery-id-1", "name": "delivery-name-1", "quantity": 7, "attempts": [{ "attempt_status": "SUCCESSFUL", "timestamp": 1570561955123, "driver_notes": "Product Delivered" "delivery_code": "AF207", "delivery_message": "Product Delivered On Time" }, ...], }, ...], }
-
GET/dcs/(dc_id)/routes/import-status/(txid)¶ Parameters: - dc_id (string) – The dc id
- txid (string) – The transaction id returned by the add route API call
Status Codes: - 202 Accepted – The route is still being processed.
- 400 Bad Request – Route import failed. See the response for detail.
- 401 Unauthorized – API key is invalid.
- 403 Forbidden – DC does not exist or user does not have permission to access it.
- 404 Not Found – This transaction id does not exist.
Status 400 error codes
Error Code Description 3000 Import error. See the ‘errors’ field for detail. Example pending response
{ "status": "pending", "data": {} }
Example success response
{ "status": "success", "data": { "route_id": "the route id" } }
Example error response
{ "status": "error", "data": { "message": "An error occurred. See 'errors' field for detail", "code": 3000, "errors": [{ "message": "Error description" }] } }
-
GET/dcs/(dc_id)/routes/find_by_date/(date)¶ Parameters: - dc_id (string) – The dc id
- date (string) – The date in YYYY-MM-DD format
Status Codes: - 200 OK – Route is returned.
- 401 Unauthorized – API key is invalid.
- 403 Forbidden – DC does not exist or user does not have permission to access it.
Example response
{ "routes": [ { "status": "success", "data": { "route": { "id": "globally unique route id", "name": "route name", "start_time": 1510696728000, "waypoint_ids": ["wpA", "wpB"], "start_warehouse_id": "warehouse id", "end_warehouse_id": "warehouse id", "assigned_driver_id": "driver id", "vehicle_id": "vehicle id", "version": 12, "is_active": True, "is_finalized": False, "imported_timestamp": 1510696728000, "started_timestamp": 1510696728000, "finalized_timestamp": 1510696728000 } } }, ... ] }
-
PATCH/dcs/(dc_id)/routes/(route_id)/vehicle-assignment¶ Parameters: - dc_id (string) – The dc id
- route_id (string) – The route id
Request JSON Object: - vehicle_id (string) – The vehicle’s id. If the vehicle does not exist, it will be created automatically.
Status Codes: - 200 OK – Route was assigned.
- 401 Unauthorized – API key is invalid.
- 403 Forbidden – DC does not exist or user does not have permission to access it.
Example request
{ "vehicle_id": "Vehicle's id" }
-
PUT/dcs/(dc_id)/routes/(route_id)/vehicle-assignment¶ Parameters: - dc_id (string) – The dc id
- route_id (string) – The route id
Request JSON Object: - vehicle_id (string) – The vehicle’s id. If the vehicle does not exist, it will be created automatically.
Status Codes: - 200 OK – Route was assigned.
- 401 Unauthorized – API key is invalid.
- 403 Forbidden – DC does not exist or user does not have permission to access it.
Example request
{ "vehicle_id": "Vehicle's id" }
-
PATCH/dcs/(dc_id)/routes/(route_id)/driver-assignment¶ Parameters: - dc_id (string) – The dc id
- route_id (string) – The route id
Request JSON Object: - driver_id (string) – The driver’s id
Status Codes: - 200 OK – Route was assigned.
- 401 Unauthorized – API key is invalid.
- 403 Forbidden – DC does not exist or user does not have permission to access it.
- 404 Not Found – The route or driver do not exist.
Example request
{ "driver_id": "John's id" }
-
PUT/dcs/(dc_id)/routes/(route_id)/driver-assignment¶ Parameters: - dc_id (string) – The dc id
- route_id (string) – The route id
Request JSON Object: - driver_id (string) – The driver’s id
Status Codes: - 200 OK – Route was assigned.
- 401 Unauthorized – API key is invalid.
- 403 Forbidden – DC does not exist or user does not have permission to access it.
- 404 Not Found – The route or driver do not exist.
Example request
{ "driver_id": "John's id" }
-
DELETE/dcs/(dc_id)/routes/(route_id)/driver-assignment¶ Parameters: - dc_id (string) – The dc id
- route_id (string) – The route id
Status Codes: - 200 OK – Route assignment was removed.
- 401 Unauthorized – API key is invalid.
- 403 Forbidden – DC does not exist or user does not have permission to access it.
- 404 Not Found – Route does not exist.
-
GET/dcs/(dc_id)/routes/(route_id)/completion-time¶ Parameters: - dc_id (string) – The dc id
- route_id (string) – The route id
Status Codes: - 200 OK – Route Completion Time is returned.
- 401 Unauthorized – API key is invalid.
- 403 Forbidden – DC does not exist or user does not have permission to access it.
- 404 Not Found – Route does not exist.
Example response
{ "status": "success", "data": { "completion_time": { "timestamp": 1510696728000, "type": "ESTIMATED" } } }
-
PATCH/dcs/(dc_id)/routes/(route_id)/deactivate¶ Parameters: - dc_id (string) – The dc id
- route_id (string) – The route id
Status Codes: - 200 OK – Route was deactivated.
- 401 Unauthorized – API key is invalid.
- 403 Forbidden – DC does not exist or user does not have permission to access it.
- 404 Not Found – Route does not exist.
-
PUT/dcs/(dc_id)/routes/(route_id)/deactivate¶ Parameters: - dc_id (string) – The dc id
- route_id (string) – The route id
Status Codes: - 200 OK – Route was deactivated.
- 401 Unauthorized – API key is invalid.
- 403 Forbidden – DC does not exist or user does not have permission to access it.
- 404 Not Found – Route does not exist.
-
GET/dcs/(dc_id)/routes/(route_id)/waypoints/(waypoint_id)¶ Parameters: - dc_id (string) – The dc id
- route_id (string) – The route id
- waypoint_id (string) – The waypoint id
Status Codes: - 200 OK – Waypoint objects are returned.
- 401 Unauthorized – API key is invalid.
- 403 Forbidden – DC does not exist or user does not have permission to access it.
- 404 Not Found – Waypoint does not exist.
Example Responses
{ "waypoint": { "id": "the-waypoint-id", "customer_id": "the-customer-id", "status": "COMPLETED", "completed_timestamp": null, "estimated_time_of_arrival": 1570561955123, "waiting_time_seconds": 0, "waypoints_ahead": 1 } }
- Please note that the completed_timestamp, estimated_time_of_arrival and waypoints_ahead fields may be null.
- If the Waypoint status is PENDING, the completed_timestamp will be null.
- If the Waypoint status is COMPLETED, the estimated_time_of_arrival and waypoints_ahead will be null.
- The estimated_time_of_arrival may also be null in other situations. If the Waypoint’s location is unknown, or the route was just imported, the Waypoint will not have an estimated_time_of_arrival.
- If the Waypoint is next in line to be visited, waypoints_ahead will be 0.
-
POST/dcs/(dc_id)/routes/(route_id)/waypoints¶ Parameters: - dc_id (string) – The dc id
- route_id (string) – The route id
Status Codes: - 200 OK – Waypoint was added.
- 401 Unauthorized – API key is invalid.
- 403 Forbidden – DC does not exist or user does not have permission to access it.
- 404 Not Found – Route does not exist.
Status 400 error codes
Error Code Description 3006 Cannot import another waypoint with the same id. 3007 Cannot import another delivery with the same id. Example request
{ "waypoint": { "id": "globally unique waypoint id", "customer_id": "customer id", "name": "waypoint name", "address": "physical address", "location": { "latitude": 1.0, "longitude": 2.0 }, "service_time_minutes": 999, "time_windows": [{ "start": 1510864915000, "end": 1510868515000 }], "deliveries": [{ "id": "globally unique delivery id", "product": "product", "quantity": 4355.0 }] } }
-
GET/dcs/(dc_id)/routes/(route_id)/waypoints¶ Parameters: - dc_id (string) – The dc id
- route_id (string) – The route id
Status Codes: - 200 OK – Waypoint objects are returned.
- 401 Unauthorized – API key is invalid.
- 403 Forbidden – DC does not exist or user does not have permission to access it.
- 404 Not Found – Route does not exist.
Example Responses
{ "waypoints": [{ "id": "the-waypoint-id", "customer_id": "the-customer-id", "status": "COMPLETED", "completed_timestamp": null, "estimated_time_of_arrival": 1570561955123, "waypoints_ahead": 1, "waiting_time_seconds": 0, }, ...], }
- Please note that the completed_timestamp, estimated_time_of_arrival and waypoints_ahead fields may be null.
- If the Waypoint status is PENDING, the completed_timestamp will be null.
- If the Waypoint status is COMPLETED, the estimated_time_of_arrival and waypoints_ahead will be null.
- The estimated_time_of_arrival may also be null in other situations. If the Waypoint’s location is unknown, or the route was just imported, the Waypoint will not have an estimated_time_of_arrival.
- If the Waypoint is next in line to be visited, waypoints_ahead will be 0.
-
PATCH/dcs/(dc_id)/routes/(route_id)/activate¶ Parameters: - dc_id (string) – The dc id
- route_id (string) – The route id
Status Codes: - 200 OK – Route was activated.
- 401 Unauthorized – API key is invalid.
- 403 Forbidden – DC does not exist or user does not have permission to access it.
- 404 Not Found – Route does not exist.
-
PUT/dcs/(dc_id)/routes/(route_id)/activate¶ Parameters: - dc_id (string) – The dc id
- route_id (string) – The route id
Status Codes: - 200 OK – Route was activated.
- 401 Unauthorized – API key is invalid.
- 403 Forbidden – DC does not exist or user does not have permission to access it.
- 404 Not Found – Route does not exist.
-
PATCH/dcs/(dc_id)/routes/(route_id)/finish¶ Parameters: - dc_id (string) – The dc id
- route_id (string) – The route id
Status Codes: - 200 OK – :Route was finished.
- 401 Unauthorized – API key is invalid.
- 403 Forbidden – DC does not exist or user does not have permission to access it.
- 404 Not Found – Route does not exist.
Example Responses Non-errored responses will include the route id and one of the following messages: - ALREADY_FINISHED if the route was already finished before calling the endpoint - SUCCESS if the route was active when calling the endpoint and successfully was finished
{ "route_id": "a route id", "message": "ALREADY_FINISHED" }
{ "route_id": "a route id", "message": "SUCCESS" }
-
PUT/dcs/(dc_id)/routes/(route_id)/finish¶ Parameters: - dc_id (string) – The dc id
- route_id (string) – The route id
Status Codes: - 200 OK – :Route was finished.
- 401 Unauthorized – API key is invalid.
- 403 Forbidden – DC does not exist or user does not have permission to access it.
- 404 Not Found – Route does not exist.
Example Responses Non-errored responses will include the route id and one of the following messages: - ALREADY_FINISHED if the route was already finished before calling the endpoint - SUCCESS if the route was active when calling the endpoint and successfully was finished
{ "route_id": "a route id", "message": "ALREADY_FINISHED" }
{ "route_id": "a route id", "message": "SUCCESS" }
-
PATCH/dcs/(dc_id)/routes/(route_id)/start¶ Parameters: - dc_id (string) – The dc id
- route_id (string) – The route id
Status Codes: - 200 OK – :Route was started (or alreadry started).
- 401 Unauthorized – API key is invalid.
- 403 Forbidden – DC does not exist or user does not have permission to access it.
- 404 Not Found – Route does not exist.
Example Responses Non-errored responses will include the route id and one of the following messages: - ALREADY_STARTED if the route was already started before calling the endpoint - SUCCESS if the route was not yet started when calling then endpoint and was successfully started - ‘NO_DRIVER_ASSIGNED’ if the route could not be started because no driver was assigned
{ "route_id": "a route id", "message": "ALREADY_STARTED" }
{ "route_id": "a route id", "message": "SUCCESS" }
{ "route_id": "a route id", "message": "NO_DRIVER_ASSIGNED" }
-
PUT/dcs/(dc_id)/routes/(route_id)/start¶ Parameters: - dc_id (string) – The dc id
- route_id (string) – The route id
Status Codes: - 200 OK – :Route was started (or alreadry started).
- 401 Unauthorized – API key is invalid.
- 403 Forbidden – DC does not exist or user does not have permission to access it.
- 404 Not Found – Route does not exist.
Example Responses Non-errored responses will include the route id and one of the following messages: - ALREADY_STARTED if the route was already started before calling the endpoint - SUCCESS if the route was not yet started when calling then endpoint and was successfully started - ‘NO_DRIVER_ASSIGNED’ if the route could not be started because no driver was assigned
{ "route_id": "a route id", "message": "ALREADY_STARTED" }
{ "route_id": "a route id", "message": "SUCCESS" }
{ "route_id": "a route id", "message": "NO_DRIVER_ASSIGNED" }
-
DELETE/dcs/(dc_id)/routes/(route_id)¶ Note: Routes that have been analyzed or are active cannot be deleted.
Parameters: - dc_id (string) – The dc id
- route_id (string) – The route id
Status Codes: - 200 OK – Route was deleted.
- 401 Unauthorized – API key is invalid.
- 403 Forbidden – DC does not exist or user does not have permission to access it.
- 404 Not Found – Route does not exist.
Status 400 error codes
Error Code Description 3004 Cannot delete already analyzed routes. 3010 Cannot delete active routes.
-
GET/dcs/(dc_id)/routes/(route_id)¶ Parameters: - dc_id (string) – The dc id
- route_id (string) – The route id
Status Codes: - 200 OK – Route is returned.
- 401 Unauthorized – API key is invalid.
- 403 Forbidden – DC does not exist or user does not have permission to access it.
- 404 Not Found – Route does not exist.
Example response
{ "status": "success", "data": { "route": { "id": "globally unique route id", "name": "route name", "start_time": 1510696728000, "waypoint_ids": ["wpA", "wpB"], "start_warehouse_id": "warehouse id", "end_warehouse_id": "warehouse id", "assigned_driver_id": "driver id", "vehicle_id": "vehicle id", "version": 12, "is_active": True, "is_finalized": False, "imported_timestamp": 1510696728000, "started_timestamp": 1510696728000, "finalized_timestamp": 1510696728000 } } }
-
POST/dcs/(dc_id)/routes¶ This endpoint is asynchronous and will return a transaction id to be used to check the route import status.
Parameters: - dc_id (string) – The dc id
Request JSON Object: - route (json) – The route to be imported. See import route model
Status Codes: - 202 Accepted – The request to import a Route has been accepted. The returned txid should be used to poll for route import status.
- 400 Bad Request – Check error code within the response.
- 401 Unauthorized – API key is invalid.
- 403 Forbidden – DC does not exist or user does not have permission to access it.
Status 400 error codes
Error Code Description 3005 Cannot import another route with the same id. 3006 Cannot import another waypoint with the same id. 3007 Cannot import another delivery with the same id. Example request
{ "route": { "id": "globally unique route id", "name": "route name", "driver_id": "globally unique driver id", "start_time": 1510860915000, "activate_after_successful_import": true, "start_warehouse": { "id": "warehouse id", "name": "warehouse name", "address": "physical address", "location": { "latitude": 3.0, "longitude": 4.0 } }, "end_warehouse": { "id": "warehouse id", "name": "warehouse name", "address": "physical address", "location": { "latitude": 3.0, "longitude": 4.0 } }, "vehicle": { "id": "globally unique vehicle id" }, "waypoints": [{ "id": "globally unique waypoint id", "customer_id": "customer id", "name": "waypoint name", "address": "physical address", "contact_name": "John Smith", "contact_phone": "555-555-5555", "contact_email": "example-email@foxtrot.io", "location": { "latitude": 1.0, "longitude": 2.0 }, "service_time_minutes": 999, "time_windows": [{ "start": 1510864915000, "end": 1510868515000 }], "deliveries": [{ "id": "globally unique delivery id", "product": "product", "quantity": 4355.0 }] }, { "id": "globally unique waypoint id 2", "customer_id": "customer id", "name": "waypoint name", "address": "physical address", "location": { "latitude": 3.0, "longitude": 4.0 }, "service_time_minutes": 999, "time_windows": [], "deliveries": [{ "id": "delivery B", "product": "product", "quantity": 342.0 }] } ] } }
Example successful response
{ "status": "success", "data": { "txid": "the transaction id" } }
Example error response
{ "data": { "code": 3006, "message": "Cannot import another waypoint with the same id" }, "status": "error" }