Introduction
The smooth exchange of data is critical to successfully integrating key technologies into your enterprise. Wise Systems’ Autonomous Dispatch and Routing platform offers an open Application Programming Interface (API) that enables your organization to share important information across platforms.
This online documentation is the official reference for the Wise Systems API. It outlines the information your organization needs to connect the Wise Systems platform to your other systems of record. Through API calls, you can streamline data sharing across platforms, e.g., order management software, route accounting software, and ERP systems, among others. You can also manage user accounts, add new drivers to the platform, create, edit, and assign tasks (stops), dispatch routes to drivers, optimize routes in real time, and much more.
Wise's Route Planner product assigns tasks to routes and creates schedules for drivers. Earlier versions of Route Planner were called "Scheduler" and "Route Builder", and these names continue to exist in our code. You can consider descriptions of Scheduler in this document to mean Route Planner.
If you have questions about the documentation or handling integrations, contact your account manager or the Wise Systems support team.
Assumptions
Throughout this document it is assumed that the reader is well acquainted with the Wise Systems Platform. Check out the user guides here.
The API is HTTP-based
- Methods to retrieve data from the API require a GET request.
- Methods that submit data require a POST.
- Methods that change data require a PATCH.
- Methods that destroy data require a DELETE.
API Methods that require a particular HTTP method will return an error if you do not make your request with the correct one.
API Data Structure
The Wise Systems API uses the JSON (JavaScript Object Notation) payload format. Details on how JSON works can be found on the official JSON website. Libraries that convert to and from the JSON format are available for almost any programming language.
HTTP Response Codes and Errors
HTTP Status Codes
Wise Systems attempts to return appropriate HTTP status codes for every request
- 200 OK - Success
- 400 Bad Request - The request cannot be accepted; the accompanying error message explains why
- 401 Unauthorized - Authentication credentials are missing or incorrect
- 403 Forbidden - The current user's role doesn't have sufficient permissions to access the requested resource
- 404 Not Found - The URL requested is invalid or the resource requested does not exist
- 409 Conflict - The request could not be completed due to a conflict with the current state of the target resource (e.g., the task already exists in the system)
- 415 Unsupported Media Type - The request uses an unsupported
Content-Typeheader value; most endpoints requireapplication/json - 422 Invalid Data (e.g., can't find pickup location or a required field is missing)
- 500 Server Error - Something bad and unexpected happened, typically a bug or an unplanned maintenance; the Wise Systems support team is automatically alerted when this error happens but you may wish to contact them directly to provide additional details to help in the resolution (contact: support@wisesystems.com)
- 502 Bad Gateway - Wise Systems is temporarily down or being upgraded
- 503 Service Unavailable - Wise Systems servers are up, but they are overloaded with requests; try again later
Parameters Expectations
Some API methods take optional or requisite parameters. Please keep in mind that all query-string parameter values should be converted to UTF-8 and URL encoded.
Authentication
Wise Systems uses Bearer tokens passed in HTTP headers to authenticate requests. Most endpoints of the Wise Systems API require authentication and will also perform authorization checks to ensure that users can interact with the platform only according to assigned roles.
API Flows and Scenarios
Here's an introduction to the various flows used to integrate with the Wise Systems API. API workflows are generally customized based on a client's business requirements; however, below are a few common integration flows:
Authentication Flow
Wise Systems API uses Bearer tokens for authorization. After you have acquired a token, you can use it to access other protected resources.
1. Get token using username and password
def login(self, username = [username], password = [password], role = "account"):
data = {'username': username, 'password': password}
url = self.API_URL+"user/status?action=login"
self.role = role
if role == "driver":
url = self.API_URL+"driver/status?action=login"
r = requests.post(url, headers = self.JSON_HEADER, json = data, verify = True)
response = r.json()
if "access_token" in response:
self.auth = {'Authorization': str('bearer ' + response['access_token'])}
self.JSON_HEADER.update(self.auth)
self.client_id = self.getMe()['data']['client']['id']
return r.status_code, r.reason, r.text
Get token request example
{
"username": "username or email",
"password": "password"
}
Get token response example
{
"access_token": "B5FZzbGF7buiEuDlD0FeS398...",
"refresh_token": "xf4lbgLCehvhhEIJsgy0AHD...",
"expires_in": 3600,
"token_type": "bearer"
}
HTTP Request
POST https://api.wisesys.info/user/status?action=login
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| username | String | User's username or email |
| password | String | User's password |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| access_token | String | The access token is used for authentication and authorization to get access to the resources from the resource server |
| refresh_token | String | The refresh token is used to get a new access token when the old one expires; the client provides the refresh token and receives a new access token |
| expires_in | String | Token's lifetime measured in seconds |
| token_type | String | Access tokens type; always "bearer" |
2. Send subsequent requests with the header - Authorization: bearer
Authentication headers example
GET /api.wisesys.info HTTP/1.1
Content-type: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaOqsFOOwqJ
3. Access token will expire in 1 hour. Use the refresh token to update it.
HTTP Request
POST https://api.wisesys.info/user/status?action=refresh
Refresh token request example
{
"refresh_token":"iskrkWU0QqDo0..."
}
Refresh token response example
{
"access_token": "B5FZzbGF7buiEuDlD0FeS398...",
"expires_in": 3600,
"token_type": "bearer"
}
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| refresh_token | String | The refresh token is used to get a new access token when the old one expires; the client provides the refresh token and receives a new access token |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| access_token | String | The access token is used to for authentication and authorization to get access to the resources from the resource server |
| expires_in | String | Token's lifetime measured in seconds |
| token_type | String | Access tokens type; always "bearer" |
Build and Retrieve Routes Flow
These are the steps needed to plan and retrieve routes.
1. Add Tasks
There are two methods to add tasks to the system:
2. Call Schedule Task
HTTP Request
Schedule task request example
{
"date": "2019-10-03"
}
Schedule task response example
{
"Id": "8be7f220-1269-11e8-a660-c549f1991564"
}
POST https://api.wisesys.info/tasks?action=lr_schedule
SCHEDULE TASK REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| date | Date | Required; plan tasks for the specified date; the date is formatted as "YYYY-MM-DD"; example: "2019-07-04" |
SCHEDULE TASK RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | IdObject | Scheduler Task Id |
3. Retrieve Scheduled Tasks
GET /schedule/71740331-3503-1134-1922-169719251371 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
Scheduled tasks response example
{
"meta": {},
"data": [{
"driver": "2cafc9a0-3ca0-11e5-a4e2-5598a5c5072a",
"schedule": [{
"task": "34016a10-3ca0-11e5-a4e2-5598a5c5072a",
"pickupTime": "2015-06-29T16:30:00.000Z",
"deliveryTime": "2015-07-14T15:23:20.000Z"
}]
},
{
"driver": "26b777a0-3ca0-11e5-a4e2-5598a5c5072a",
"schedule": [{
"task": "34053aa0-3ca0-11e5-a4e2-5598a5c5072a",
"pickupTime": "2015-06-29T16:30:00.000Z",
"deliveryTime": "2015-07-14T15:23:20.000Z"
}]
}
]
}
Periodically invoke schedule API until the routes become available
GET https://api.wisesys.info/schedule/{id}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Job Id returned by schedule Task API |
| routeDate | Date | Optional; schedule Tasks date; the date is formatted as "YYYY-MM-DD"; example: "2019-07-04" |
RETRIEVE SCHEDULE RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | List of ScheduleTaskObject | Ordered list of drivers and their planned tasks |
4.Dispatch to Drivers
Dispatch routes response example
{
"meta": { },
"data": {
"message":"The Long Running Scheduler is now implemented."
}
}
POST https://api.wisesys.info/tasks?action=lr_accept
ACCEPT ASSIGNED RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Data | Overall result |
| data | String | Default to null |
Users
Register a user
Register a user with role (“user”, “sales”, “administrator”) in the system. These users are created for use in the web app or for programmatic access.
POST /user HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
{
"firstname": "Ali",
"lastname": "Kamil",
"username": "alikamil",
"email": [email],
"password": [password],
"roles": [
"user",
"administrator"
],
"client": "00000000-0000-0000-0000-000000000000"
}
The above command returns JSON structured like this:
{
"firstname": "Ali",
"lastname": "Kamil",
"username": "alikamil",
"email": [email],
"password": [password],
"roles": [
"user",
"administrator"
],
"client": "00000000-0000-0000-0000-000000000000"
}
HTTP Request
POST https://api.wisesys.info/user
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| firstname | String | user's first name |
| lastname | String | user's last name |
| username | String | must not already be registered in the system |
| String | must not already be registered in the system | |
| access | List of Access | User's access permissions |
| roles | list of Strings | deprecated in favor of access |
| client | UUID | client's unique Id |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | User | user's info |
User Session
POST /user/status?action=login HTTP/1.1
Accept: application/json
Content-Type: application/json
""" // login """
def login(self, username = [username], password = [password], role = "account"):
data = {'username': username, 'password': password}
url = self.API_URL+"user/status?action=login"
self.role = role
if role == "driver":
url = self.API_URL+"driver/status?action=login"
r = requests.post(url, headers = self.JSON_HEADER, json = data, verify = True)
response = r.json()
if "access_token" in response:
self.auth = {'Authorization': str('bearer ' + response['access_token'])}
self.JSON_HEADER.update(self.auth)
self.client_id = self.getMe()['data']['client']['id']
return r.status_code, r.reason, r.text
Request body JSON example for login by username
{
"username": "alikamil",
"password": "real-timerouting"
}
Request body JSON example for login by email
{
"username": "machinelearning",
"password": "gradientblue"
}
The above requests returns JSON structured like this
{
"access_token": "WBLP4sUZfg4b31oHUI7.....",
"refresh_token": "l88osCp7wRcC3bAdzs.....",
"expires_in": 3600,
"token_type": "bearer"
}
Request body example for refresh token
POST /user/status?action=refresh HTTP/1.1
Accept: application/json
Content-Type: application/json
{
"refresh_token": "iskrkWU0QqDo0..."
}
Response body example for refresh token
{
"access_token": "COzw2A6EL...",
"expires_in": 3600,
"token_type": "bearer"
}
""" // logout """
def logout(self):
url = self.API_URL+"user/status?action=logout"
r = requests.post(url, headers = self.JSON_HEADER, verify = True)
print(r.status_code, r.text)
Request body example for logout (empty JSON)
POST /user/status?action=logout HTTP/1.1
Accept: application/json
Content-Type: application/json
POST /user/status?action=reset_password HTTP/1.1
Accept: application/json
Content-Type: application/json
""" // Reset password """
def reset_password(self, email):
r = requests.post(self.API_URL + "user/status?action=reset_password",
json={"email": email}, headers=self.JSON_HEADER)
if r.status_code is not 200:
print r.status_code, r.reason
return r.json()
Request body example for reset password
{
"email": "machinelearning@wisesystems.com"
}
Manage user's session
HTTP Request
POST https://api.wisesys.info/user/status?action={action}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| action | String | Required; the actions for session management; there are four actions: "login", "refresh", "logout", "reset_password" |
| login : Get token using username and password | ||
refresh : Ask for a new token using refresh_token parameter |
||
| logout : Adjust plan for the driver by manually triggering real-time route sequence adjustments for a given driver | ||
| reset_password : Reset password request triggers an email containing a link to the web page where a password can be reset |
LOGIN REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| username | String | User's username or email |
| password | String | User's password |
LOGIN RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| access_token | String | The access token is used for authentication and authorization to get access to the resources from the resource server |
| refresh_token | String | The refresh token is used to get a new access token when the old one expires; the client provides the refresh token and receives a new access token |
| expires_in | String | Token's lifetime measured in seconds |
| token_type | String | Access tokens type; always "bearer" |
REFRESH REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| refresh_token | String | The refresh token is used to get a new access token when the old one expires; the client provides the refresh token and receives a new access token |
REFRESH RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| access_token | String | The access token is used to for authentication and authorization to get access to the resources from the resource server |
| expires_in | String | Token's lifetime measured in seconds |
| token_type | String | Access tokens type; always "bearer" |
Get User
Retrieving user info
Get User response example
GET user/7740131-1503-1124-1932-169719252271?extent=client HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
""" // get User """
def getUser(self, usr_id):
r = requests.get(self.API_URL + "user/" + usr_id, headers=self.JSON_HEADER)
if r.status_code != 200:
print(r.status_code, r.reason)
return r.json()
Get User response example
{
"meta": {},
"data": {
"firstname": "ali",
"lastname": "kamil",
"username": "alikamil",
"email": [email],
"client": "5c087850-...",
"roles": [
"user",
"administrator"
],
"id": "27331fd8-..."
}
}
HTTP Request
GET https://api.wisesys.info/user/{id}{?extent}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Id of a user. |
| extent | String | Optional; name of field which shows its detail (e.g., client) |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | User | User's info |
Update User
Update the user information.
PATCH /user/7740131-1503-1124-1932-169719252271 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
Update user request example
{
"firstname": "Keyser",
"lastname": "Sose"
}
Update user response example
{
"meta": {},
"data": {
"id": "7a740f3c-..."
}
}
HTTP Request
PATCH https://api.wisesys.info/user/{id}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Id of a user |
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| firstname | String | User's first name |
| lastname | String | User's last name |
| access | List of Access | User's access permissions |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | IdObject | Return userId upon success |
Delete User
Update the user information.
DELETE user/7740131-1503-1124-1932-169719252271 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
Delete user response example
{
"meta": {},
"data": {
"id": "7a740f3c-f503-11e4-b9b2-1697f925ec7b"
}
}
HTTP Request
DELETE https://api.wisesys.info/user/{id}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Id of a user. |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | IdObject | return userId upon success |
User Groups
User groups allow administrators to restrict or enable access to certain features of Wise Systems Products. This is especially useful for enterprise clients who want to limit access to data given to their user accounts. These customers have users that serve many types of roles in their organization and are able to represent some of that same complexity in our system.
Currently supported features:
* driver_booking : Manage the driver booking process.
* driver_management : Edit drivers.
* planning : Reassign/edit routes, run Route Planner.
* user_management : User creation/deletion/editing and permission assigning.
A user group can contain any combination of those 4 features as well as editor and viewer roles.
User group names are not case-sensitive. Admin and admin will be considered the same user group.
Create User Groups
POST /user_groups HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def add_user_groups(self, user_groups):
r = request.post("{api_url}user_groups".format(api_url=self.API_URL), headers=self.JSON_HEADER,
json=user_groups)
r.raise_for_status()
return r.json()
Request body JSON example
[
{
"name": "Sample Group",
"client_access": [
{
"client_id": "5c087850-2a99-11e5-9189-eb07c479dfd5",
"permission": [
{
"role": "editor",
"feature": "planning"
},
{
"role": "viewer",
"feature": "driver_management"
},
{
"role": "editor",
"feature": "user_management"
}
]
}
]
},
{
"name": "Multi Station Route Planner",
"client_access": [
{
"client_id": "5c087850-2a99-11e5-9189-eb07c479dfd5",
"permission": [
{
"role": "editor",
"feature": "planning"
},
{
"role": "viewer",
"feature": "driver_management"
}
]
},
{
"client_id": "00b1c42e-5f0d-472d-825a-cda5781f626b",
"permission": [
{
"role": "editor",
"feature": "planning"
}
]
}
]
}
]
Response body JSON example
{
"meta": {},
"data": {
"successes": [
{
"id": "58b09920-eb71-4792-a237-dc2a4835cc11",
"client_id": "0ec8b330-4ce4-11ea-957d-c9797b6a9c15",
"owner_id": "0f34bb70-4ce4-11ea-957d-c9797b6a9c15",
"name": "sample group",
"client_access": [
{
"client_id": "5c087850-2a99-11e5-9189-eb07c479dfd5",
"permission": [
{
"role": "editor",
"feature": "planning"
},
{
"role": "viewer",
"feature": "driver_management"
},
{
"role": "editor",
"feature": "user_management"
}
]
}
]
},
{
"id": "78645f45-7313-4d4e-86d0-0fddc25b4d28",
"client_id": "0ec8b330-4ce4-11ea-957d-c9797b6a9c15",
"owner_id": "0f34bb70-4ce4-11ea-957d-c9797b6a9c15",
"name": "multi station route planner",
"client_access": [
{
"client_id": "5c087850-2a99-11e5-9189-eb07c479dfd5",
"permission": [
{
"role": "editor",
"feature": "planning"
},
{
"role": "viewer",
"feature": "driver_management"
}
]
},
{
"client_id": "00b1c42e-5f0d-472d-825a-cda5781f626b",
"permission": [
{
"role": "editor",
"feature": "planning"
}
]
}
]
}
],
"failures": []
}
}
HTTP REQUEST
POST https://api.wisesys.info/user_groups
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| data | UserGroup[] | Array of user groups to be created |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | Object | Json object containing list of successfully created and failed groups |
Get User Groups
GET /user_groups HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def get_user_groups(self, ids=None, client_ids=None, names=None):
params = {"id[]": ids, "client_id[]": client_ids, "name[]": names}
r = request.get("{api_url}user_groups".format(api_url=self.API_URL), headers=self.JSON_HEADER,
params=params)
r.raise_for_status()
return r.json()
Response body JSON example
{
"meta": {},
"data": {
"successes": [
{
"id": "58b09920-eb71-4792-a237-dc2a4835cc11",
"client_id": "0ec8b330-4ce4-11ea-957d-c9797b6a9c15",
"owner_id": "0f34bb70-4ce4-11ea-957d-c9797b6a9c15",
"name": "sample group",
"client_access": [
{
"client_id": "5c087850-2a99-11e5-9189-eb07c479dfd5",
"permission": [
{
"role": "editor",
"feature": "planning"
},
{
"role": "viewer",
"feature": "driver_management"
},
{
"role": "editor",
"feature": "user_management"
}
]
}
]
}
],
"failures": []
}
}
HTTP REQUEST
GET https://api.wisesys.info/user_groups
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id[] | UUID[] | (Optional) Array of user group ids to retrieve |
| client_id[] | UUID[] | (Optional) Array of client ids to retrieve |
| name[] | UUID[] | (Optional) Array of user group names to retrieve |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | Object | Json object containing list of successfully retrieved and failed user groups |
Update User Groups
PATCH /user_groups HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def update_user_groups(self, user_groups):
r = request.patch("{api_url}user_groups".format(api_url=self.API_URL), headers=self.JSON_HEADER,
json=user_groups)
r.raise_for_status()
return r.json()
Request body JSON example
json [ { "id": "85cdce52-d4db-4c35-8f20-e55a6f9fe704", "name": "User Administrator", "client_access": [ { "client_id": "5c087850-2a99-11e5-9189-eb07c479dfd5", "permission": [ { "role": "editor", "feature": "user_management" } ] } ] } ]Response body JSON example
json { "meta": {}, "data": { "successes": [ { "id": "85cdce52-d4db-4c35-8f20-e55a6f9fe704", "client_id": "0ec8b330-4ce4-11ea-957d-c9797b6a9c15", "owner_id": "0f34bb70-4ce4-11ea-957d-c9797b6a9c15", "name": "user administrator", "client_access": [ { "client_id": "5c087850-2a99-11e5-9189-eb07c479dfd5", "permission": [ { "role": "editor", "feature": "user_management" } ] } ] } ], "failures": [] } }HTTP REQUEST
PATCH https://api.wisesys.info/user_groups
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| data | UserGroup[] | Array of user groups to be updated |
The required attributes for a successful update are: a valid user group id and either name, client_access, or both.
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | Object | Json object containing list of successfully updated and failed groups |
Delete User Groups
DELETE /user_groups HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
The endpoint supports group deletion in two ways: * Single group deletion
DELETE https://api.wisesys.info/user_groups/<user_group_id>
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | (Optional) |
- Multiple user group deletion
DELETE https://api.wisesys.info/user_groups/
Request body JSON example (body required)
json [ "85cdce52-d4db-4c35-8f20-e55a6f9fe704", "16545ca3-db10-4e82-a5f2-f5f970029373" ]REQUEST BODY
Parameter Type Description data UUID[] Array of user group ids to be deleted
Response body for both approaches follow the same format
#This method cover multiple user group deletion
def delete_user_groups(self, user_group_ids):
r = request.delete("{api_url}user_groups".format(api_url=self.API_URL), headers=self.JSON_HEADER, json=user_group_ids)
r.raise_for_status()
return r.json()
Response body JSON example
json { "meta": {}, "data": { "successes": [ { "id": "16545ca3-db10-4e82-a5f2-f5f970029373", "client_id": "0ec8b330-4ce4-11ea-957d-c9797b6a9c15" }, { "id": "85cdce52-d4db-4c35-8f20-e55a6f9fe704", "client_id": "0ec8b330-4ce4-11ea-957d-c9797b6a9c15" } ], "failures": [] } }
HTTP REQUEST
DELETE https://api.wisesys.info/user_groups
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | Object | Json object containing list of successfully updated and failed groups |
Associate Users to User Groups
In order to assign permissions to a specific user, we need to associate it with one or more user groups. For this, we support CREATE, GET AND DELETE endpoints for User to User Group Associations.
Create User To User Group Associations
POST /users/user_groups HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
This endpoint has 3 possible combination of parameters to create associations: * One to One (Associate one user with one user group):
POST https://api.wisesys.info/users/<user_id>/user_groups/<user_group_id>
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| users | UUID | user id to associate to the paired user group |
| user_groups | UUID | user group id to associate to the paired user |
- One to Many (Associate one user with many user groups):
POST https://api.wisesys.info/users/<user_id>/user_groups
Request body JSON example (Body is required)
[
{
"id": "0f34bb70-4ce4-11ea-957d-c9797b6a9c15"
},
{
"id": "0f4472e0-4ce4-11ea-957d-c9797b6a9c15"
}
]
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| data | Object[] | Array of Json containing the user group ids to associate with the user id. |
- Many to Many:
POST https://api.wisesys.info/users/user_groups
Request body JSON example (Body is required)
[
{
"user_id": "0f34bb70-4ce4-11ea-957d-c9797b6a9c15",
"user_group_id": "58b09920-eb71-4792-a237-dc2a4835cc11"
},
{
"user_id": "0f4472e0-4ce4-11ea-957d-c9797b6a9c15",
"user_group_id": "0ed5ee48-a238-4196-8140-0ba19516281f"
}
]
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| data | Object[] | Array of Json containing the user_id paired with the user_group_id to be associated. |
The JSON response body has the same format for either of these three approaches.
#This method covers the Many to Many approach
def add_users_to_user_groups(self, associations):
r = request.post("{api_url}users/user_groups".format(api_url=self.API_URL), headers=self.JSON_HEADER, json=associations)
r.raise_for_status()
return r.json()
Response body JSON example
{
"meta": {},
"data": {
"successes": [
{
"id": "2bc01c51-95b1-4104-a9b9-c4cf1b991ae9",
"user_group_id": "58b09920-eb71-4792-a237-dc2a4835cc11",
"user_id": "0f34bb70-4ce4-11ea-957d-c9797b6a9c15",
"owner_id": "0f34bb70-4ce4-11ea-957d-c9797b6a9c15",
"client_id": "0ec8b330-4ce4-11ea-957d-c9797b6a9c15"
},
{
"id": "da321d1d-c629-4c22-be81-0e68c7a7a2de",
"user_group_id": "0ed5ee48-a238-4196-8140-0ba19516281f",
"user_id": "0f4472e0-4ce4-11ea-957d-c9797b6a9c15",
"owner_id": "0f34bb70-4ce4-11ea-957d-c9797b6a9c15",
"client_id": "0ec8b330-4ce4-11ea-957d-c9797b6a9c15"
}
],
"failures": []
}
}
HTTP REQUEST
POST https://api.wisesys.info/users/user_groups
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | Object | Json object containing list of successfully found and failed associations |
Get User To User Group Associations
The querying options fall into three categories:
- Find User To User Group Associations:
POST /users/user_groups HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
Response body JSON example
json { "meta": {}, "data": { "successes": [ { "id": "2bc01c51-95b1-4104-a9b9-c4cf1b991ae9", "client_id": "0ec8b330-4ce4-11ea-957d-c9797b6a9c15", "owner_id": "0f34bb70-4ce4-11ea-957d-c9797b6a9c15", "user_group_id": "58b09920-eb71-4792-a237-dc2a4835cc11", "user_id": "0f34bb70-4ce4-11ea-957d-c9797b6a9c15" }, { "id": "da321d1d-c629-4c22-be81-0e68c7a7a2de", "client_id": "0ec8b330-4ce4-11ea-957d-c9797b6a9c15", "owner_id": "0f34bb70-4ce4-11ea-957d-c9797b6a9c15", "user_group_id": "0ed5ee48-a238-4196-8140-0ba19516281f", "user_id": "0f4472e0-4ce4-11ea-957d-c9797b6a9c15" } ], "failures": [] } }
def get_user_to_user_group_associations(self, client_ids=None, user_ids=None, user_group_ids=None):
params = {"client_id[]": client_ids, "user_id[]": user_ids, "user_group_id[]": user_group_ids}
r = request.get("{api_url}users/user_groups".format(api_url=self.API_URL),headers=self.JSON_HEADER,
params=params)
r.raise_for_status()
return r.json()
HTTP REQUEST
GET https://api.wisesys.info/users/user_groups
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| client_id[] | UUID | (Optional) client_id to retrieve associations from. Request supports multiple client_ids as query params |
| user_id[] | UUID | (Optional) user_group_id to retrieve associations from. Request supports multiple user_ids as query params |
| user_group_id | UUID | (Optional) user_id to retrieve associations from. Request supports multiple user_ids as query params |
Example of querying with multiple user_ids:
GET https://api.wisesys.info/users/user_groups?user_id[]=id1?user_id[]=id2&client_id[]=clientid1
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | Object | Json object containing list of successfully created and failed associations |
Find User Groups associated to one or more Users:
- Find a user group associated to an specific user:
GET https://api.wisesys.info/users/<user_id>/user_groups/<user_group_id>QUERYSTRING PARAMETERS
Parameter Type Description user_id UUID user id of the association user_group_id UUID user group id of the association - Find all user groups associated to an specific user:
GET https://api.wisesys.info/users/<user_id>/user_groups
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| user_id | UUID | user id from which to find the associations |
Find all user groups associated with a given set of users:
GET https://api.wisesys.info/user_groups?user_id[]=id1&user_id[]=id2This method supports as many user ids as needed as query params
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| user_id[] | UUID | user ids from which to find the associations |
The response body for all three variations of this category follows the same format:
Response body JSON example
{
"meta": {},
"data": {
"successes": [
{
"id": "58b09920-eb71-4792-a237-dc2a4835cc11",
"client_id": "0ec8b330-4ce4-11ea-957d-c9797b6a9c15",
"owner_id": "0f34bb70-4ce4-11ea-957d-c9797b6a9c15",
"name": "sample group",
"client_access": [
{
"client_id": "5c087850-2a99-11e5-9189-eb07c479dfd5",
"permission": [
{
"role": "editor",
"feature": "planning"
}
]
}
]
},
{
"id": "0ed5ee48-a238-4196-8140-0ba19516281f",
"client_id": "0ec8b330-4ce4-11ea-957d-c9797b6a9c15",
"owner_id": "0f34bb70-4ce4-11ea-957d-c9797b6a9c15",
"name": "sample group 2",
"client_access": [
{
"client_id": "5c087850-2a99-11e5-9189-eb07c479dfd5",
"permission": [
{
"role": "editor",
"feature": "user_management"
}
]
}
]
}
],
"failures": []
}
}
#This method finds all user groups associated to an specific user
def get_user_groups_assigned_to_user(self, user_id):
r = request.get("{api_url}users/{id}/user_groups".format(api_url=self.API_URL, id=user_id),
headers=self.JSON_HEADER)
r.raise_for_status()
return r.json()
Find Users Associated to one or more User Groups
- Find the user associated to an specific user group:
GET https://api.wisesys.info/user_groups/<user_group_id>/users/<user_id>
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| user_id | UUID | user id of the association |
| user_group_id | UUID | user group id of the association |
Find all users associated with a given user group
GET https://api.wisesys.info/user_groups/<user_group_id>/users/
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| user_id | UUID | user id of the association |
| user_group_id | UUID | user group id of the association |
Find all users associated with a given set of user groups
GET https://api.wisesys.info/user_groups/users?user_group_id[]=id1&user_group_id[]=id2This method supports as many user ids as needed as query params
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| user_group_id[] | UUID | user group ids from which to find the associations |
The response body for all three variations of this category follows the same format:
Response body JSON example
json { "meta": {}, "data": { "successes": [ { "roles": [ "user", "administrator" ], "username": "demo", "firstname": "John", "lastname": "Doe", "client": "0ec8b330-...", "email": [email], "access": [ { "roles": [ "user", "administrator" ], "_id": "5e42c9a1d3cbb838dc164291", "client": "0ec8b330-..." } ], "id": "0f34bb70-..." } ], "failures": [] } }
def get_users_assigned_to_user_group(self, user_group_id):
r = request.get("{api_url}user_groups/{id}/users".format(api_url=self.API_URL, id=user_group_id),
headers=self.JSON_HEADER)
r.raise_for_status()
return r.json()
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| user_group_id[] | UUID | (Optional) user_group_id to retrieve associations from. Request supports multiple user_ids as query params |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | Object | Json object containing list of successfully found and failed users |
Delete User To User Group Associations
Delete one association
DELETE https://api.wisesys.info/users/<user_id>/user_groups/<user_group_id>Delete all associations related to one user
DELETE https://api.wisesys.info/users/<user_id>/user_groups
def remove_user_groups_from_user(self, user_id):
r = request.delete("{api_url}users/{id}/user_groups".format(api_url=self.API_URL, id=user_id), headers=self.JSON_HEADER)
r.raise_for_status()
return r.json()
Delete all associations related to one user group
DELETE https://api.wisesys.info/user_groups/<user_group_id>/users
def remove_users_from_user_group(self, user_group_id):
r = request.delete("{api_url}user_groups/{id}/users".format(api_url=self.API_URL, id=user_group_id), headers=self.JSON_HEADER)
r.raise_for_status()
return r.json()
Delete multiple associations
DELETE https://api.wisesys.info/users/user_groups
Request body JSON example (Body required)
json [ { "client_id": "0ec8b330-4ce4-11ea-957d-c9797b6a9c15", "user_group_id": "58b09920-eb71-4792-a237-dc2a4835cc11", "user_id": "0f4472e0-4ce4-11ea-957d-c9797b6a9c15" }, { "client_id": "0ec8b330-4ce4-11ea-957d-c9797b6a9c15", "user_group_id": "0ed5ee48-a238-4196-8140-0ba19516281f", "user_id": "0f4472e0-4ce4-11ea-957d-c9797b6a9c15" } ]
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| data | Object[] | Array of Json containing the user_id, user_group_id, and the client_id related to the association. |
Response format is the same in all three cases
Response body JSON example
json { "meta": {}, "data": { "successes": [ { "client_id": "0ec8b330-4ce4-11ea-957d-c9797b6a9c15", "user_group_id": "58b09920-eb71-4792-a237-dc2a4835cc11", "user_id": "0f4472e0-4ce4-11ea-957d-c9797b6a9c15", "id": "f0611e49-449e-41d1-af5a-4179166f823d" }, { "client_id": "0ec8b330-4ce4-11ea-957d-c9797b6a9c15", "user_group_id": "0ed5ee48-a238-4196-8140-0ba19516281f", "user_id": "0f4472e0-4ce4-11ea-957d-c9797b6a9c15", "id": "38041a27-25c4-4ec4-817f-83cf21382cfb" } ], "failures": [] } }
def delete_user_group_associations(self, associations):
r = request.delete("{api_url}users/user_groups".format(api_url=self.API_URL), headers=self.JSON_HEADER, json=associations)
r.raise_for_status()
return r.json()
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | Object | Json object containing list of successfully deleted and failed associations |
Clients
List all clients
List all clients that current user has access to.
GET /clients HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
Get Clients response example
{
"meta": {
"page": 1,
"limit": 2,
"total": 32
},
"data": [{
"name": "Wise Systems",
"domain": "Wise Systems",
"id": "5c087850-2a99-11e5-9189-eb07c479dfd5"
},
{
"name": "ford",
"domain": "ford",
"id": "df879dc0-34b5-11e5-9f43-537e6f38261a"
}
]
}
HTTP REQUEST
GET https://api.wisesys.info/clients?page=0?limit=8
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| page | int | Optional; defaults to 0; the pagination offset to return |
| limit | int | Optional; defaults to 0; the pagination limit of each page |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | List of Clients | Client data |
The headers sent with GET /clients should not include the
Wise-Client-Idheader. IfWise-Client-Idis included in the headers, the result will only contain the data corresponding to that specific client. {.is-info}
Get Client Information
Get a specific client by id.
GET /client/5c087850-2a99-11e5-9189-eb07c479dfd5 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def getClient(self, clt_id):
r = requests.get(self.API_URL + "client/" + clt_id, headers=self.JSON_HEADER)
if r.status_code != 200:
print(r.status_code, r.reason)
return r.json()
Get Client response example
{
"meta": {},
"data": {
"name": "Wise Systems",
"domain": "Wise Systems",
"code": "abc",
"address": "ecbc20c0-3de7-11e5-8b33-853f5f93eb82",
"id": "5c087850-2a99-11e5-9189-eb07c479dfd5"
}
}
HTTP REQUEST
GET https://api.wisesys.info/client/client/{id}{?extent}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Id of a client |
| extent | String | Optional; name of field which shows its detail (e.g., address) |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | ClientData | Returns client data |
Set Client Level Driver Break Rules
Set Client-level Driver Break rules that will be applied to all Routes by default. Driver breaks are configured based on Driver Break rules in the Wise Systems platform. Once Route Planner runs, the Wise Systems Optimization Engine will add driver breaks to individual routes based on the break rules.
After setting client level break rules, please be sure to re-run Route Planner to generate a new route plan with inserted breaks.
PUT /client/5c087850-2a99-11e5-9189-eb07c479dfd5 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def setClientBreakRules(self, client_id, driverBreakRules):
data = {}
if driverBreakRules:
data["driverBreakRules"] = driverBreakRules
r = requests.put(self.API_URL + "client/" + client_id, headers=self.JSON_HEADER, json=data)
if r.status_code != 200:
print(r.status_code, r.reason)
return r.json()
Request JSON example
{
"driverBreakRules": [
{
"startOffsetSeconds": 30000,
"durationSeconds": 900
},
{
"startOffsetSeconds": 10000,
"durationSeconds": 300
}
]
}
Response body JSON example
{
"meta": {},
"data": {
"id": "5c087850-2a99-11e5-9189-eb07c479dfd5"
}
}
HTTP REQUEST
PUT https://api.wisesys.info/client/client/{id}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Id of a client |
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| driverBreakRules | List of driver break rules | Required; list of rules to be set as client level break rules |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data.id | UUID | id of client involved in the request |
Driver Break Rule Object
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Unique id of Driver Break rule |
| startOffsetSeconds | int | When a break should be taken, w.r.t. the start time of a route, in seconds. |
| durationSeconds | int | Duration of the break in seconds |
Drivers
Drivers are the unit workers in the Wise Systems platform. You can add drivers into the system along with their associated vehicles. All tasks originating in the system are assigned to drivers. A driver can have multiple vehicles associated in the profile, but each driver will use one vehicle at a given time for a task.
List All Drivers
GET /drivers HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
""" // Get Drivers """
def getDrivers(self, limit=1000, page=0, extents=None):
url = self.__get_request_url("drivers", limit, page, extents)
r = requests.get(url, headers=self.JSON_HEADER)
if r.status_code != 200:
print(r.status_code, r.reason)
return r.json()
Get Drivers response example
{
"meta": {
"page": 1,
"limit": 10,
"total": 32
},
"data": [
{
"id": "f98fe4af-4e4a-480c-bbf7-d266c88e5fa5",
"location": {
"lat": 42.363896537209364,
"lng": -71.08657243911952
},
"vehicle": {
"id": "djllz490-4e4a-480c-bbf7-d266c88e5fa5",
"licensePlate": "NC-1701",
"type": "truck",
"makemodel": "Ford F150",
"year": "2009",
"weightCapacity": 1000,
"volumeCapacity": 2.5,
"description": "red ford f150 with black decals"
},
"profile": {
"name": "Jean Luc Picard",
"phone": "+15552581001"
},
"props": {
"shiftTime": [
{
"start": "2015-05-16T09:00:00Z",
"end": "2015-05-16T13:00:00Z"
},
{
"start": "2015-05-16T18:00:00Z",
"end": "2015-05-16T23:00:00Z"
}
]
}
}
]
}
List all drivers in the system.
HTTP REQUEST
GET https://api.wisesys.info/drivers{?page}{?limit}{?extent}{?name}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| page | int | Optional; default: 0; the pagination offset to return; example: 0 |
| limit | int | Optional; default: 10; the pagination limit of each page; example: 8 |
| extent | String | Optional; the extended (id to detail) fields in response; example: vehicle |
| name | String | Optional; a full or partial name of the desired driver to find; example: John+Doe |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | List of Drivers | Returns available Drivers. |
Create a Driver
POST /driver HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
"""" // Create a driver """
def addDriver(self, data):
r = requests.post(self.API_URL+"driver", json=data, headers=self.JSON_HEADER)
if r.status_code is not 200:
print r.status_code, r.reason
return r.json()
Create Driver request example
{
"firstname": "Jean Luc",
"lastname": "Picard",
"telephone": "+15552581001",
"username": "+15552581001",
"password": "p@ssw03d",
"deviceType": "android",
"props": {
"shiftTimes": {
"0": [ ],
"1": [{
"duration": "PT8H",
"start": "09:00"
}],
"2": [{
"duration": "PT8H",
"start": "09:00"
}],
"3": [{
"duration": "PT8H",
"start": "09:00"
}],
"4": [ ],
"5": [ ],
"6": [ ],
}
}
}
Create a new driver in the system. The system makes the driver available for task fulfillment based on provided shift times. The driver will be initially placed at the default client location.
A driver can be set up to log in either with a username and password or with a one-time PIN associated with a phone. Their login process will differ based on the authentication type (see Driver Session section below). After a driver record is created, they will receive a text message containing a link to their respective app store (based on the provided device type) to download the application.
HTTP REQUEST
POST https://api.wisesys.info/driver
REQUEST BODY
A Driver with the following required properties
| Parameter | Type | Description |
|---|---|---|
| firstname | String | Driver's firstname |
| lastname | String | Driver's lastname |
| username | String | (Required for username login) Driver's username; must be unique |
| password | String | (Required for username login) Driver's password for login |
| telephone | String | (Required for pin login) Driver's phone number; example: "+15552581001"; must be unique |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | Driver | The system will assign a UUID to the new Driver and return it in the response |
Get Driver Information
GET driver/73740130-3503-11e4-1912-169739255978 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
""" // Get Driver info """
def getDriver(self, drv_id):
r = requests.get(self.API_URL + "driver/" + drv_id, headers=self.JSON_HEADER)
if r.status_code != 200:
print(r.status_code, r.reason)
return r.json()
Get Driver response example
{
"meta": {},
"data": {
"vehicle": {
"licensePlate": "NC-1704",
"type": "truck",
"makemodel": "Ford F150",
"year": "2009",
"weightCapacity": 1000,
"volumeCapacity": 2.5,
"description": "red ford f150 with black decals",
"id": "14f744c0-2fba-11e5-891f-9d3d0c07dabb"
},
"profile": {
"name": "Homer Kwan",
"phone": "+15552581001"
},
"props": {
"shiftTimes": {
"0": [ ],
"1": [ ],
"2": [ ],
"3": [ ],
"4": [ ],
"5": [ ],
"6": [ ],
}
},
"id": "14f7b9f0-2fba-11e5-891f-9d3d0c07dabb",
"location": {
"lat": 42.363896537209364,
"lng": -71.08657243911952
},
"assignments": [
{
"task": "14f4d3c0-2fba-11e5-891f-9d3d0c07dabb",
"location": {
"lat": 42.362153,
"lng": -71.08588
},
"id": "14ffd040-2fba-11e5-891f-9d3d0c07dabb",
"driver": "14f7b9f0-2fba-11e5-891f-9d3d0c07dabb",
"type": "delivery",
"props": {
"time": "2015-06-29T20:35:00.000Z",
"window": {
"start": "2015-06-29T20:30:00.000Z",
"end": "2015-06-29T20:50:00.000Z"
}
}
},
{
"task": "14f4d3c0-2fba-11e5-891f-9d3d0c07dabb",
"location": {
"lat": 42.362153,
"lng": -71.08588
},
"id": "14fc9bf0-2fba-11e5-891f-9d3d0c07dabb",
"driver": "14f7b9f0-2fba-11e5-891f-9d3d0c07dabb",
"type": "pickup",
"props": {
"time": "2015-06-29T16:34:41.000Z",
"window": {
"start": "2015-06-29T16:30:00.000Z",
"end": "2015-06-29T16:45:00.000Z"
}
}
}
],
"schedule": [
{
"assignment": "14ffd040-2fba-11e5-891f-9d3d0c07dabb",
"eta": "1970-01-17T15:17:13.202Z",
"status": 0
},
{
"assignment": "14fc9bf0-2fba-11e5-891f-9d3d0c07dabb",
"eta": "1970-01-17T15:17:12.108Z",
"status": 0
}
]
}
}
Get a specific driver by id and view current assignments.
HTTP REQUEST
GET https://api.wisesys.info/driver/{id}{?extent}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; driver unique Id; example: "7a740f3c-f503-11e4-b9b2-1697f925ec7b" |
| extent | String | Optional; obtain more details about a specific object within a Driver; example: "extent=vehicle" |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | Driver | The system returns driver details |
Update Driver
PATCH driver/73740130-3503-11e4-1912-169739255978 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def updateDriver(self, drv_id, data):
r = requests.patch(self.API_URL + "driver/" + drv_id, json = data,
headers = self.JSON_HEADER)
if r.status_code is not 200:
print r.status_code, r.reason
return r.status_code, r.json()
Update Driver request Example.
{
"props": {
"shiftExceptions": {
{
"2019-01-01": [{
"start": "08:00",
"duration": "PT8H"
}]
}
}
}
}
Update the driver information. For instance this can update the driver's phone number, shift times, and default vehicle.
If the update includes defaultVehicle, the system will check if another driver already specifies the same vehicle as default, and if so will reject the request with a client error.
If the update includes the eid property different from the current value, the system will try to unassign any stops assigned to the driver on the current date. This is only allowed if all of the (non-depot) stops have the non-started status, otherwise the request will be rejected with a client error regardless of any other requested updates. If successful, this will also update the driver's assigned vehicle eid to match the driver's new value.
If the update includes the props object, the following behavior takes place for each of the fields present in that object:
1) all fields included in the props object sent in the payload will get updated with the new values provided,
2) all fields excluded from the props object sent in the payload (but that are present in the existing driver.props object) will have those original values retained (instead of being removed altogether from the object). So, the new props object does not fully overwrite the existing props object.
3) there is existing backwards-compatibility logic that converts the provided shiftTime into daily shiftTimes (in the case where the latter is not provided in the update).
Note that the shiftTime property in props is deprecated. The shiftTimes property is the correct one for updating shifts.
HTTP REQUEST
PATCH https://api.wisesys.info/driver/{id}
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | Driver | Returns the updated driver object |
Remove Driver
DELETE driver/73740130-3503-11e4-1912-169739255978 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def deleteDriver(self, drv_id):
r = requests.delete(self.API_URL + "driver/" + drv_id, headers=self.JSON_HEADER)
if r.status_code is not 200:
print(r.status_code, r.reason)
return r.json()
Remove a driver from the system. This call will fail if the driver has active assignments.
HTTP REQUEST
DELETE https://api.wisesys.info/driver/{Id}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required. Driver unique Id; example: "7a740f3c-f503-11e4-b9b2-1697f925ec7b" |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | IdObject | Returns the deleted driver's unique Id |
Get Driver Assignments
GET driver/73740130-3503-11e4-1912-169739255978 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def getDriverAssignments(self, drv_id):
url = self.__get_request_url("driver/" + drv_id + "/assignments", 99, 1, ["location"])
r = requests.get(url, headers=self.JSON_HEADER)
if r.status_code != 200:
print(r.status_code, r.reason)
return r.json()
Get Driver assignments response example
{
"meta": {
"page": 0,
"limit": 3,
"total": 32
},
"data": [
{
"id": "7b7g0f2c-g523-11f4-c9h4-1697f925ec7b",
"type": "delivery",
"location": "16e5b1d0-3bf0-11e5-9206-1324edd52c4d",
"contact": {
"name": "Homer Kwan",
"phone": "+15552581001"
},
"props": {
"time": "2015-06-20T16:34:41.000Z",
"window": {
"start": "2015-06-20T16:34:41.000Z",
"end": "2015-06-20T16:34:41.000Z"
}
},
"task": "84788f56-c617-4c2b-8677-53de01fb47fe",
"driver": "7a740f3c-f503-11e4-b9b2-1697f925ec7b",
"eta": "PT10M36S",
"status": 3
}
]
}
Get all assignments for a specific driver
HTTP REQUEST
GET https://api.wisesys.info/driver/{Id}/assignments{?page}{?limit}{?extent}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; driver unique Id; example: "7a740f3c-f503-11e4-b9b2-1697f925ec7b" |
| page | int | Optional; default: 0; the pagination offset to return; example: 0 |
| limit | int | Optional; default: 10; the pagination limit of each page; example: 8 |
| extent | String | Optional; the extended (details) fields in response; example: location or task |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | List of Assignments | Assignments associated with the driver |
Bulk Create Driver Assignments
POST driver/73740130-3503-11e4-1912-169739255978 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def addDriverAssignments(self, drv_id, asgns):
r = self.SESSION.post(self.API_URL + "driver/" + drv_id + "/assignments", json={"tasks": asgns},
headers=self.JSON_HEADER)
if r.status_code != 200:
print r.status_code, r.reason
return r.json()
{
"tasks": [
{
"id": "4193ab21-8fd9-11e5-9112-1143e1274f81",
"pickupTime": 1509557365
},
{
"id": "4193ab22-8fd9-11e5-9112-1143e1274f80",
"deliveryTime": 1509557365
}
]
}
Create Driver assignments response example
{
"meta": {
},
"data": [
"assignments": [
{
"id": "7b7g0f2c-g523-11f4-c9h4-1697f925ec7b",
"type": "delivery",
"location": "16e5b1d0-3bf0-11e5-9206-1324edd52c4d",
"contact": {
"name": "Homer Kwan",
"phone": "+15552581001"
},
"props": {
"time": "2015-06-20T16:34:41.000Z",
"window": {
"start": "2015-06-20T16:34:41.000Z",
"end": "2015-06-20T16:34:41.000Z"
}
},
"task": "4193ab22-8fd9-11e5-9112-1143e1274f80",
"driver": "7a740f3c-f503-11e4-b9b2-1697f925ec7b",
"eta": "PT10M36S",
"status": 3
}
],
"unassignedTasks": [
"4193ab21-8fd9-11e5-9112-1143e1274f81"
]
]
}
Bulk assign a set of tasks to a given driver. Only include pickupPosition/deliveryPosition if you previously received them from the suggest driver API. One or both may be included depending on task type (pickup/delivery/two-way). If insertion positions are included the system will try to insert the assignments in the corresponding positions in the driver's schedule; otherwise it will pick the best place automatically.
The response will include the IDs of tasks that couldn't get assigned, if any.
HTTP REQUEST
POST https://api.wisesys.info/driver/{Id}/assignments{?page}{?limit}{?extent}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; driver unique Id; example: "7a740f3c-f503-11e4-b9b2-1697f925ec7b" |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | Object | Contains successful assignments under assignments and failed task IDs under unassignedTasks. |
Schedule Adjustment
PUT /driver/73740130-3503-11e4-1912-169739255978/assignments HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
""" // Schedule adjustment"""
def adjust_schedule(self, drv_id):
r = requests.put(self.API_URL + "driver/" + drv_id + "/assignments?action=adjust_schedule",
headers = self.JSON_HEADER)
if r.status_code != 200:
self.notify("Failed when calling Adjust Schedule: " + r.text)
return r.status_code, r.text
""" // Ignore RTA"""
def ignoreRTA(self, drv_id):
r = requests.put(self.API_URL + "driver/" + drv_id + "/assignments?action=ignore_rta",
headers=self.JSON_HEADER)
if r.status_code != 200:
self.notify("Failed when calling Ignore RTA: "+r.text)
return r.json()
With ignore_rta disables automatic real-time adjustment until an assignment is completed or removed from driver's schedule (unless RTA is completely disabled for the driver's vehicle with enableRta=false).
With adjust_schedule requests a manual RTA, unless it's disabled for the driver's vehicle (in which case a client error is returned in the response). This action is similar to Manual Sequencing, except that there's no ability to "lock" the first few stops (note that the first stop will always remain in place so as not to cause drastic route changes for the driver). The process could take a few seconds, so the schedule will be updated asynchronously after the API responds.
HTTP REQUEST
PUT https://api.wisesys.info/driver/{Id}/assignments?action=[ignore_rta|adjust_schedule]
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; driver unique Id |
| action | enum | Required; can be one of ignore_rta or adjust_schedule |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | Data | driver's unique Id |
Driver Report
GET driver/73740130-3503-11e4-1912-169739255978/report/2020-10-10 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
""" // Manual sequencing """
def getDriverReport(self, drv_id, date):
r = requests.get(self.API_URL + "driver/" + drv_id + "/report/" + date,
headers=self.JSON_HEADER)
if r.status_code != 200:
self.notify("Failed when calling Get Driver Report: "+r.text)
return r.json()
Get a driver's report for a specified day. Response contains the following data:
planned: the planned route (eg. StartDay); null if not found
projected: most recent plan; null if not found
current: most recent route data; null if not found
swipe_accuracy: between 0 and 1, represents the percent of completed stops that are rapid swipes; null if no completed stops on route
accept_reject: list containing accept/reject data; empty list if no accept/reject data found
route_date: date of the route
Note that accept_reject data will not contain data from RTA runs without corresponding responses, or responses of type result_not_found
This report only includes data from after the most recent Start Day event.
HTTP REQUEST
GET https://api.wisesys.info/driver/{Id}/report/{date}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; driver unique Id |
| date | String | Required; date to get report for, format: YYYY-MM-DD |
Get Driver Report response example
{
"meta": {},
"data": {
"swipe_accuracy": 0.95,
"route_date": "2020-11-24",
"current": {
"travel_time": 1230,
"service_time": 456,
"waiting_time": 0,
"distance": 2000,
"delays": 1,
"num_stops": 2,
"stops": [
{
"violatedTW": false,
"departureTime": 1495021803000,
"delay": 0,
"task": "73491600-3b0e-11e7-98c8-8f452a766311",
"pickupTime": 1495016291000,
"delayFlag": -1,
"waitingTime": 2509000,
"travelTimeFromPrevious": 1091000,
"startServiceTime": 1495018800000,
"distanceToNext": 7448,
"distanceFromPrevious": 1122000,
"demandViolated": false,
"travelTimeToNext": 8750,
"deliveryTime": 1495016291000,
"hardTWViolated": false
},
{
"violatedTW": false,
"departureTime": 1495025577000,
"delay": 0,
"task": "752ace50-3b0e-11e7-98c8-8f452a766311",
"pickupTime": 1495022925000,
"delayFlag": 0,
"waitingTime": 0,
"travelTimeFromPrevious": 1122000,
"startServiceTime": 1495022925000,
"distanceToNext": 7820,
"distanceFromPrevious": 855000,
"demandViolated": false,
"travelTimeToNext": 7448,
"deliveryTime": 1495022925000,
"hardTWViolated": false
}
],
"timestamp": "2020-11-24T11:00:00.000Z"
},
"projected": {
"travel_time": 1250,
"service_time": 400,
"waiting_time": 10,
"distance": 2100,
"delays": 0,
"num_stops": 2,
"stops": [
{
"violatedTW": false,
"departureTime": 1495021803000,
"delay": 0,
"task": "73491600-3b0e-11e7-98c8-8f452a766311",
"pickupTime": 1495016291000,
"delayFlag": -1,
"waitingTime": 2509000,
"travelTimeFromPrevious": 1091000,
"startServiceTime": 1495018800000,
"distanceToNext": 7448,
"distanceFromPrevious": 1122000,
"demandViolated": false,
"travelTimeToNext": 8750,
"deliveryTime": 1495016291000,
"hardTWViolated": false
},
{
"violatedTW": false,
"departureTime": 1495025577000,
"delay": 0,
"task": "752ace50-3b0e-11e7-98c8-8f452a766311",
"pickupTime": 1495022925000,
"delayFlag": 0,
"waitingTime": 0,
"travelTimeFromPrevious": 1122000,
"startServiceTime": 1495022925000,
"distanceToNext": 7820,
"distanceFromPrevious": 855000,
"demandViolated": false,
"travelTimeToNext": 7448,
"deliveryTime": 1495022925000,
"hardTWViolated": false
}
],
"timestamp": "2020-11-24T10:25:00.000Z"
},
"planned": {
"travel_time": 1000,
"service_time": 300,
"waiting_time": 20,
"distance": 1500,
"delays": 0,
"num_stops": 2,
"stops": [
{
"violatedTW": false,
"departureTime": 1495021803000,
"delay": 0,
"task": "73491600-3b0e-11e7-98c8-8f452a766311",
"pickupTime": 1495016291000,
"delayFlag": -1,
"waitingTime": 2509000,
"travelTimeFromPrevious": 1091000,
"startServiceTime": 1495018800000,
"distanceToNext": 7448,
"distanceFromPrevious": 1122000,
"demandViolated": false,
"travelTimeToNext": 8750,
"deliveryTime": 1495016291000,
"hardTWViolated": false
},
{
"violatedTW": false,
"departureTime": 1495025577000,
"delay": 0,
"task": "752ace50-3b0e-11e7-98c8-8f452a766311",
"pickupTime": 1495022925000,
"delayFlag": 0,
"waitingTime": 0,
"travelTimeFromPrevious": 1122000,
"startServiceTime": 1495022925000,
"distanceToNext": 7820,
"distanceFromPrevious": 855000,
"demandViolated": false,
"travelTimeToNext": 7448,
"deliveryTime": 1495022925000,
"hardTWViolated": false
}
],
"timestamp": "2020-11-24T06:00:00.000Z"
},
"accept_reject": [
{
"rta_timestamp": "2020-11-24T10:45:00.000Z",
"time_on_road_before": 2000,
"travel_time_before": 1000,
"service_time_before": 700,
"waiting_time_before": 0,
"delay_time_before": 300,
"distance_before": 10000,
"delays_before": 0,
"num_stops_before": 2,
"time_on_road_after": 1900,
"travel_time_after": 1000,
"service_time_after": 900,
"waiting_time_after": 0,
"delay_time_after": 0,
"distance_after": 9000,
"delays_after": 0,
"num_stops_after": 2,
"response_type": "accept",
"response_timestamp": 1605728829000,
"rta_id": "ed81cbdb-28be-489c-bebb-09ee4bca4f95"
}
]
}
}
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | ReportResponse | Returns an object with planned, projected, and current route data, as well as swipe_accuracy, route_date, and accept_reject data. |
Manual Sequencing
PUT driver/73740130-3503-11e4-1912-169739255978/manual_sequence HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
""" // Manual sequencing """
def manualSequenceImpact(self, drv_id, data):
r = requests.patch(self.API_URL + "driver/" + drv_id + "/manual_sequence?action=calculate_impact",
json=data, headers=self.JSON_HEADER)
if r.status_code != 200:
self.notify("Failed when calling Patch Manual Sequence Impact: "+r.text)
return r.json()
JSON Example Without Optional Querystring Parameters
{
"order": [
"e35b1da0-8d8e-11e5-8d65-ff1945e720c1"
],
"reasoncode": "R01"
}
JSON Example With Optional Querystring: action = calculate_impact
{
"meta": {},
"data": {
"delayedAssignments": [
{
"id": "70a3c908-f502-11e4-b9b2-1697f925ec7b"
},
{
"id": "80a4c308-f502-11e4-b9b2-1697f925ec7b"
},
{
"id": "40a2c102-g209-21fgb9b2-1697f925ec7b"
}
],
"changedDistance": 24,
"changedTime": 22
}
}
Set the next stop(s) in the driver's schedule for the day. The system will lock these stops at the beginning of the schedule in exactly the same order as specified by the order property and create an optimal schedule for the remaining assignments on the driver’s schedule. The body of the request is the IDs of the to-be-locked assignments. The user can first calculate the impact of the manual sequence by calling this with action=calculate_impact, which returns a list of assignments that will be delayed along with the increase in miles and minutes of the new schedule.
With an empty assignment list, this also works to "resync" the schedule, that is, recalculate the optimal sequence, discarding any previous manual adjustments. For convenience the adjust_schedule action in Schedule Adjustment has the same effect.
The actual change to the schedule is made with no action specified and a reason code in the body.
Note that this action overrides the vehicle's enableRta=false property - that is, it may still modify the schedule even if automatic RTA is disabled.
HTTP REQUEST
PUT https://api.wisesys.info/driver/{Id}/manual_sequence[?action=calculate_impact]
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; driver unique Id |
| action | String | Optional; if calculate_impact, calculate the impact of the manual change to the sequence |
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| order | List of UUID | Required; list of one or more Assignments to be assigned to the target Driver (in the given sequence) |
| reasoncode | ReasonCode | Optional |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | SequenceResponse | Returns a list of assignments that will be delayed along with the increase in miles and minutes of the new schedule |
Insert Driver Breaks
POST driver/73740130-3503-11e4-1912-169739255978/breaks HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
""" // Break insertion """
def insert_breaks(self, drv_id, breakRules=None):
data = {}
if breakRules:
data["breakRules"] = breakRules
r = self.SESSION.post(self.API_URL + "driver/" + drv_id + "/breaks",
headers=self.JSON_HEADER, json=data)
if r.status_code != 200:
print(r.status_code, r.reason, r.json())
return r.status_code, r.json()
Request body JSON example
{
"breakRules": [
{
"startOffsetSeconds": 3600,
"endOffsetSeconds": 0,
"durationSeconds": 1800,
"isMandatory": true
}
]
}
Inserts break(s) to driver's schedule according to the specified break rule(s).
HTTP REQUEST
POST https://api.wisesys.info/driver/{Id}/breaks
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; driver unique Id |
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| breakRules | List of BreakRule | Required; list of one or more break rules |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | Data | driver's unique Id |
Insert Driver Breaks After Specified Time
POST driver/73740130-3503-11e4-1912-169739255978/breaks?ruleType=startsAfter HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
""" // Break insertion after specified time """
def insert_breaks_start_time(self, drv_id, breakRules=None):
data = {}
if breakRules:
data["breakRulesByStartTime"] = breakRules
r = self.SESSION.post(self.API_URL + "driver/" + drv_id + "/breaks?ruleType=startsAfter",
headers=self.JSON_HEADER, json=data)
if r.status_code != 200:
print(r.status_code, r.reason, r.json())
return r.status_code, r.json()
Request body JSON example
{
"breakRulesByStartTime": [
{
"startsAfter": 1682618400000,
"duration": 1800
}
]
}
Inserts break(s) to driver's schedule after specified time according to the break rule(s).
HTTP REQUEST
POST https://api.wisesys.info/driver/{Id}/breaks?ruleType=startsAfter
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; driver unique Id |
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| breakRulesByStartTime | List of BreakRuleByStartTime | Required; list of one or more break rules |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | Data | driver's unique Id |
Update Driver Break by Assignment Id
PATCH driver/73740130-3503-11e4-1912-169739255978/breaks?ruleType=startsAfter HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
""" // Update break by assignment Id """
def update_break(self, drv_id, assignment_id=None,data={}):
if assignment_id:
data["assignmentId"] = assignment_id
r = self.SESSION.patch(self.API_URL + "driver/" + drv_id + "/breaks?ruleType=startsAfter", headers=self.JSON_HEADER, json=data)
if r.status_code != 200:
print(r.status_code, r.reason, r.json())
return r.status_code, r.json()
Request body JSON example
{
"assignmentId":"2csd7a47-d249-404a-8b03-2783kq924278",
"startsAfter":1685618969654, // epoch ms
"duration":1800 // seconds
}
Update driver's existing break by assignment Id.
HTTP REQUEST
PATCH https://api.wisesys.info/driver/{Id}/breaks?ruleType=startsAfter
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; driver unique Id |
| ruleType | String | Required; ruleType has to be startsAfter; example: ruleType==startsAfter |
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| breakUpdateRules | List of BreakUpdateRule | Required; list of one or more break rules |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | Data | driver's unique Id |
Remove Driver Breaks
DELETE driver/73740130-3503-11e4-1912-169739255978/breaks HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
""" // Break deletion """
def remove_breaks(self, drv_id, assignmentIds=None):
data = {}
if assignmentIds:
data["assignmentIds"] = assignmentIds
r = self.SESSION.delete(self.API_URL + "driver/" + drv_id + "/breaks",
headers=self.JSON_HEADER, json=data)
if r.status_code != 200:
print(r.status_code, r.reason, r.json())
return r.status_code, r.json()
Request body JSON example with optional parameter
{
"assignmentIds": ["2csd7a47-d249-404a-8b03-2783kq924278", "2cad7a47-d249-404a-8b03-2783jj924279"]
}
Removes all break(s) from driver's schedule if assignmentIds are not provided. Otherwise, only removes breaks from specified assignments.
HTTP REQUEST
DELETE https://api.wisesys.info/driver/{Id}/breaks
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; driver unique Id |
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| assignmentIds | List of UUID | Optional; list of one or more assignment(s) from which the break(s) must be removed. |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | Data | driver's unique Id |
Delete Driver Assignments
Bulk-delete all assignments (assigned tasks) for a specific driver.
DELETE driver/73740130-3503-11e4-1912-169739255978 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
""" // Delete Driver Assignments """
def delete_driver_assignments(self, drv_id):
r = requests.delete(self.API_URL + "driver/" + drv_id + "/assignments",
headers=self.JSON_HEADER)
if r.status_code != 200:
print(r.status_code, r.reason)
return r.json()
HTTP REQUEST
DELETE https://api.wisesys.info/driver/{Id}/assignments{?page}{?limit}{?extent}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; driver unique Id; example: "7a740f3c-f503-11e4-b9b2-1697f925ec7b" |
Associate Active Vehicle To Driver
- this method is deprecated - see Associate Default Vehicle To Driver > Associate vehicle request example
PATCH driver/7a740f3c-f503-11e4-b9b2-1697f925ec7b/vehicle HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
""" // Associate Vehicle to driver """
def addVehicleToDriver(self, drv_id, data):
r = requests.patch(self.API_URL + "driver/" + drv_id + "/vehicle", json=data,
headers=self.JSON_HEADER)
if r.status_code is not 200:
print r.status_code, r.reason
return r.json()
{
"id":"45ba38a4-f8e9-11e4-a322-1697f925ec7b"
}
Associate vehicle response example
{
"meta": {
"status": 0,
"message": "The resource was assigned successfully"
},
"data": {
"id": "7a740f3c-f503-11e4-b9b2-1697f925ec7b"
}
}
An existing vehicle is associated to a specific driver as their active vehicle. If the vehicle id is not found, the system will return an error.
If the vehicle id is already associated to a driver, this call will disassociate the vehicle and associate it to the new driver. A vehicle can be disassociated from a driver and associated to another driver only if the original driver is not active in the system.
PATCH https://api.wisesys.info/driver/{id}/vehicle
Associate Default Vehicle To Driver
Associate default vehicle request example
PATCH driver/7a740f3c-f503-11e4-b9b2-1697f925ec7b/update_default_vehicle HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
""" // Associate Vehicle to driver """
def addVehicleToDriver(self, drv_id, data):
r = requests.patch(self.API_URL + "driver/" + drv_id + "/update_default_vehicle", json=data,
headers=self.JSON_HEADER)
if r.status_code is not 200:
print r.status_code, r.reason
return r.json()
// option 1
{
"defaultVehicle":"45ba38a4-f8e9-11e4-a322-1697f925ec7b"
}
// option 2
// with no data to unassign the drivers defaultVehicle
{}
Associate vehicle response example
// option 1
{
"meta": {
"status": 0,
"message": "The resource was assigned successfully"
},
"data": {
"items":[{driver1...}, {driver2...}]
}
}
// option 2
{
"meta": {
"status": 0,
"message": "The resource was assigned successfully"
},
"data": {
"items":[{driver1...}]
}
}
An existing vehicle is associated to a specific driver as their default vehicle. If the vehicle id is not found, the system will return an error.
If the default vehicle id is already associated to a driver, this call will disassociate the vehicle and associate it to the new driver.
PATCH https://api.wisesys.info/driver/{id}/defaultVehicle
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; driver unique Id; example: "7a740f3c-f503-11e4-b9b2-1697f925ec7b" |
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; vehicle unique Id; example: "7a740f3c-f503-11e4-b9b2-1697f925ec7b" |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | The returned meta data |
| data | Id | Returns driver's unique Id |
Update Driver Location
PATCH driver/73740130-3503-11e4-1912-169739255978/location HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def updateDriverLocation(self, drv_id, data):
r = requests.patch(self.API_URL + "driver/" + drv_id + "/location", json=data,
headers=self.JSON_HEADER)
if r.status_code != 200:
print(r.status_code, r.reason)
return r.status_code, r.text
Update Driver Location request Example
{
"lat": 42.362153,
"lng": -71.08588,
"speed": 10,
"direction": 90,
"timestamp": "2015-08-13T21:00:00.000Z"
}
Updates the location of the driver. The driver must have an active vehicle associated. The system will recalculate all stop ETAs based on the submitted location.
PATCH https://api.wisesys.info/driver/{id}/location
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; driver unique Id; example: "7a740f3c-f503-11e4-b9b2-1697f925ec7b" |
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| lat | float | The latitude of the location's coordinates |
| lng | float | The longitude of the location's coordinates |
| speed | int | Optional; speed measured in m/s |
| direction | int | Optional; course in degrees clockwise, starting from North |
| timestamp | DateTime | Optional; the date and time when the Driver Location was last modified; useful if the status update happened in the past (e.g., the location update was locally saved to the phone and then sent to Wise Systems when the connection was re-established) |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | The returned meta data |
| data | Id | Returns the driver's unique Id |
Batch Driver Location Update
PATCH driver/73740130-3503-11e4-1912-169739255978/locations HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def batchUpdateDriverLocations(self, drv_id, data):
r = requests.patch(self.API_URL + "driver/" + drv_id + "/locations", json=data,
headers=self.JSON_HEADER)
if r.status_code != 200:
print(r.status_code, r.reason)
return r.json()
Update Driver Locations request example
[
{
"lat": 42.362153,
"lng": -71.08588,
"speed": 10,
"direction": 90,
"timestamp": "2015-08-13T21:00:00.000Z"
},
{
"lat": 42.362152,
"lng": -71.085881,
"speed": 0,
"direction": 91,
"timestamp": "2015-08-13T21:01:00.000Z"
},
{
"lat": 42.362152,
"lng": -71.085883,
"speed": 5,
"direction": 130,
"timestamp": "2015-08-13T21:02:00.000Z"
}
]
Adds multiple location updates to the system for a driver. The driver must have an active vehicle associated. The system will record all valid locations, but only use the latest one for the purposes of recalculating stop ETAs.
PATCH https://api.wisesys.info/driver/{id}/locations
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; driver unique Id; example: "7a740f3c-f503-11e4-b9b2-1697f925ec7b" |
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| lat | float | The latitude of the location's coordinates |
| lng | float | The longitude of the location's coordinates |
| speed | int | Optional; speed measured in m/s |
| direction | int | Optional; course in degrees clockwise, starting from North |
| timestamp | DateTime | Optional; the date and time when the Driver Location was last modified; useful if the status update happened in the past (e.g., the location update was locally saved to the phone and then sent to Wise Systems when the connection was re-established) |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | The returned meta data |
| data | Id | Returns driver's unique Id |
Update Location of Multiple Drivers
PATCH https://api.wisesys.info/drivers/location
Update location of multiple drivers. Each driver must exist in the system and have an active vehicle associated. The system will record all valid locations, but only use the latest one for the purposes of recalculating stop ETAs.
IMPORTANT NOTES
- Locations of maximum 50 drivers can be updated at a time
- No driver location will be updated if any data is in the request body is invalid. For example, if 50 driver locations were sent and one of them is an invalid data, the entire request will be rejected and no driver locations will be updated
REQUEST BODY
Payload: A list of DriverLocation
- DriverLocation
| Parameter | Type | Description |
|---|---|---|
| driverId | uuid | Id of the driver |
| location | object | New location of the driver |
- Location
| Parameter | Type | Description |
|---|---|---|
| lat | float | The latitude of the location's coordinates |
| lng | float | The longitude of the location's coordinates |
| speed | int | Optional; speed measured in m/s |
| direction | int | Optional; course in degrees clockwise, starting from North |
| timestamp | DateTime | Optional; the date and time when the Driver Location was last modified; useful if the status update happened in the past (e.g., the location update was locally saved to the phone and then sent to Wise Systems when the connection was re-established) |
RESPONSE BODY
- Payload
| Parameter | Type | Description |
|---|---|---|
| meta | Object | Metadata of the response |
| data | Object | Empty on success and errors on invalid requests |
- Meta
| Parameter | Type | Description |
|---|---|---|
| status | ResultStatusCode | Result status code of the response |
| message | String | message explaining the status |
STATUS CODE
- 200 OK: Drivers' locations were updated successfully
- 400 Bad Request: Invalid request body was sent
- 413 Payload Too Large: More than 50 driver locations were sent
- 403 Forbidden: The role of the API caller was a driver or sales
- 422 Unprocessable Entity: One or more of the given drivers do not exist or do not have an associated active vehicle
Examples
PATCH drivers/location HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
PATCH /drivers/location
[
{
"driverId": "a03e5852-e9dd-46b4-b3a9-1ba261c5f3c1",
"location": {
"lat": 42.362153,
"lng": -71.08588,
"speed": 10,
"direction": 90,
"timestamp": "2022-02-07T10:00:00.000Z"
}
},
{
"driverId": "86041cc5-6ce6-4a21-af55-e3278337be71",
"location": {
"lat": 39.362153,
"lng": -12.08588,
"speed": 211,
"direction": 30,
"timestamp": "2022-02-07T07:00:00.000Z"
}
}
]
PATCH /drivers/location 200 OK
{
"meta": {
"status": 0,
"message": "Locations of the drivers have been updated successfully"
},
"data": {}
}
PATCH /drivers/location 400 Bad Request
{
"meta": {
"status": 1,
"message": "Invalid request body. Request body does not respect the api specification"
},
"data": {
"errors": [
"There must be at least 1 or more driver locations in the request body",
"One or more driver ids are not valid UUIDs",
"One or more drivers do not have a location defined",
"One or more drivers' locations do not have latitude or longitude defined",
"One or more drivers' locations have invalid latitude",
"One or more drivers' locations have invalid logitude",
"One or more drivers' locations have invalid speed",
"One or more drivers' locations have invalid direction",
"One or more drivers' locations have invalid timestamp",
]
}
}
PATCH /drivers/location 403 Forbidden
{
"meta": {
"status": 8,
"message": "The API user does not have sufficient privilege"
},
"data": {}
}
PATCH /drivers/location 413 Payload Too Large
{
"meta": {
"status": 1,
"message": "Request body payload exceeded a limit of 50 driver locations"
},
"data": {}
}
PATCH /drivers/location 422 Unprocessable Entity
{
"meta": {
"status": 3,
"message": "One or more given drivers either do not exist or do not have an associated active vehicle"
},
"data": {
"nonExistentDriverIds": [
"a55f61cd-54a3-45ac-a9b2-91ae14346fe3",
"10e9c3a3-698d-48dd-9e6d-a17ccbf336ab"
],
"driversWithoutActiveVehicle": [
"9703f954-5c20-4cab-855a-90a049199879"
]
}
}
Driver Session
Request body JSON example for login by driver's username
POST /driver/status?action=login HTTP/1.1
Accept: application/json
Content-Type: application/json
{
"username": "alikamil",
"password": "real-timedynamic"
}
Request body JSON example for login by driver's telephone
""" // login using telephone """
def loginPin(self, telephone):
data = {'telephone': telephone}
url = self.API_URL+"driver/status?action=login"
r = requests.post(url, headers = self.JSON_HEADER, json = data, verify = True)
response = r.json()
data["pin"] = response["data"]["pin"]
url = self.API_URL+"driver/status?action=verify"
r = requests.post(url, headers = self.JSON_HEADER, json = data, verify = True)
response = r.json()
self.auth = 'Bearer ' + response['token']['access_token']
self.JSON_HEADER.update({'Authorization': str(self.auth)})
return r.status_code, r.reason, r.text
{
"telephone": "+15552581001"
}
Login response example
{
"access_token": "WBLP4sUZfg4b31oHUI7.....",
"refresh_token": "l88osCp7wRcC3bAdzs.....",
"expires_in": 3600,
"token_type": "bearer"
}
Request body JSON example for refresh token
POST /user/status?action=refresh HTTP/1.1
Accept: application/json
Content-Type: application/json
{
"refresh_token": "iskrkWU0QqDo0..."
}
Refresh token response example
{
"access_token": "COzw2A6EL...",
"expires_in": 3600,
"token_type": "bearer"
}
Request body JSON example for logout (empty JSON)
{
}
Request body JSON example for driver password reset
{
"telephone": "+15552581001"
}
Request body JSON example for logout (empty JSON)
{
}
Request body JSON example for re-send pin
{
"telephone": "+15552581001"
}
Response body JSON example for re-send pin
{
"message": "Pin Has Been Sent"
}
If the driver's account is set up to log in with a phone number, the driver will receive a text message upon first login attempt containing a PIN to verify their phone device. Upon successful verification the device session will last for six months.
It’s possible to re-request a verification PIN for an existing driver account.
For drivers with a username and password log in method the process works the same way as for web users. (See the section at the beginning of the document.)
A reset password request triggers an email containing a link to the web page where a password can be reset.
POST https://api.wisesys.info/driver/status?action={action}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| action | String | Required; the actions for session management; there are four actions: "login", "refresh", "logout", "reset_password" |
| login : Get token using username and password | ||
| refresh : Ask for a new token using refresh_token parameter | ||
| logout : Adjust the plan for a given driver by manually triggering a real-time adjustment | ||
| reset_password : Reset password request triggers an email containing a link to the web page where a password can be reset | ||
| resend_pin : Request a verification PIN for an existing driver account |
LOGIN REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| username | String | User's username or email |
| password | String | User's password |
| telephone | String | (For login via pin number) Driver's telephone number |
LOGIN RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| access_token | String | The access token is used to for authentication and authorization to get access to the resources from the resource server |
| refresh_token | String | The refresh token is used to get a new access token when the old one expires; the client provides the refresh token and receives a new access token |
| expires_in | String | Token's lifetime measured in seconds |
| token_type | String | Access tokens type; always "bearer" |
REFRESH REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| refresh_token | String | The refresh token is used to get a new access token when the old one expires; the client provides the refresh token and receives a new access token |
REFRESH RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| access_token | String | The access token is used to for authentication and authorization to get access to the resources from the resource server |
| expires_in | String | Token's lifetime measured in seconds |
| token_type | String | Access tokens type; always "bearer" |
RESEND PIN REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| telephone | String | Driver's phone number; example: "+15552581001" |
REFRESH RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| message | String | Confirmation message |
Route Log
Route logs provide a history of a driver’s route-- including non-applied (eg. suggested) changes to the route. To get the actual history of the route, filter out the route_logs with applied==false, or request the logs with applied=true.
If a driver’s route was created via Driver Start Day, Driver Assignment Completion, or Route Planner Dispatch, a StartDay route log will be created for that driver. New route logs are created whenever changes are made to that driver’s routes. Possible route modifying events are AutoRTA, ManualRTA, ManualSeq, and AssignmentComplete.
GET drivers/routelog/2019-10-03/ HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
""" // Route Log"""
def get_route_log(self, date, route_log_type=None, sub_type=None, page=0, limit=10, applied=True):
"""
:param date: YYYY-MM-DD
:param route_log_type: "Custom", "Wise", "Driver"
:param sub_type: "StartDay", "AutoRTA", "ManualRTA", "ManualSeq", "AssignmentComplete", "PreRTA", "RtaResponse"
:param page: The pagination offset to return
:param limit: The pagination limit of each page
:param applied: Whether logs represent a change in the route (True for applied, False for non-applied, None
for both)
:return: full route log for the date
"""
url = self.API_URL + "drivers/routelog/{}".format(date)
params = {
"applied": applied,
"limit": limit,
"page": page
}
if route_log_type:
params["type"] = route_log_type
if sub_type:
params["subType"] = sub_type
r = requests.get(url, params=params, headers=self.JSON_HEADER)
if r.status_code != 200:
print(r.status_code, r.reason)
return r.json()
Route Log response example
{
"meta": {},
"data": [
[
{
"total_delay": 400,
"driver_id": "c6c5c5e0-1668-11e8-af75-fbb2952db10a",
"number_of_unassigned_tasks": 0,
"total_travel_time": 6202,
"id": "246bc5a0-1669-11e8-af75-fbb2952db10a",
"eta_type": "Mixed",
"number_of_extra_needed_vehicles": 0,
"time_on_road": 26476,
"user_id": "c6c5c5e0-1668-11e8-af75-fbb2952db10a",
"total_waiting_time": 0,
"number_of_open_routes": 1,
"stops": [
{
"departureTime": 1519150119000,
"task": "depot1",
"pickupTime": 1519150119,
"deliveryTime": 1519150119
},
{
"hardTWViolated": false,
"departureTime": 1519151457000,
"task": "f9ddc270-1668-11e8-af75-fbb2952db10a",
"demandViolated": false,
"startServiceTime": 1519150816000,
"violatedTW": false,
"travelTimeFromPrevious": 1175,
"travelTimeToNext": 0,
"delay": 0,
"waitingTime": 0,
"delayFlag": 0,
"deliveryTime": 1519150816,
"pickupTime": 1519150816,
"distanceToNext": 0,
"distanceFromPrevious": 7209
},
{
"hardTWViolated": false,
"departureTime": 1519152794000,
"task": "fab9f1a0-1668-11e8-af75-fbb2952db10a",
"demandViolated": false,
"startServiceTime": 1519151783000,
"violatedTW": false,
"travelTimeFromPrevious": 0,
"travelTimeToNext": 659,
"delay": 0,
"waitingTime": 0,
"delayFlag": 0,
"deliveryTime": 1519151783,
"pickupTime": 1519151783,
"distanceToNext": 4294,
"distanceFromPrevious": 0
},
{
"departureTime": 1519176595000,
"task": "depot2",
"pickupTime": 1519176595,
"deliveryTime": 1519176595
}
],
"total_meters": 31018,
"number_of_violated_tw": 1,
"type": "Wise",
"total_service_time": 20274,
"number_of_violated_hard_tw": 1,
"number_of_tasks": 18,
"sub_type": "StartDay",
"route_date": "2040-07-04",
"created_at": "2040-07-04T18:09:07.323Z",
"route_id": "4d012700-15c2-11e8-948e-e178b3822e53",
"eid": "1",
"applied": true,
"response_type": null,
"response_timestamp": null,
"rta_id": null
}
]
]
}
Get route logs for all drivers for a specific date
GET https://api.wisesys.info/drivers/routelog{date}/{?type}{?subType}{?page}{?limit}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| date | String | Required; date of the route logs formated as "YYYY-MM-DD"; example: "2019-07-04" |
| type | String | Optional; type of route logs; example: type=Driver |
| subType | String | Optional; SubType of route logs; example: sub_type==AssignmentComplete |
| page | int | Optional; defaults to 0; the pagination offset to return |
| limit | int | Optional; default to 10; the pagination limit of each page |
Driver Logs
GET driver/73740130-3503-11e4-1912-169739255978/routelog/2019-10-03/ HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
""" // Drivers Log """
def get_driver_route_log(self, driver_id, date, route_log_type=None, sub_type=None, page=0, limit=10, applied=True):
"""
:param driver_id: uuid for the driver
:param date: YYYY-MM-DD
:param route_log_type: "Custom", "Wise", "Driver"
:param sub_type: "StartDay", "AutoRTA", "ManualRTA", "ManualSeq", "AssignmentComplete", "PreRTA", "RtaResponse"
:param page: The pagination offset to return
:param limit: The pagination limit of each page
:param applied: Whether logs represent a change in the route (True for applied, False for non-applied, None
for both)
:return: driver route log for the date provided
"""
url = self.API_URL + "driver/{}/routelog/{}".format(driver_id, date)
params = {
"applied": applied,
"limit": limit,
"page": page
}
if route_log_type:
params["type"] = route_log_type
if sub_type:
params["subType"] = sub_type
r = requests.get(url, params=params, headers=self.JSON_HEADER)
if r.status_code != 200:
print(r.status_code, r.reason)
return r.json()
Driver Logs response example
{
"meta": {},
"data": [
{
"total_delay": 0,
"driver_id": "7dabb070-1269-11e8-a660-c549f1991564",
"number_of_unassigned_tasks": 0,
"total_travel_time": 1839,
"id": "8be7f220-1269-11e8-a660-c549f1991564",
"eta_type": "Mixed",
"number_of_extra_needed_vehicles": 0,
"time_on_road": 3639,
"user_id": "7dabb070-1269-11e8-a660-c549f1991564",
"total_waiting_time": 0,
"number_of_open_routes": 1,
"stops": [
{
"departureTime": 1518710506000,
"task": "depot1",
"pickupTime": 1518710506,
"deliveryTime": 1518710506
},
{
"hardTWViolated": false,
"departureTime": 1518711573000,
"task": "7dee37b0-1269-11e8-a660-c549f1991564",
"demandViolated": false,
"startServiceTime": 1518710973000,
"violatedTW": false,
"travelTimeFromPrevious": 534,
"travelTimeToNext": 0,
"delay": 0,
"waitingTime": 0,
"delayFlag": 0,
"deliveryTime": 1518710973,
"pickupTime": 1518710973,
"distanceToNext": 0,
"distanceFromPrevious": 2070
},
{
"hardTWViolated": false,
"departureTime": 1518712330000,
"task": "7df93430-1269-11e8-a660-c549f1991564",
"demandViolated": false,
"startServiceTime": 1518711730000,
"violatedTW": false,
"travelTimeFromPrevious": 0,
"travelTimeToNext": 467,
"delay": 0,
"waitingTime": 0,
"delayFlag": 1,
"deliveryTime": 1518711730,
"pickupTime": 1518711730,
"distanceToNext": 3330,
"distanceFromPrevious": 0
},
{
"hardTWViolated": false,
"departureTime": 1518713355000,
"task": "7de0a320-1269-11e8-a660-c549f1991564",
"demandViolated": false,
"startServiceTime": 1518712755000,
"violatedTW": false,
"travelTimeFromPrevious": 467,
"travelTimeToNext": 573,
"delay": 0,
"waitingTime": 0,
"delayFlag": 0,
"deliveryTime": 1518712755,
"pickupTime": 1518712755,
"distanceToNext": 2837,
"distanceFromPrevious": 3330
},
{
"departureTime": 1518714145000,
"task": "depot2",
"pickupTime": 1518714145,
"deliveryTime": 1518714145
}
],
"total_meters": 11722,
"number_of_violated_tw": 0,
"type": "Wise",
"total_service_time": 1800,
"number_of_violated_hard_tw": 0,
"number_of_tasks": 3,
"sub_type": "StartDay",
"route_date": "2040-07-04",
"created_at": "2040-07-04T16:01:56.292Z",
"route_id": "068d2b10-1262-11e8-bd4c-0f5fadabc812",
"eid": "17",
"applied": true,
"response_type": null,
"response_timestamp": null,
"rta_id": null
}
]
}
Get route logs for a specific driver by id and date.
GET https://api.wisesys.info/driver/{id}/routelog/{date}/{?type}{?subType}{?page}{?limit}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required. Driver unique Id; example: "7a740f3c-f503-11e4-b9b2-1697f925ec7b" |
| date | String | Required; eate of the route logs formated as "YYYY-MM-DD"; example: "2019-07-04" |
| type | String | Optional; type of route logs; example: type=Driver |
| subType | String | Optional; SubType of route logs; example: sub_type==AssignmentComplete |
| page | int | Optional; defaults to 0; the pagination offset to return |
| limit | int | Optional; default to 10; the pagination limit of each page |
| sortdir | String | Optional; default to ASC; the order in which to return the route logs based on log creation time |
End Route
POST /driver/73740130-3503-11e4-1912-169739255978/endroute HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
""" // End Route"""
def end_route(self, driver_id, timestamp=None):
"""
:param driver_id: string
:param timestamp: ISO datetime string
"""
url = self.API_URL + "driver/{}/endroute".format(driver_id)
if timestamp:
body = {"timestamp": timestamp}
else:
body = {}
r = requests.post(url, json=body, headers=self.JSON_HEADER)
if r.status_code != 200:
print(r.status_code, r.reason)
return r.json()
End route response example
{
"meta": {},
"data": {
"message": "Driver route ended"
}
}
Indicate driver route completion
POST https://api.wisesys.info/driver/{id}/endroute
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Driver id |
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| timestamp | DateTime | Optional; if the request was delayed (e.g. due to lack of connectivity) indicates the actual time the route ended |
Driver Migration
Driver Migration in Wise Systems platform represents an attempt to migrate a driver from one client space to another.
Execute a Driver Migration
POST https://api.wisesys.info/driver-migration
Initiating driver migration triggers the following operations:
- A driver will be moved from one client space to a new client space
- If the driver has a vehicle assigned, the vehicle will be moved to the new client space as well
- If a depot id was provided, the start/end depot of the vehicle will be set to this depot.
- If no depot id was provided, the start/end depot of the vehicle will be set to the default depot of the new client space
- If the driver does not have a vehicle assigned, the depot id will be ignored even if it was provided
- Live driver state in the system will be moved to the new client space if the driver has a vehicle assigned
- Any system failure during one of this operations will trigger a full rollback of the migration
NOTE: The driver must not have any outstanding incomplete assignments when being migrated.
REQUEST BODY
Payload
| Parameter | Type | Description |
|---|---|---|
| driverId | uuid | Id of the driver to migrate |
| newClientId | uuid | Id of the new client space to which the driver will be migrated |
| newDepotId | uuid | Optional; Id of the new start/end depot of the vehicle that is assigned to the driver |
RESPONSE BODY
- Payload
| Parameter | Type | Description |
|---|---|---|
| meta | Object | Metadata of the response |
| data | Object | Data of the response; See below for its structure |
- Meta
| Parameter | Type | Description |
|---|---|---|
| status | ResultStatusCode | Result status code of the response |
| message | String | message explaining the status |
- Data on valid request
| Parameter | Type | Description |
|---|---|---|
| id | uuid | Id of the driver migration |
| driverId | uuid | Id of the driver to migrate |
| vehicleId | uuid | Optional; Id of the vehicle that is assigned to the driver |
| oldClientId | uuid | Id of the old client space from which the driver is migrated |
| newClientId | uuid | Id of the new client space to which the driver is migrated |
| success | boolean | Indicates whether the driver migration was successful |
NOTE: If success is false, this means there was an unexpected error in the system during the driver migration operation, and the migration was fully rolled back. The API User can retry the migration with the same payload.
- Data on invalid request
| Parameter | Type | Description |
|---|---|---|
| errors | array |
A list of errors in string |
STATUS CODE
- 201 Created: Driver migration operation is finished. It could have either succeeded or failed.
- 400 Bad Request: Invalid request body was sent
- 403 Forbidden:
- The role of the API caller was a driver or sales
- The api caller does not have access to the new client space to which the driver is to be migrated
- 422 Unprocessable Entity:
- The driver with the given id does not exist in the system
- The driver being migrated already exists in the new client space
- The vehicle that is assigned to the driver does not exist in the system
- The specified or default depot to be assigned as start/end depot of the driver's vehicle does not exist in the system
- The driver does not have a location update and the target client depot has no address or address with no location coordinates
- The driver has incomplete assignments
Examples
POST /driver-migration HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
POST /driver-migration
{
"driverId": "8375dbac-920c-4a1e-9a82-1acf0fbf1831",
"newClientId": "73dc45bc-6082-450f-abd5-f595ab8bb6bd",
"newDepotId": "9552ad5d-8c19-4d28-ac89-4f247cd29af0" // optional
}
POST /driver-migration 201 Created
{
"meta": {
"status": 0,
"message": ""
},
"data": {
"driverId": "8375dbac-920c-4a1e-9a82-1acf0fbf1831",
"vehicleId": "02c28b62-5329-4f9c-8ba6-6afe4432a4b7", // optional
"oldClientId": "970bda8e-a4c2-4f6b-9250-662d20522521",
"newClientId": "73dc45bc-6082-450f-abd5-f595ab8bb6bd",
"success": true
}
}
POST /driver-migration 400 Bad Request
{
"meta": {
"status": 1,
"message": "Invalid request body. Request body does not respect the api specification"
},
"data": {
"errors": [
"Request body is missing or has an invalid structure",
"driverId is missing",
"driverId is an invalid uuid",
"newClientId is missing",
"newClientId is an invalid uuid",
"newDepotId is an invalid uuid"
]
}
}
POST /driver-migration 403 Forbidden
{
"meta": {
"status": 8,
"message": "The API user does not have sufficient privilege"
},
"data": {}
}
POST /driver-migration 403 Forbidden
{
"meta": {
"status": 8,
"message": "The API user does not have access to the specified client space"
},
"data": {}
}
POST /driver-migration 422 Unprocessable Entity
{
"meta": {
"status": 3,
"message": "Unprocessable data was provided"
},
"data": {
"errors": [
"The given driver does not exist in the system",
"The given driver already exists in the new client space",
"The vehicle of the driver does not exist in the system",
"The specified or default depot of the new client space does not exist in the system",
"The given driver has not-started and/or in-progress assignments",
"The given driver does not have a location update. The default location could not be assigned to the driver, because the depot of the new client space does not have an address or address coordinates"
]
}
}
Driver Shift Start
Register Driver's Shift Start
POST /shiftstart
Examples
POST /shiftstart HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
POST /shiftstart
{
"driverId": "329a336e-9f1a-4639-be89-30355be0dd6d",
"timestamp": "2023-05-15T04:30:00Z"
}
201 Created
{
"meta": {
"status": 0,
"message": ""
},
"data": {
"id": "e1e77d0e-3095-4a97-8f0e-507fdeccba7b",
"driverId": "329a336e-9f1a-4639-be89-30355be0dd6d",
"timestamp": "2023-05-15T04:30:00Z"
}
}
400 Bad Request
{
"meta": {
"status": 1,
"message": "Invalid request body. Request body does not respect the api specification"
},
"data": {
"errors": [
"Request body is missing or has an invalid structure",
"driverId is missing",
"driverId is an invalid uuid",
"timestamp is missing",
"timestamp is not in a valid UTC ISO 8601 format"
]
}
}
422 Unprocessable Entity
{
"meta": {
"status": 3,
"message": "Unprocessable data was provided"
},
"data": {
"errors": [
"The given driver does not exist in the system",
"The given driver has already started a shift"
]
}
}
REQUEST BODY
| Parameter | Type | Description | Limitation | Required |
|---|---|---|---|---|
| driverId | string | Id of the driver in Wise | Must be a valid UUID. Cannot be longer than 128 characters | Yes |
| timestamp | DateTime | Time of driver's shift start | Must be a UTC 8601 format ex) 2023-05-15T04:30:00Z | Yes |
RESPONSE BODY
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Refer to the link |
| data | ShiftStart | Refer to the link |
HTTP Status Codes
- 201 Created: Driver's shift start has successfully been registered in the system
- 400 Bad Request: Malformed request body has been received. Refer to the tables above for more detail
- 422 Unprocessable Entity:
- Driver does not exist in the system
- Shift start of the driver with the given id has already been registered
Note
In order to delete the existing shift start of a driver, end of shift must be registered for the driver and the shift must be ended
ShiftStart Resource
| Parameter | Type | Description |
|---|---|---|
| id | string | Id of the shift start registration |
| driverId | string | Id of the driver whose shift has started |
| timestamp | DateTime | Time of driver's shift start in UTC |
Driver Shift End
Register Driver's Shift End
POST /shiftend
Examples
POST /shiftend HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
POST /shiftend
{
"driverId": "329a336e-9f1a-4639-be89-30355be0dd6d",
"lastAssignmentId": "e1cc98a4-95d5-4fff-9ca7-ef2751220f78",
"timestamp": "2023-05-15T04:30:00Z"
}
201 Created
{
"meta": {
"status": 0,
"message": ""
},
"data": {
"id": "fa4edc52-c97f-4ea8-81bd-017e7751e438",
"driverId": "329a336e-9f1a-4639-be89-30355be0dd6d",
"lastAssignmentId": "e1cc98a4-95d5-4fff-9ca7-ef2751220f78",
"clientId": "e1cc98a4-95d5-4fff-9ca7-ef2751220f78",
"approvedAt": "2023-05-15T04:30:00Z"
}
}
400 Bad Request
{
"meta": {
"status": 1,
"message": "Invalid request body. Request body does not respect the api specification"
},
"data": {
"errors": [
"Request body is missing or has an invalid structure",
"driverId is missing",
"driverId is an invalid uuid",
"lastAssignmentId is missing",
"lastAssignmentId is an invalid uuid",
"timestamp is missing",
"timestamp is not in a valid UTC ISO 8601 format"
]
}
}
422 Unprocessable Entity
{
"meta": {
"status": 3,
"message": "Unprocessable data was provided"
},
"data": {
"errors": [
"The given driver does not exist in the system",
"The given driver has already ended a shift",
"The assignment with the given lastAssignmentId does not exist in the system",
"The given last assignment is already complete. It must be an incomplete assignment"
]
}
}
REQUEST BODY
| Parameter | Type | Description | Limitation | Required |
|---|---|---|---|---|
| driverId | string | Id of the driver in Wise | Must be a valid UUID. Cannot be longer than 128 characters | Yes |
| lastAssignmentId | string | Id of the last assignment in Wise that the driver is going to perform to end his/her shift | Must be a valid UUID. Cannot be longer than 128 characters | Yes |
| timestamp | DateTime | Time the driver's end of shift was initiated | Must be a UTC 8601 format ex) 2023-05-15T04:30:00Z | Yes |
RESPONSE BODY
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Refer to the link |
| data | ShiftEnd | Refer to the link |
HTTP Status Codes
- 201 Created: Driver's shift end has successfully been registered in the system
- 400 Bad Request: Malformed request body has been received. Refer to the tables above for more detail
- 422 Unprocessable Entity:
- Driver with the given id does not exist in the system
- Shift end of the driver has already been registered
- Assignment with the given
lastAssignmentIddoes not exist in the system - Assignment with the given
lastAssignmentIdis already complete
Note
Only one ShiftEnd can be registered at a time per driver. In order to register another ShiftEnd, current
existing driver's shift must be ended by calling PATCH /shiftend or must be
unregistered by calling DELETE /shiftend
Retrieve a Driver's Shift
GET /shiftend/{shiftend_id}
Examples
GET /shiftend/329a336e-9f1a-4639-be89-30355be0dd6d HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
200 Ok
{
"meta": {
"status": 0,
"message": ""
},
"data": {
"id": "329a336e-9f1a-4639-be89-30355be0dd6d",
"driverId": "41c53d28-7f51-466f-a37d-4f86c7b6101c",
"lastAssignmentId": "e1cc98a4-95d5-4fff-9ca7-ef2751220f78",
"clientId": "e1cc98a4-95d5-4fff-9ca7-ef2751220f78",
"time": "2023-05-15T04:30:00Z"
}
}
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| id | string | Id of the `ShiftEnd` in Wise |
Response Body
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Refer to the link |
| data | ShiftEnd | Refer to the link |
HTTP Status Codes
- 200 Ok:
ShiftEndwith the given id was found and returned - 400 Bad Request:
- No
ShiftEndid path parameter was specified
- No
- 404 Not Found:
ShiftEndwith the given id was not found in the system
Ending a Driver's Shift
PATCH /shiftend
PATCH /shiftend HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
Examples
PATCH /shiftend
{
"driverId": "329a336e-9f1a-4639-be89-30355be0dd6d",
"endTime": "2023-05-15T04:30:00Z"
}
202 Accepted
{
"meta": {
"status": 0,
"message": ""
},
"data": {}
}
400 Bad Request
{
"meta": {
"status": 1,
"message": "Invalid request body. Request body does not respect the api specification"
},
"data": {
"errors": [
"Request body is missing or has an invalid structure",
"driverId is missing",
"driverId is an invalid uuid",
"endTime is missing",
"endTime is not in a valid UTC ISO 8601 format"
]
}
}
422 Unprocessable Entity
{
"meta": {
"status": 3,
"message": "Unprocessable data was provided"
},
"data": {
"errors": [
"The given driver does not exist in the system"
]
}
}
REQUEST BODY
| Parameter | Type | Description | Limitation | Required |
|---|---|---|---|---|
| driverId | string | Id of the driver in Wise | Must be a valid UUID. Cannot be longer than 128 characters | Yes |
| endTime | DateTime | Time the driver's shift ended | Must be a UTC 8601 format ex) 2023-05-15T04:30:00Z | Yes |
RESPONSE BODY
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Refer to the link |
| data | object | Empty Object |
HTTP Status Codes
- 202 Accepted: Driver's shift has successfully been ended
- 400 Bad Request:
driverIdis missingdriverIdis not a validUUIDendTimeis missingendTimeis not a valid UTC 8601 format
- 422 Unprocessable Request:
- Driver with the given
driverIddoes not exist in the system - Given
endTimeis before theShiftStartthat was registered by POST /shiftstart
- Driver with the given
Delete a Driver's ShiftEnd by Driver Id
DELETE /shiftend?driverId={driverId}
Examples
DELETE /shiftend?driverId=329a336e-9f1a-4639-be89-30355be0dd6d HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
200 Ok
{
"meta": {
"status": 0,
"message": ""
},
"data": {}
}
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| driverId | string | Id of the driver in Wise |
Response Body
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Refer to the link |
| data | object | Empty Object |
HTTP Status Codes
- 200 Ok:
ShiftEndwith the given driver id was found and successfully deleted
ShiftEnd Resource
| Parameter | Type | Description |
|---|---|---|
| id | string | Id of shift end registration |
| driverId | string | Id of the driver in Wise |
| lastAssignmentId | string | Id of the last assignment in Wise that the driver is going to perform to end his/her shift |
| timestamp | DateTime | Time the driver's end of shift was initiated |
Driver Shifts
Get Driver's Shifts
GET /shifts
Examples
GET /shifts HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
GET /shifts?minStart=2023-05-15T00:00:00Z&page=0&limit=2
200 Ok
{
"meta": {
"status": 0,
"message": ""
},
"data": [
{
"id": "d432a368-7d66-4708-9e2c-c2b4ce9e4691",
"driverId": "837d6535-adfe-4760-9b5f-4d66c1d82518",
"start": "2023-05-05T09:00:00Z",
"end": "2023-05-05T17:00:00Z"
},
{
"id": "5d519772-3fb1-4e0d-be88-33c18bd23a59",
"driverId": "80f18fbc-06f4-4387-a142-7173d317909c",
"start": "2023-05-05T07:00:00Z",
"end": "2023-05-05T15:00:00Z"
}
]
}
400 Bad Request
{
{
"meta": {
"status": 1,
"message": "Invalid query string values. Query string values do not respect the api specification"
},
"data": {
"errors": [
"minStart is not in a valid UTC ISO 8601 format"
]
}
}
}
Query String Parameters
| Parameter | Type | Description | Limitation | Required |
|---|---|---|---|---|
| minStart | Date | Minimum start date of the shifts to be queried. For example, if `minStart` is `2023-05-15T00:00:00Z`, then all shifts whose start time is `2023-05-15T00:00:00Z` or later will be returned | Must be a UTC 8601 format ex) 2023-05-15T04:30:00Z | No |
| page | number | Page number of the `Shifts` being queried. If page is `1` and limit is `50`, the second 50 `Shifts` will be returned in the response (since `page` starts at `0`) | Unsigned Integer. `page` starts at 0 | No |
| limit | number | The maximum number of `Shifts` to be returned per request | Unsigned Integer. The maximum value is 100. Any value greater will be rounded down to 100 | No |
Response Body
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Refer to the link |
| data | Array of Shift | List of `Shift` that matches the query received in the request |
HTTP Status Codes
- 200 Ok: Request was successfully processed and
Shiftsmatching the query were returned - 400 Bad Request:
minStartis not in a valid UTC ISO 8601 format
Shift Resource
| Parameter | Type | Description |
|---|---|---|
| id | string | Id of the Shift in Wise |
| driverId | string | Id of the driver in Wise |
| start | Date | Start of the shift in UTC ISO 8601 format |
| end | Date | End of the shift in UTC ISO 8601 format |
Custom Form
Create Forms
API Endpoint:
POST /forms?clientId=:clientId
Examples
POST /forms?clientId=:clientId
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
POST /forms?clientId=:clientId
Request JSON example
{
"title": "Form title",
"category": String
"questions":[
{
"title": "Question title",
"type": "text",
"isRequired": boolean
}
]
}
200 Ok
{
"meta": {},
"data": {
"message": "The form requested has been created successfully",
"form": {
"id": "ddb96117-501a-42e9-b2fb-44a1135969ec",
"clientId": "5c087850-2a99-11e5-9189-eb07c479dfd5",
"title": "First Staging Form",
"status": "active",
"updatedAt": "2023-08-14T12:28:57.458Z",
"createdAt": "2023-08-14T12:28:57.458Z",
"category": null
}
}
}
403 Unauthorized
{
"code": 8,
"error": "Unauthorized",
"message": ""
}
400 Bad Request
{
"code": 3,
"error": "Invalid data",
"message": "Unexpected token } in JSON at position 143"
}
Query String Parameters
| Parameter | Type | Description |
|---|---|---|
| clientId | UUID | Unique Client ID |
The logic for adding or updating a form will be as follows
In order to create a new form we need at least a form title, questions along with its type if numeric or text, and a client Id, for whom the form will be created. While creating a form, the API will
- Mark a previous form as inactive
- Insert a record in the form table and get the formId
- Will now mark each previous question as inactive
- Insert each question with reference to new formId
Acceptance Criteria
- A form with new questions should be created in the database with the status active for both form and questions.
- Old forms and old questions should be marked as inactive in the database for this clientId.
- Write required functional and unit test cases.
[Note] - If the category field is not mentioned It will be applied to all types of assignments.
Get Driver Forms
A driver with assignments could be able to fetch all the forms along with responses if any for their existing assignments. Note: This API can only be accessed with a driver’s authorization.
API Endpoint:
GET /forms/drivers
Return an empty array in case any forms could not be found for this driver.
Implementation Logic
Fetching a form is associated with a driverId, hence requiring a driverId to fetch a form.
While fetching a form using a driverId
- Fetch client Id
- Fetch the assignmentIds using driverId
- For each assignment check if a response exists
- If no response fetches the active form by client Id along with questions and pushes it to the forms array for all the assignments with no response with assignmentId
- If response - trace back to formId and fetch the accurate form and push it to the forms array along with assignmentId
Tracing
- By assingmentId get response Id
- By responseId get questionId if a response is not found get the active form for the client
- By questionId get formId / form
- Response for a questionId either can be found or not found based on if already been responded to by the driver.
- If responded we'll mark submitted=true at the form level object above
- If Not responded we'll mark the submitted false
Examples
GET /forms/drivers
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
GET /forms/drivers
200 Ok
{
"meta":{},
"data": [
{
"id": "1fb73b5b-e8a2-4733-87cc-ee5e8eea2806",
"assignmentId": "1fb73b5b-e8a2-4733-87cc-ee5e8eea2886",
"title": "form title", // nullable
"category": "form category", // nullable
"isSubmitted": true,
"questions": [
{
"id": "1fb73b5b-e8a2-4733-87cc-ee5e8eea2806",
"title": "Did you meet the recipient?",
"type": "text",
"isRequired":true,
"response": "Yes" // nullable
},
{
"id": "1fb73b5b-e8a2-4733-87cc-ee5e8eea2806",
"title": "What is the temperature of the shipment?",
"type": "number",
"isRequired":false,
"response": null // nullable
}
]
}
]
}
403 Unauthorized
{
"code": 8,
"error": "Unauthorized",
"message": ""
}
Submit Forms
Drivers' applications should be able to submit responses for a form. This API will be able to submit responses for a single form or form multiple forms.
API Endpoint:
PUT /forms/responses
Examples
PUT /forms/responses
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
PUT /forms/responses
Request JSON example
{
"responses": [
{
"assignmentId": "1fb73b5b-e8a2-4733-87cc-ee5e8eea2808I",
"formId": "1fb73b5b-e8a2-4733-87cc-ee5e8eea2808J",
"responses": [
{
"questionId": "1fb73b5b-e8a2-4733-87cc-ee5e8eea2808K",
"response": "response string or number",
"submittedAt": "2020-11-24T06:00:00.000Z"
},
{
"questionId": "1fb73b5b-e8a2-4733-87cc-ee5e8eea2808L",
"response": "response string or number",
"submittedAt": "2020-11-24T06:00:00.000Z"
}
]
}
]
}
200 Ok
{
"meta": {
"status": 0,
"message": null
},
"data": {
"message":"Responses have been saved successfully.",
"errors":[ // if error saving any assignment
{
assignmentId:"1fb73b5b-e8a2-4733-87cc-ee5e8eea2808L",
message:"One compulsory question missing."
}
],
"success": [
{
"assignmentId": "6857df9a-0b2a-4a94-8236-a98acb34e01b",
"message": "Response was updated or created successfully"
}
]
}
}
The logic for response submission
While submitting response
- - Validate if the request object has responses to all the required questions.
- - By the questionId, Id finds formId
- - Fetch all questions associated with the formId
- - Match-fetched questions isRequired with requested body question responses
- - If the exact matches - go to the next step or throw the error “Please submit a response to all questions”
- - We'll find if a response already exists for a question of an assignment using questionId and assignmentId
- - If it does we'll update the record with the new value
- - Otherwise will create a new record(s) in the response table
Acceptance Criteria
- After a form is submitted it should return with responses next time
- When we try to submit a form partially, should throw an error with status code - 422
- If a form getting resubmitted should update the record
- if a form is getting submitted the first time should create a record
Get Assignment Form
Anyone who has access to an assignment can access the form along with the response.
This endpoint will be used to fetch a form along with responses by assignmentId. This API can be accessed by any of the stakeholders of the assignment.
API Endpoint :
GET /forms?assignmentId=:assignmentId:
Examples
GET /forms?assignmentId=:assignmentId:
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
GET /forms?assignmentId=:assignmentId:
200 Response
{
"meta": { },
"data": {
"id": "1fb73b5b-e8a2-4733-87cc-ee5e8eea2806",
"assignmentId": "1fb73b5b-e8a2-4733-87cc-ee5e8eea2886",
"title": "form title",
"category": "form category",
"isSubmitted": true,
"questions": [
{
"id": "1fb73b5b-e8a2-4733-87cc-ee5e8eea2806",
"title": "Did you meet the recipient?",
"type": "text",
"response": "Yes"
},
{
"id": "1fb73b5b-e8a2-4733-87cc-ee5e8eea2806",
"title": "What is the temperature of the shipment?",
"type": "number",
"response": "56"
}
]
}
}
Invalid assignment Id
{
"meta": {
"status": 3,
"message": "assignmentId has to be a valid UUID"
},
"data": {}
}
When no form associated with given assignment ID or the logged in user do not have permission to the form or assignment
{
"meta": {
"status": 0,
"message": null
},
"data": null
}
Acceptance Criteria
- If the form is associated with the assignment id, return the form if not return null
- If a response is available for the form, populate the response
- Write request functional and unit test cases
- Update documentation - In the documentation the nullable, optional, and always present fields should be clearly specified
Compartment Types
Compartment Types in the Wise Systems platform are the combination of a unit and label and represent the distinct sections available on a Vehicle or the type of transportation storage needed for a task. Labels and units are arbitrary, and are carried across Tasks and Vehicles.
List All Compartment Types
List All Compartment Types response example
{
"meta": {},
"data": [
{
"unit": "cu-ft",
"label": "dry",
"isDefault": true,
"client": "206d6930-4542-4f94-815d-33664ca04f00",
"id": "af7e3072-7843-44da-b7b5-3af0a92e1bdf"
},
{
"unit": "pallet",
"label": "refrigerated",
"isDefault": false,
"client": "206d6930-4542-4f94-815d-33664ca04f00",
"id": "c5d15643-14c2-42eb-b6e6-b9d1884fee1d"
}
]
}
""" // get compartment_types """
def getCompartmentTypes(self, limit=1000, page=0):
url = self.__get_request_url("compartment_types", limit, page)
r = requests.get(url, headers=self.JSON_HEADER)
if r.status_code != 200:
print(r.status_code, r.reason)
return r.json()
List all Compartment Types in the system.
GET https://api.wisesys.info/compartment_types
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | List of Compartment Types | List of Compartment Types |
Create a Compartment Type
POST /compartment_types HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
""" // Create Compartment Type """
def addCompartmentType(self, data):
r = requests.post(self.API_URL + "compartment_types", json=data, headers=self.JSON_HEADER)
if r.status_code is not 200:
print r.status_code, r.reason
return r.json()
Create Compartment Type request example
{
"label": "refrigerated",
"unit": "cu-ft"
}
Add a new Compartment Type into the system. There is a limit of maximum 10 Compartment Types per client. Compartment units and labels cannot contain spaces, underscores, or other special characters. Only alphanumeric charaters and dashes (-) are accepted.
POST https://api.wisesys.info/compartment_types
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| label | String | The label for this Compartment Type |
| unit | String | The unit for the merchandise transported in this Compartment Type |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | Compartment Type | New Compartment Type data |
Get Specific Compartment Type
GET /compartment_types/71740039-2503-1114-0912-169749251171 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
""" // Get Compartment Type """
def getCompartmentType(self, compartmentType_id):
r = requests.get(self.API_URL + "compartment_types?id[]=" + compartmentType_id, headers=self.JSON_HEADER)
if r.status_code != 200:
print(r.status_code, r.reason)
return r.json()
Specific Compartment Type response example
{
"meta": {},
"data": [
{
"label": "refrigerated",
"unit": "cu-ft",
"client": "206d6930-4542-4f94-815d-33664ca04f00",
"isDefault": true,
"id": "af7e3072-7843-44da-b7b5-3af0a92e1bdf"
}
]
}
Get a specific Compartment Type by id.
GET https://api.wisesys.info/compartment_types?id[]={id}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id[] | UUID | Required; Compartment Type unique Id; example: "7a740f3c-f503-11e4-b9b2-1697f925ec7b" |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | Compartment Type | Compartment Type data |
Update Compartment Type
PUT /compartment_types/71740039-2503-1114-0912-169749251171 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def updateCompartmentType(self, compartment_type_id, data):
r = requests.put(self.API_URL + "compartment_types/" + compartment_type_id, json=data, headers=self.JSON_HEADER)
if r.status_code is not 200:
print r.status_code, r.reason
return r.status_code, r.json()
Update Compartment Type body JSON example
{
"label": "refrigerated",
"unit": "cu-ft"
}
Update a specific compartment type by id. Unit and label are required fields. This will respond with a status 404 if the compartment type doesn't exist.
PUT https://api.wisesys.info/compartment_types/{id}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; Compartment Type unique Id; example: "7a740f3c-f503-11e4-b9b2-1697f925ec7b" |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | CompartmentType | Updated Compartment Type data |
Remove Compartment Type
DELETE /compartment_types/71740039-2503-1114-0912-169749251171 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
""" // Remove Compartment Type """
def deleteCompartmentType(self, compartment_type_id):
r = requests.delete(self.API_URL + "compartment_types/" + compartment_type_id, headers=self.JSON_HEADER)
if r.status_code is not 200:
print(r.status_code, r.reason)
return r.json()
Remove Compartment Type response body JSON example
{
"id": "7a740f3c-f503-11e4-b9b2-1697f925ec7b"
}
Remove a Compartment Type.
DELETE https://api.wisesys.info/compartment_types/{id}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; Compartment Type unique Id; example: "7a740f3c-f503-11e4-b9b2-1697f925ec7b" |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | IdObject | Wise Systems' server returns unique compartment type Id |
Vehicles
Vehicles in the Wise Systems platform represent the mode of transport for a driver.
List All Vehicles
List All Vehicles response example
{
"meta": {
"page":0,
"limit":10,
"total":3
},
"data":[
{
"id": "eklaz440--4e4a-480c-bbf7-d266c88e5fa5",
"licensePlate": "NC-1701",
"type": "truck",
"makemodel": "Ford F150",
"year": "2009",
"weightCapacity": 1000,
"volumeCapacity": 5.0,
"compartments": [
{
"compartmentType": "fe8118d7-7534-4809-80fb-90b77fd3964f",
"capacity": 5.0
}
],
"description": "red ford f150 with black decals"
},
{
"id": "pow22je0--4e4a-480c-bbf7-d266c88e5fa5",
"licensePlate": "NC-1703",
"type": "truck",
"makemodel": "Ford F250",
"year": "2012",
"weightCapacity": 1500,
"volumeCapacity": 5,
"description": "black ford f250"
}]
}
""" // get vehicles """
def getVehicles(self, limit=1000, page=0):
url = self.__get_request_url("vehicles", limit, page)
r = requests.get(url, headers=self.JSON_HEADER)
if r.status_code != 200:
print(r.status_code, r.reason)
return r.json()
List all vehicles in the system.
GET https://api.wisesys.info/vehicles{?page}{?limit}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| page | int | Optional; defaults to 0; the pagination offset to return |
| limit | int | Optional; default to 10; the pagination limit of each page |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | List of Vehicle | List of vehicles |
Create a Vehicle
POST /vehicle HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
""" // Create vehicle """
def addVehicle(self, data):
r = requests.post(self.API_URL+"vehicle", json=data, headers=self.JSON_HEADER)
if r.status_code is not 200:
print r.status_code, r.reason
return r.json()
Create Vehicle request example
{
"licensePlate": "NC-1701",
"type": "truck",
"makemodel": "Ford F150",
"year": "2009",
"weightCapacity": 1000,
"compartments":[
{
"compartmentType": "f49f6ccb-d93b-4c73-b7d8-2eb8813f9c26",
"capacity": 5.0
}
],
"description": "red ford f150 with black decals"
}
Add a new vehicle into the system. The system makes the vehicle available to be assigned to a driver.
POST https://api.wisesys.info/vehicle
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| licensePlate | String | The vehicle license plate |
| type | String | Type of the vehicle; example: truck |
| makemodel | String | The make and model of the vehicle; example: Ford F150 |
| year | String | The year of the vehicle; example: "2012" |
| weightCapacity | Float | Weight limits apply to tasks and take into account the vehicle's weight-carrying capacity. Units are arbitrary, but they should be the same as used for tasks' weight. |
| volumeCapacity | Float | Deprecated and replaced by compartments |
| compartments | List | List of compartments and capacities. Capacity limits apply to Tasks with matching Compartment Types and take into account the Vehicle's carrying capacity per compartment. |
| description | String | Vehicle description |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | Vehicle | New vehicle data |
Get Specific Vehicle
GET /vehicle/71740039-2503-1114-0912-169749251171 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
""" // get vehicle """
def getVehicle(self, veh_id):
r = requests.get(self.API_URL + "vehicle/" + veh_id, headers=self.JSON_HEADER)
if r.status_code != 200:
print(r.status_code, r.reason)
return r.json()
Specific Vehicle response example
{
"meta": {
"status": 0
},
"data": {
"id": "djllz490--4e4a-480c-bbf7-d266c88e5fa5",
"licensePlate": "NC-1701",
"type": "truck",
"makemodel": "Ford F150",
"year": "2009",
"weightCapacity": 1000,
"volumeCapacity": 2.5,
"compartments":[
{
"compartmentType": "f49f6ccb-d93b-4c73-b7d8-2eb8813f9c26",
"capacity": 2.5
}
],
"description": "red ford f150 with black decals"
}
}
Get a specific vehicle by id.
GET https://api.wisesys.info/vehicle/{id}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; vehicle unique Id; example: "7a740f3c-f503-11e4-b9b2-1697f925ec7b" |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | Vehicle | Vehicle data |
Update Vehicle
PUT /vehicle/71740039-2503-1114-0912-169749251171 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def updateVehicle(self, veh_id, data):
r = requests.put(self.API_URL + "vehicle/" + veh_id, json=data, headers=self.JSON_HEADER)
if r.status_code is not 200:
print r.status_code, r.reason
return r.status_code, r.json()
Update Vehicle body JSON example
{
"licensePlate": "SS-1988",
"weightCapacity": 1000,
"compartments": [
{
"compartmentType": "f49f6ccb-d93b-4c73-b7d8-2eb8813f9c26",
"capacity": 3.0
}
],
"description": "red ford f150 with black decals"
}
Update a specific vehicle by id. Unlike a traditional PUT, this request may omit the properties that don't need to be updated. This will also respond with a status 404 if the vehicle doesn't exist.
volumeCapacity is deprecated. It is recommended to use compartments when updating vehicles.
Note that if the update includes eid the system will first check if another vehicle exists with the same eid and if so reject the request with status 405.
PUT https://api.wisesys.info/vehicle/{id}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; vehicle unique Id; example: "7a740f3c-f503-11e4-b9b2-1697f925ec7b" |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | IdObject | Wise Systems' server returns unique vehicle Id |
Remove Vehicle
DELETE /vehicle/71740039-2503-1114-0912-169749251171 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
""" // Remove vehicle """
def deleteVehicle(self, veh_id):
r = requests.delete(self.API_URL + "vehicle/" + veh_id, headers=self.JSON_HEADER)
if r.status_code is not 200:
print(r.status_code, r.reason)
return r.json()
Remove Vehicle response body JSON example
{
"licensePlate": "SS-1988",
"weightCapacity": 1000,
"description": "red ford f150 with black decals"
}
Remove a vehicle from service.
DELETE https://api.wisesys.info/vehicle/{id}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; vehicle unique Id; example: "7a740f3c-f503-11e4-b9b2-1697f925ec7b" |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | IdObject | Wise Systems' server returns unique vehicle Id |
Tasks
In the Wise Systems platform, tasks are the core pieces of work that will be assigned to a driver and vehicle. Tasks contain all the valuable information about a visit to a customer location that the Wise Systems platform needs to consider when optimizing routes. Tasks primarily contain client-entered data, where assignments represent the dispatched state of the task as managed by the Wise Systems platform.
Tasks can be single-part, or two-part: a pickup, a delivery, or a joined pickup and delivery. The client must set the relevant properties for location and props based on the type. For instance, a two-part task must contain both a pickupLocation and deliveryLocation (and pickupTimeWindow, deliveryTimeWindow, etc), while a single-part delivery should not contain any fields corresponding to a pickup. A single-part task is interpreted as the “other half” occurring at a depot: a single-part delivery must have a preceding pickup at the depot at some point.
List Tasks
GET /tasks HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def getTasks(self, date=None, limit=1000, page=0, extents=None):
url = self.__get_request_url("tasks", limit, page, extents)
if date:
params = {"date": date}
else:
params = {}
r = requests.get(url, params = params, headers=self.JSON_HEADER)
if r.status_code != 200:
print(r.status_code, r.reason)
return r.json()
def getTasksByStatus(self, status, limit=1000, page=0, extents=None):
url = self.__get_request_url("tasks", limit, page, extents) + "&status=" + str(status)
r = requests.get(url, headers=self.JSON_HEADER)
if r.status_code != 200:
self.notify("Failed when calling GET Tasks by Status: "+r.text)
return r.json()
List Tasks response body JSON example
{
"meta": {
"page": 1,
"limit": 1,
"total": 2
},
"data": [
{
"name": "task-1",
"pickupContact": "70a3c908-f502-11e4-b9b2-1697f925ec7b",
"pickupLocation": "14e93b00-2fba-11e5-891f-9d3d0c07dabb",
"deliveryContact": "91a4c701-r502-21e4-c9b2-4697r923ec7b",
"deliveryLocation": "34f43780-2fba-11e5-891f-9d3d0c07dabb",
"props": {
"priority": 1,
"size": 2,
"weight": 25,
"pickupTime": "2015-06-29T16:34:41.000Z",
"pickupServiceTime": "PT30M",
"pickupWindow": [
{
"start": "2015-06-29T16:30:00.000Z",
"end": "2015-06-29T16:45:00.000Z"
}
],
"deliveryTime": "2015-06-29T20:35:00.000Z",
"deliveryServiceTime": "PT30M",
"deliveryWindow": [
{
"start": "2015-06-29T20:30:00.000Z",
"end": "2015-06-29T20:50:00.000Z"
}
]
},
"sizeByCompartment": [
{
"compartmentType": "f49f6ccb-d93b-4c73-b7d8-2eb8813f9c26",
"size": 2
}
],
"id": "14f4d3c0-2fba-11e5-891f-9d3d0c07dabb",
"status": 1
}
]
}
GET https://api.wisesys.info/tasks{?extent}{?page}{?limit}{?status}{?date}
List all tasks that are currently in the system.
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| extent | string | Optional; name of field which shows its detail |
| page | int | Optional; defaults to 0; the pagination offset to return |
| limit | int | Optional; default to 10; the pagination limit of each page |
| status | int | Optional; default to null; filter by task status |
| date | string | Optional; default to null; filter by route date; the date is formatted as "YYYY-MM-DD" |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | TaskObject | Returned task data |
Start Day for Driver
POST /tasks?action=accept_assigned HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def acceptAssignment(self, driverId=None):
data = {"driverId": driverId} if driverId else {}
r = requests.post(self.API_URL+"tasks?action=accept_assigned", json = data,
headers=self.JSON_HEADER)
if r.status_code != 200:
print(r.status_code, r.reason)
return r.status_code, r.text
Response Body JSON example
{
"meta": { },
"data": {
"message": "The Prepared Route is now implemented."
}
}
Retrieve and assign all tasks that are designated for a specific driver & vehicle. This call will reference any planned assigned routes in the system, and use the driver’s last known location to build an optimal schedule for the driver, if applicable. This is recommended to only be called from the driver’s mobile application.
POST https://api.wisesys.info/tasks?action=accept_assigned
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| action | String | Required; get all tasks designated for the driver as an optimal schedule |
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| driverId | UUID | Optional; the driver to assign tasks to |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | String | Default to null |
Plan Tasks
POST /tasks/71740331-3503-1134-1922-169719251371 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
""" // suggest assignments for drivers """
def suggestTasks(self, action='suggest', date=None):
"""
:param action: takes in the following actions:
* suggest - gives suggestions for assignments to drivers
:param date: a future date in the YYYY-MM-DD format
:return: return message from the API
"""
params = {}
if date:
params["date"] = date
r = requests.get(self.API_URL + "tasks/" + action, params=params, headers=self.JSON_HEADER)
if r.status_code != 200:
self.notify("Failed to Schedule Task: "+r.text)
return r.json()
""" // auto assign tasks """
def scheduleTasks(self, date = None, action='suggest'):
"""
Initiates the auto-assign scheduler
:param date: in YYYY-MM-DD format
:param action: takes in the following actions
* auto_assign - automatically assigns the tasks
* suggest - gives suggestions for assignments to drivers
"""
data = {"date": date} if date else {}
r = requests.post(self.API_URL+"tasks?action="+action, json = data,
headers = self.JSON_HEADER)
if r.status_code != 200:
self.notify("Failed to Schedule Task: "+r.text)
ret = r.json()
if r.status_code == 200 and ret['data'] == []:
self.notify("No Tasks Scheduled: "+r.text)
return ret
""" // plan long running tasks """
def scheduleTasksWithLRS(self, action="lr_schedule", date=None, preferences=None):
"""
Initiates the long running Route Planner on unassigned tasks
:param action:
* lr_schedule - initiates the long running Route Planner
* lr_stop - will stop the long running Route Planner
* lr_accept - accept the proposed solution
:param date date for the plan. If not provided, current day is used.
:param preferences overrides for client preferences during this run
"""
data = preferences if preferences else {}
if date:
data["date"] = date
r = requests.post(self.API_URL + "tasks?action=" + action, json=data,
headers=self.JSON_HEADER)
if r.status_code != 200:
self.notify("Failed when attempting " + action + ": " + r.text)
return r.json()
""" // suggest drivers """
def suggestDrivers(self, task_id):
"""
suggests a list of best-suited drivers for a given task
:param task_id: task id to receive suggested drivers
"""
r = requests.get(self.API_URL+"task/" + task_id + "/suggest",
headers=self.JSON_HEADER)
if r.status_code != 200:
self.notify("Failed to Schedule Task: "+r.text)
return r.status_code, r.json()
Request body JSON example
{
"date": "2019-03-01"
}
Suggest response body JSON example
{
"meta": {},
"data": [{
"driver": "2cafc9a0-3ca0-11e5-a4e2-5598a5c5072a",
"schedule": [{
"task": "34016a10-3ca0-11e5-a4e2-5598a5c5072a",
"pickupTime": "2015-06-29T16:30:00.000Z",
"deliveryTime": "2015-07-14T15:23:20.000Z"
}]
},
{
"driver": "26b777a0-3ca0-11e5-a4e2-5598a5c5072a",
"schedule": [{
"task": "34053aa0-3ca0-11e5-a4e2-5598a5c5072a",
"pickupTime": "2015-06-29T16:30:00.000Z",
"deliveryTime": "2015-07-14T15:23:20.000Z"
}]
}
]
}
Schedule response body JSON example
{
"meta": {},
"data": {
"message": "The schedule is done and the assignments are added..."
}
}
Plan all queued tasks for the available drivers. The system will return an ordered list of drivers and their task allocations for the given day. The tasks are assigned based on the optimal scenarios considered by the algorithms.
There are multiple ways to plan tasks
POST https://api.wisesys.info/tasks/{?action}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| action | String | action value must be set to one of the following values: |
| lr_schedule : Initiates the long running Route Planner on unassigned tasks | ||
| lr_accept : Dispatches the planned routes to drivers | ||
| lr_stop : Stops the long running Route Planner operation | ||
| auto_assign : Automatically assigns the task |
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| date | Date | Required; plan tasks for the specified date; the date is formated as "YYYY-MM-DD"; example: "2019-07-04" |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | List of ScheduleTaskObject | Ordered list of drivers and their planned tasks |
Create or Replace Task
PUT /task HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
"""// Create Task """
def addTask(self, data):
r = requests.post(self.API_URL+"task", json=data, headers=self.JSON_HEADER)
if r.status_code != 200:
print(r.status_code, r.reason)
return r.json(
Request body example for both pickup and delivery
{
"name": "task-A",
"routeDate": "2018-02-05",
"euid": "17",
"eorder": 0,
"externalTaskType": "pickup",
"pickupContact": {
"name": "Julian Bashir",
"phone": "+15552581001"
},
"pickupLocation": "70a3c908-f502-11e4-b9b2-1697f925ec7b",
"deliveryContact": {
"name": "Homer Kwan",
"phone": "+15552581001"
},
"deliveryLocation": {
"name": "MIT Bookstore",
"addressLine1": "292 Main Street",
"addressLine2": "Suite 616",
"city": "Cambridge",
"state": "MA",
"zipcode": "02138",
"country": "USA"
},
"props": {
"priority": 1,
"weight": 25,
"pickupTime": "2018-02-05T16:34:41.000Z",
"pickupServiceTime": "PT30M",
"pickupWindow": [
{
"start": "2018-02-05T16:30:00.000Z",
"end": "2018-02-05T16:45:00.000Z"
}
],
"deliveryTime": "2018-02-05T20:35:00.000Z",
"deliveryServiceTime": "PT30M",
"deliveryWindow": [
{
"start": "2018-02-05T20:30:00.000Z",
"end": "2018-02-05T20:50:00.000Z"
}
]
},
"sizeByCompartment": [
{
"compartmentType": "70a3c908-e965-11e4-45c5-1697f925ec7b",
"size": 2.1
}
]
}
Instead of the
id, it is possible to specify thelabelof an existing Compartment Type when creating Tasks.
"sizeByCompartment": [
{
"compartmentType": {"label": "refrigerated"}
"size":2.1
}
]
POST /task HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
Request body example for customer delivery euid
{
"routeDate": "2018-02-05",
"deliveryEuid": "10913"
}
Request body example for pickup
POST /task HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
{
"name": "task-A",
"routeDate": "2018-02-05",
"pickupContact": {
"name": "Homer Kwan",
"phone": "+15552581001"
},
"pickupLocation": {
"name": "MIT Bookstore",
"addressLine1": "292 Main Street",
"addressLine2": "Suite 616",
"city": "Cambridge",
"state": "MA",
"zipcode": "02138",
"country": "USA"
},
"props": {
"priority": 1,
"size": 2,
"weight": 25,
"pickupServiceTime": "PT30M",
"pickupWindow": [
{
"start": "2018-02-05T16:30:00.000Z",
"end": "2018-02-05T16:45:00.000Z"
}
]
}
}
Add a new task to the system or replace existing one matching the following properties:
- name
- routeDate
- euid
- routeId
- props.weight
- props.size | deprecated in favor of sizeByCompartment
- sizeByCompartment
sizeByCompartment
props.size is deprecated in favor of sizeByCompartment.
Tasks can have a maximum of 10 Compartment Types associated. All tasks have a default compartment associated at creation if sizeByCompartment is not specified.
Example sizeByCompartment in response
"sizeByCompartment": [
{
"compartmentType": "9618fafa-f48e-4d26-b1c0-9fc0836aeef7",
"size": 6
},
{
"compartmentType": "f4c4629b-4cb3-4324-8349-cbbce45ba986",
"size": 3
},
]
For pickupLocation and deliveryLocation, there are two possible formats:
- Existing address id
- New address that will be created automatically
props.pickupInventory and props.deliveryInventory
It is possible to create Inventory Items associated to the task by including props.pickupInventory and/or props.deliveryInventory. Their value must be an array of valid inventory items. If the items are successfully created, the response will include the fields created_successfully and wise_inventory_item_id with the id of the created inventory item on each element. If an item is not created successfully, created_successfully will be false and the field creation_error_message is included with details on the failure. Failed items can be retried by using POST https://api.wisesys.info/inventoryitems. The type ("delivery" or "pickup") of the inventory items is determined by the type of the inventory they are included in.
Example pickupInventory in response
"pickupInventory": [
{
"item_id": "BOTL",
"item_name": "Bottles",
"expected_quantity": 15,
"successfully_created": true,
"wise_inventory_item_id": "9b9cecc8-2714-45f9-8c2f-85380077c867"
},
{
"item_id": "CANS",
"item_name": "Cans",
"expected_quantity": "Cans",
"successfully_created": false,
"creation_error_message": "invalid input syntax for type numeric: \"Cans\""
}
]
props.pickupInvoices and props.deliveryInvoices
It is possible to create Invoices associated to the task by including props.deliveryInvoices and/or props.pickupInvoices. Their value must be an array of valid invoices. Sample creation query (note that an invoice may or may not be referenced by the an inventory item):
"props": {
"deliveryInvoices": [
{
"invoiceNumber": "DLV001",
"amountDue": 100
},
{
"invoiceNumber": "DLV002",
"amountDue": 50
}
],
"deliveryInventory": [
{
"item_id": "BOTL",
"item_name": "Bottles",
"expected_quantity": 15,
"invoice_number": "DLV001"
},
{
"item_id": "CANS",
"item_name": "Cans",
"expected_quantity": 10,
}
]
}
props.truckType
This property can be used for customers to match two part tasks based on specified truck type (e.g. cold, 18ft container, etc.). Matching is made by exact string comparison.
PUT https://api.wisesys.info/task
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| externalTaskType | String | Optional; A custom task type (maximum 64 character) that an API user wants to associate with the task; example: "Load Delivery" |
| date | Date | Required; plan tasks for the specified date; the date is formated as "YYYY-MM-DD"; example: "2019-07-04" |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | TaskObject | Returned task data |
Bulk Create or Replace Task
PUT /tasks HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
"""// Bulk Create Task """
def addTasks(self, data):
r = requests.post(self.API_URL+"tasks", json=data, headers=self.JSON_HEADER)
if r.status_code != 200:
print(r.status_code, r.reason)
return r.json(
Request body example: tasks in the format described above for single task creation
[
{
task1
},
{
task2
},
{
task3
},
{
task4
},
{
task5
}
]
POST /task HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
Adds multiple new tasks to the system, replacing existing matching ones, by the same logic in PUT /task.
PUT https://api.wisesys.info/tasks
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | Object | Information on successful and failed task uploads |
Returned data format example:
{
"success": [
"859fe3d6-daca-4b3a-b408-6a476868381b",
"1d521232-ceff-4389-8567-289b5b5ba4a3",
"5d4cb2e3-6606-4ad2-9165-55414bbd939a"
],
"fail": [
{"index": 0, "error": "error message"},
{"index": 4, "error": "error message"}
]
}
Retrieve Task
Request body example for pickup
GET /task/71740331-3503-1134-1922-169719251371 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
"""// retrieve task """
def getTask(self, tsk_id, extents=None):
url = self.__get_request_url("task/" + tsk_id, 1, 1, extents)
r = requests.get(url, headers=self.JSON_HEADER)
if r.status_code != 200:
print(r.status_code, r.reason)
return r.json()
{
"data": {
"name": "task-1",
"pickupContact": "9zb834c0-41ab-31e5-33c1-9ca1d2723de2",
"pickupLocation": "14e93b00-2fba-11e5-891f-9d3d0c07dabb",
"deliveryContact": "5ca935b0-31ab-41e5-93c1-5ba1d2723ce5",
"deliveryLocation": "14f43780-2fba-11e5-891f-9d3d0c07dabb",
"props": {
"priority": 1,
"size": 2,
"weight": 25,
"pickupTime": "2015-06-29T16:34:41.000Z",
"pickupServiceTime": "PT30M",
"pickupWindow": [
{
"start": "2015-06-29T16:30:00.000Z",
"end": "2015-06-29T16:45:00.000Z"
}
],
"deliveryTime": "2015-06-29T20:35:00.000Z",
"deliveryServiceTime": "PT30M",
"deliveryWindow": [
{
"start": "2015-06-29T20:30:00.000Z",
"end": "2015-06-29T20:50:00.000Z"
}
]
},
"id": "14f4d3c0-2fba-11e5-891f-9d3d0c07dabb",
"status": 1
}
}
Get a specific task by id and view its current status.
GET https://api.wisesys.info/task/{id}{?extent}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; task unique Id |
| extent | String | Optional; name of field which shows its detail (e.g., address) |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | List of TaskObject | Returned task data |
Delete Task
DELETE /task/71740331-3503-1134-1922-169719251371 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
""" // Delete task"""
def deleteTask(self, tsk_id):
r = requests.delete(self.API_URL + "task/" + tsk_id, headers=self.JSON_HEADER)
if r.status_code is not 200:
print(r.status_code, r.reason)
return r.json()
Response body example with task Id
{
"meta": {},
"data": {
"id": "70a3c908-f502-11e4-b9b2-1697f925ec7b",
}
}
Response body could also be empty
{
"meta": {},
"data": {}
}
Delete a task from the system. The task must not already be assigned. If the task is found, the response will contain the task id, otherwise it will be empty.
DELETE https://api.wisesys.info/task/{id}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; task Id |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | Ids | Return Id of the deleted task |
Update Task
Request body example
PATCH /task/71740331-3503-1134-1922-169719251371 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
"""// Update Task """
def update_task(self, tsk_id, data):
r = requests.patch(self.API_URL + "task/" + tsk_id, json=data, headers=self.JSON_HEADER)
if r.status_code is not 200:
print(r.status_code, r.reason)
return r.json()
{
"props": {
"priority": 1,
"size": 2,
"weight": 25,
"pickupTime": "2007-11-06T16:34:41.000Z",
"pickupWindow": [
{
"start": "2007-11-06T16:34:41.000Z",
"end": "2007-11-06T16:34:41.000Z"
}
],
"deliveryTime": "2007-11-06T18:20:41.000Z",
"deliveryWindow": [
{
"start": "2007-11-06T16:34:41.000Z",
"end": "2007-11-06T16:34:41.000Z"
}
]
}
}
Update task information by supplying the properties to modify. Note that if you want to modify a second-level property (e.g., props.size), you must send the whole parent structure (in this case props). You can’t change the task status.
PATCH https://api.wisesys.info/task/{id}?action={task_action}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; task Id |
| action | String | Optional; any action to perform on the task, (e.g. cancel, `unassign') |
REQUEST BODY
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | Ids | Return Id of the updated task |
Get All Assignments for Task
Response body example
GET /task/71740331-3503-1134-1922-169719251371/assignments HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def getAssignmentByTaskID(self, task_id):
r = requests.get(self.API_URL + "task/" + task_id + "/assignments", headers=self.JSON_HEADER)
if r.status_code != 200:
print(r.status_code, r.reason)
return r.json()
Get all assignments response example
{
"meta": {
"page": 0,
"limit": 3,
"total": 32
},
"data": [
{
"id": "7b7g0f2c-g523-11f4-c9h4-1697f925ec7b",
"type": "delivery",
"location": "16e5b1d0-3bf0-11e5-9206-1324edd52c4d",
"contact": {
"name": "Homer Kwan",
"phone": "+15552581001"
},
"props": {
"time": "2015-06-20T16:34:41.000Z",
"serviceTime": "PT30M",
"window": {
"start": "2015-06-20T16:34:41.000Z",
"end": "2015-06-20T16:34:41.000Z"
}
},
"task": "84788f56-c617-4c2b-8677-53de01fb47fe",
"driver": "7a740f3c-f503-11e4-b9b2-1697f925ec7b",
"eta": "PT10M36S",
"completedAt": "2015-08-24T20:26:21.007Z",
"status": 2
}
]
}
Get all assignments (assigned tasks) for a specific task
GET https://api.wisesys.info/task/{id}/assignments{?page}{?limit}{?extent}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; task Id |
| extent | string | Optional; name of field which shows its detail |
| page | int | Optional; defaults to 0; the pagination offset to return |
| limit | int | Optional; default to 10; the pagination limit of each page |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | List of AssignmentObject | Assignments associated with the driver |
Unassign a Task
def unassign_task(self, tsk_id):
r = requests.patch(self.API_URL + "task/{}?action=unassign".format(tsk_id), headers=self.JSON_HEADER)
if r.status_code is not 200:
print(r.status_code, r.text)
return r.json()
Remove the assignment for a given task.
PATCH https://api.wisesys.info/task/{id}?action=unassign
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; task Id |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | Ids | Return Id of the updated task |
Get Suggested Drivers for Task
Request example for suggesting drivers
GET /task/71740331-3503-1134-1922-169719251371/suggest HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def suggestDrivers(self, task_id, order_by=None, prioritize_active_drivers=None, radius=None, include_metrics=None):
"""
suggests a list of best-suited drivers for a given task
"""
params = {}
if order_by:
params["orderBy"] = order_by
if prioritize_active_drivers:
params["prioritizeActiveDrivers"] = prioritize_active_drivers
if radius:
params["radius"] = radius
if include_metrics:
params["includeMetrics"] = include_metrics
url = "{api_url}task/{id}/suggest".format(api_url=self.API_URL, id=task_id)
r = self.SESSION.get(url, params=params, headers=self.JSON_HEADER)
r.raise_for_status()
return r.json()
Response example
json { "data": { "suggestedDrivers": [ { "driver": "80d20df0-2025-11ea-9d44-cbee967533a6", "deliveryPosition": 2 }, { "driver": "29a3ce7b-f34f-4204-89cb-6ef9e835a1b2", "deliveryPosition": 2 }, { "driver": "235df2bb-1ec3-428f-ae1f-f973432b485c", "deliveryPosition": 3 }, { "driver": "d93b148f-21bb-41a5-a5d8-4152d3edb48f", "deliveryPosition": 1 }, { "driver": "33787064-7a9f-11eb-9439-0242ac130002", "deliveryPosition": 5 } ], "task": { "status": 0, "routeDate": "2019-12-16", "name": "Tatte to Flour", "vehicleTypes": [], "vehicleEid": "", "eorder": 0, "deduplicationId": "fd1bb31a-ae93-4c31-b4f4-c635e15bc228", "deliveryContact": { "phone": "+15558632637", "name": "Test Driver" }, "deliveryLocation": { "customer": "b91e4670-4d58-11e8-a033-85499a9e6935", "city": "Cambridge", "name": "Anna's Tacqueria", "country": "USA", "parking": [], "zipcode": "02139", "state": "MA", "addressLine2": "", "location": { "lat": 42.35901399999999, "lng": -71.0947224 }, "addressLine1": "84 Massachusetts Ave", "id": "61111310-4743-11e8-a86b-25dc69243966" }, "props": { "deliveryServiceTime": "PT0H10M0S", "weight": 25, "deliveryTime": "2019-12-16T16:15:12.072Z", "priority": 1, "deliveryWindow": [ { "start": "2019-12-16T16:15:12.072Z", "end": "2019-12-16T23:36:12.072Z" } ], "size": 2 }, "id": "f0b1f803-f347-4497-8f12-8b393ef35b21", "euid": "" } } }
Produce a list of best 5 suggested drivers for a task.
Sort Metric
Here are supported metrics that can be passed using the orderBy query parameter:
total_route_time: Estimate of the total time the driver has been, and will be, on road.number_of_delays: Number of delayed stops after the new task is added.eta: Estimated time of arrival of the newly added stop.induced_route_time: Route time induced by the new task.induced_number_of_delays: Number of delays induced by the new task.
If orderBy parameter is provided, only that metric will be used. Otherwise, if orderBy parameter is not provided, the induced_route_time is used and ties will be broken first by total_route_time, number_of_delays and then eta.
When includeMetrics is true, the response will include the new total and induced route time and the new and induced number of delays to provide additional insights on the effects of dispatching the tasks to the suggested driver.
Other parameters, such as radius for example can be used together with orderBy.
The system only considers those drivers and vehicles that can accept the task while satisfying all the constraints such as capacity.
For each driver, Wise Systems computes the best pickup/delivery insertion position taking into account the already-assigned stops and current vehicle position. These positions can then be provided to the Create Assignment method to dictate where in the schedule it should insert the stop. Since vehicle schedules may change over time making the insertion positions out-of-date, it is recommended that the Create Assignment call is made right after receiving the suggestions.
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; task unique Id |
| orderBy | String | Optional; Sort metric. Possible values: total_route_time, number_of_delays, eta, induced_route_time, induced_number_of_delays |
| radius | Number | Optional; Radius around the task in meters where suggested drivers should be considered. Possible values: 0 - 1'000'000 |
| prioritizeActiveDrivers | Boolean | Optional; prioritizes active drivers over inactive drivers when set to true. Default: true |
| includeMetrics | Boolean | Optional, default: false; includes explainMetrics in response. See SuggestedDrivers |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data.suggestedDrivers | SuggestedDrivers | Driver suggestions |
| data.task | Task | Task for which suggestions apply |
Get Suggested Drivers for Group of Tasks
Request example for bulk suggest
POST /task/bulk_suggest HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
{
"tasks": [
"45ba3660-f8e9-11e4-a322-1697f925ec7b",
"71740331-3503-1134-1922-169719251371"
],
"excludedDrivers": [
"32554ecd-1898-45f1-bfe7-134bb6c21d07",
"d60b5531-c502-4e0c-9eb6-04814f52b25e"
]
}
def bulkSuggestDrivers(self, task_ids, order_by=None, prioritize_active_drivers=None, radius=None,
excluded_drivers=None, include_metrics=None):
"""
suggests a list of best-suited drivers for a given list of task_ids
"""
url = "{api_url}task/bulk_suggest".format(api_url=self.API_URL)
params = {}
if order_by:
params["orderBy"] = order_by
if prioritize_active_drivers:
params["prioritizeActiveDrivers"] = prioritize_active_drivers
if radius:
params["radius"] = radius
if include_metrics:
params["includeMetrics"] = include_metrics
data = {"tasks": task_ids}
if excluded_drivers:
data["excludedDrivers"] = excluded_drivers
r = self.SESSION.post(url, json=data, params=params, headers=self.JSON_HEADER)
r.raise_for_status()
return r.json()
Response example
json { "data": { "suggestedDrivers": [ { "driver": "80d20df0-2025-11ea-9d44-cbee967533a6", "deliveryPosition": 2, "taskId": "45ba3660-f8e9-11e4-a322-1697f925ec7b" }, { "driver": "80d20df0-2025-11ea-9d44-cbee967533a6", "deliveryPosition": 3, "taskId": "71740331-3503-1134-1922-169719251371" }, { "driver": "29a3ce7b-f34f-4204-89cb-6ef9e835a1b2", "deliveryPosition": 2, "taskId": "45ba3660-f8e9-11e4-a322-1697f925ec7b" }, { "driver": "29a3ce7b-f34f-4204-89cb-6ef9e835a1b2", "deliveryPosition": 2, "taskId": "71740331-3503-1134-1922-169719251371" }, { "driver": "235df2bb-1ec3-428f-ae1f-f973432b485c", "deliveryPosition": 1, "taskId": "45ba3660-f8e9-11e4-a322-1697f925ec7b" }, { "driver": "235df2bb-1ec3-428f-ae1f-f973432b485c", "deliveryPosition": 4, "taskId": "71740331-3503-1134-1922-169719251371" }, { "driver": "d93b148f-21bb-41a5-a5d8-4152d3edb48f", "deliveryPosition": 2, "taskId": "45ba3660-f8e9-11e4-a322-1697f925ec7b" }, { "driver": "d93b148f-21bb-41a5-a5d8-4152d3edb48f", "deliveryPosition": 5, "taskId": "71740331-3503-1134-1922-169719251371" }, { "driver": "33787064-7a9f-11eb-9439-0242ac130002", "deliveryPosition": 2, "taskId": "45ba3660-f8e9-11e4-a322-1697f925ec7b" }, { "driver": "33787064-7a9f-11eb-9439-0242ac130002", "deliveryPosition": 2, "taskId": "71740331-3503-1134-1922-169719251371" } ], "tasks": [{ "status": 0, "routeDate": "2021-01-29", "name": "Tatte to Flour", "vehicleTypes": [], "vehicleEid": "", "eorder": 0, "deduplicationId": "45ba3660-f8e9-11e4-a322-1697f925ec7b", "deliveryContact": { "phone": "+15558632637", "name": "Test Driver" }, "deliveryLocation": { "customer": "b91e4670-4d58-11e8-a033-85499a9e6935", "city": "Cambridge", "name": "Anna's Tacqueria", "country": "USA", "parking": [], "zipcode": "02139", "state": "MA", "addressLine2": "", "location": { "lat": 42.35901399999999, "lng": -71.0947224 }, "addressLine1": "84 Massachusetts Ave", "id": "61111310-4743-11e8-a86b-25dc69243966" }, "props": { "deliveryServiceTime": "PT0H10M0S", "weight": 25, "deliveryTime": "2021-01-29T16:15:12.072Z", "priority": 1, "deliveryWindow": [ { "start": "2021-01-29T16:15:12.072Z", "end": "2021-01-29T23:36:12.072Z" } ], "size": 2 }, "id": "45ba3660-f8e9-11e4-a322-1697f925ec7b", "euid": "" }, { "status": 0, "routeDate": "2021-01-29", "locked": false, "name": "Thinking Cup", "vehicleTypes": [], "vehicleEid": "1", "labels": [], "deduplicationId": "71740331-3503-1134-1922-169719251371", "eorder": 8, "client": "5c087850-2a99-11e5-9189-eb07c479dfd5", "deliveryContact": { "phone": "N/A", "name": "Thinking Cup" }, "euid": "1", "props": { "deliveryServiceTime": "PT29M15S", "weight": 25, "deliveryTime": "2021-01-29T04:00:13.585Z", "priority": 3, "deliveryWindow": [ { "start": "2021-01-29T04:00:13.585Z", "end": "2021-01-29T19:00:13.585Z" } ], "size": 1 }, "id": "459ffbe0-e88e-48df-8d44-acc8eb79622d", "deliveryLocation": { "customer": "13e7ef93-43c3-49c1-8553-21c2dc92db39", "geoLocation": { "type": "Point", "coordinates": [ -71.0552321, 42.3633329 ] }, "name": "Thinking Cup", "city": "Boston", "country": "USA", "parking": [], "zipcode": "02113", "state": "MA", "addressLine2": "", "location": { "lat": 42.3633329, "lng": -71.0552321 }, "addressLine1": "236 HANOVER ST", "id": "71740331-3503-1134-1922-169719251371" } } ] } }
Produce a list of 5 suggested drivers that can accommodate all provided tasks. Certain drivers can be excluded by optionally specifying excludedDrivers in the request body.
By default, the list is sorted by the same metrics as the Suggest Drivers method.
If orderBy parameter is provided, only that metric will be used for selecting and sorting drivers.
(See Suggest Drivers for more details.)
For each driver, Wise Systems computes the best pickup/delivery insertion position taking into account the already-assigned stops and current vehicle position. These positions can then be provided to the Create Assignment method to dictate where in the schedule it should insert the stop. Since vehicle schedules may change over time making the insertion positions out-of-date, it is recommended that the Create Assignment call is made right after receiving the suggestions.
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| orderBy | String | Optional; Sort metric. Possible values: total_route_time, number_of_delays, eta, induced_route_time, induced_number_of_delays, custom_cost, induced_custom_cost |
| radius | Number | Optional; Radius around the task in meters where suggested drivers should be considered. Possible values: 0 - 1'000'000 |
| prioritizeActiveDrivers | Boolean | Optional; prioritizes active drivers over inactive drivers when set to true. Default: true |
| includeMetrics | Boolean | Optional, default: false; includes explainMetrics in response. See SuggestedDrivers |
If orderBy parameter is provided, only that metric will be used. orderBy=custom_cost and orderBy=induced_custom_cost can only be used when custom cost is enabled in the client account and an active custom cost matrix exists for the client. custom_cost sorts the results based on total custom cost of the route as computed through the custom cost matrix. induced_custom_cost sorts the results based on cost induced by the new task as computed through the custom cost matrix.
Otherwise, if orderBy parameter is not provided, the induced_route_time is used and ties will be broken first by total_route_time, number_of_delays and then eta.
When includeMetrics is true, the response will include the new total and induced route time, the new and induced number of delays, and custom cost metrics to provide additional insights on the effects of dispatching the tasks to the suggested driver. When custom cost is disabled in the client account or if there are no active custom cost matrices, the custom cost metrics will always be 0 in the included metrics.
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| tasks | List of UUID | Required; array of task to get suggestion for |
| excludedDrivers | List of UUID | Optional; an array of driver ids that should not be considered when suggesting drivers |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data.suggestedDrivers | SuggestedDrivers | Driver suggestions |
| data.tasks | List of Task | Tasks for which suggestions apply |
Get Suggested Drivers From Subset of Fleet
Request example for suggest across subset of fleet
POST /task/45ba3660-f8e9-11e4-a322-1697f925ec7b/suggest HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def select_drivers(self, task_id, driver_ids):
"""
select best drivers from a list of suggested drivers for a given task
:param task_id: task ID to receive selected drivers
:param driver_ids: array of driver IDs to select from
"""
data = {'driverIds': driver_ids}
r = requests.post("{api_url}task/{id}/suggest".format(api_url=self.API_URL, id=task_id),
json=data, headers=self.JSON_HEADER)
if r.status_code != 200:
self.notify("Failed to select drivers: "+r.text)
return r.status_code, r.json()
Request body example
{
"driverIds": ["32554ecd-1898-45f1-bfe7-134bb6c21d07", "d60b5531-c502-4e0c-9eb6-04814f52b25e"]
}
Response example for suggest across subset of fleet
{
...,
"suggestedDrivers": [
{
"deliveryPosition": 2,
"driver": "32554ecd-1898-45f1-bfe7-134bb6c21d07"
},
{
"deliveryPosition": 3,
"driver": "d60b5531-c502-4e0c-9eb6-04814f52b25e"
}
]
}
Get potential ETAs and best insertion position for a given task across a subset of vehicles in the client fleet. For each driver, Wise Systems computes the pickup/delivery ETA corresponding to the best insertion position, taking into account the already-assigned stops and current vehicle position.
REQUEST VALUES
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | SuggestedDrivers | Driver suggestions |
Two-Part Task Editing
Two-part tasks are tasks with both a pickup and a delivery component. Using two-part tasks ensures that the pickup component will be planned before the corresponding delivery component. It is possible to join a pickup and a delivery task into a two-part task and, conversely, to split a two-part task into standalone pickup and delivery tasks. It is important to note however that when a two-part task is split into standalone pickup and delivery tasks, their planning order is no longer guaranteed. Tasks can only be joined or split when they are unassigned and not part of a route plan.
Joining Tasks
Joining tasks will delete the original tasks that were joined. When joining two tasks, fields that are not specific to either the pickup or delivery component will take the delivery task's value when the joined pickup and delivery have different values for the field, with the following exceptions:
props.size,props.weightandprops.priority: the largest value between both tasks is selectedname: the name of the new task will be${pickup.name} to ${delivery.name}vehicleTypes: the intersection of both tasks' list of vehicle types is takenlabels: the union of both tasks' labels is takennotes: the union of both tasks' notes is takendeduplicationId: a new unique id is generated
Additionally, tasks with different routeDate, routeEid, vehicleEid cannot be joined.
Splitting a Task
Splitting a task will delete the original task that was split. When splitting a task, fields that are not specific to either the pickup or delivery component will share the same value in the resulting pickup and delivery tasks, with the following exceptions:
name: if the split task's name follows the pattern${pickupLocation.name} to ${deliveryLocation.name}, the resulting pickup task's name will bepickupLocation.nameand the delivery's,deliveryLocation.name. Otherwise, both resulting task will have the same namelabels: all labels are copied to both the new pickup and delivery. if a previously joined task is being split, the labels will instead return to the resulting tasks according to which task they were joined from. For example, if an original pickup and original delivery are joined, then later split, the labels on the original pickup will go to the new pickup, and the labels on the original delivery will go to the new deliverydeduplicationId:_pickupor_deliveryis appended to the end of the original task's deduplicationId
POST https://api.wisesys.info/task/{id}?action=split
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; id of a two-part task |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | SplitTaskResponse | Resulting split tasks |
POST /task/8dc4d2b0-f051-4eba-a818-582e7082b1e1?action=split HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def splitTask(self, taskId):
r = requests.post(self.API_URL+"task/" + task_id + "?action=split",
headers=self.JSON_HEADER)
if r.status_code != 200:
print(r.status_code, r.reason)
return r.json()
Split task response example
{
"meta": {},
"data": {
"pickup": {
"status": 0,
"routeDate": "2021-02-17",
"name": "Wise Systems Boston",
"vehicleTypes": [],
"vehicleEid": "",
"eorder": 0,
"deduplicationId": "fd1bb31a-ae93-4c31-b4f4-c635e15bc228",
"pickupContact": {
"phone": "+15558632637",
"name": "Test Driver"
},
"pickupLocation": {
"customer": "b91e4670-4d58-11e8-a033-85499a9e6935",
"city": "Cambridge",
"name": "Wise Systems Boston",
"country": "USA",
"parking": [],
"zipcode": "02140",
"state": "MA",
"addressLine2": "",
"location": {
"lat": 42.3884594819908,
"lng": -71.13210071322288
},
"addressLine1": "84 Sherman St",
"id": "61111310-4743-11e8-a86b-25dc69243966"
},
"props": {
"pickupServiceTime": "PT0H10M0S",
"weight": 25,
"pickupTime": "2021-02-17T16:15:12.072Z",
"priority": 1,
"pickupWindow": [
{
"start": "2021-02-17T16:15:12.072Z",
"end": "2021-02-17T23:36:12.072Z"
}
],
"size": 2
},
"id": "f0b1f803-f347-4497-8f12-8b393ef35b21",
"euid": ""
},
"delivery": {
"status": 0,
"routeDate": "2021-02-17",
"name": "Wise Systems Montreal",
"vehicleTypes": [],
"vehicleEid": "",
"eorder": 0,
"deduplicationId": "68e4b1ff-7a97-428a-8568-c3566d62f474",
"deliveryContact": {
"phone": "+15558632639",
"name": "Test Driver"
},
"deliveryLocation": {
"customer": "8ce532cf-b8da-4eec-8d1e-784132d39a1f",
"city": "Montreal",
"name": "Wise Systems Montreal",
"country": "CA",
"parking": [],
"zipcode": "H2X 1X2",
"state": "QC",
"addressLine2": "",
"location": {
"lat": 45.513062676562704,
"lng": -73.56901907776765
},
"addressLine1": "51 Sherbrooke St",
"id": "c7d7a69e-0d10-4ba4-a7f6-6882f32102e9"
},
"props": {
"deliveryServiceTime": "PT0H10M0S",
"weight": 25,
"deliveryTime": "2021-02-17T16:15:12.072Z",
"priority": 1,
"deliveryWindow": [
{
"start": "2021-02-17T16:15:12.072Z",
"end": "2021-02-17T23:36:12.072Z"
}
],
"size": 2
},
"id": "b086bdbe-2e53-4f1a-867a-1ac169b70f91",
"euid": ""
}
}
}
POST https://api.wisesys.info/task/{id}?action=join
QUERY STRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; id of a delivery or pickup task |
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| joinedTask | UUID | Required; id of a delivery or pickup task |
Note: The query string task id should be for an existing pickup task and the request body joinedTask id should be for an existing delivery task, or vice-versa. Two tasks of the same type cannot be joined.
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | Task | Resulting two-part task |
POST /task/8dc4d2b0-f051-4eba-a818-582e7082b1e1?action=join HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def splitTask(self, pickupId, deliveryId):
r = requests.post(self.API_URL+"task/" + pickupId + "?action=join",
data={"joinedTask": deliveryId},
headers=self.JSON_HEADER)
if r.status_code != 200:
print(r.status_code, r.reason)
return r.json()
Join tasks response example
{
"meta": {},
"data": {
"status": 0,
"routeDate": "2021-02-17",
"name": "Wise Systems Boston",
"vehicleTypes": [],
"vehicleEid": "",
"eorder": 0,
"deduplicationId": "fd1bb31a-ae93-4c31-b4f4-c635e15bc228",
"pickupContact": {
"phone": "+15558632637",
"name": "Test Driver"
},
"pickupLocation": {
"customer": "b91e4670-4d58-11e8-a033-85499a9e6935",
"city": "Cambridge",
"name": "Wise Systems Boston",
"country": "USA",
"parking": [],
"zipcode": "02140",
"state": "MA",
"addressLine2": "",
"location": {
"lat": 42.3884594819908,
"lng": -71.13210071322288
},
"addressLine1": "84 Sherman St",
"id": "61111310-4743-11e8-a86b-25dc69243966"
},
"deliveryContact": {
"phone": "+15558632639",
"name": "Test Driver"
},
"deliveryLocation": {
"customer": "8ce532cf-b8da-4eec-8d1e-784132d39a1f",
"city": "Montreal",
"name": "Wise Systems Montreal",
"country": "CA",
"parking": [],
"zipcode": "H2X 1X2",
"state": "QC",
"addressLine2": "",
"location": {
"lat": 45.513062676562704,
"lng": -73.56901907776765
},
"addressLine1": "51 Sherbrooke St",
"id": "c7d7a69e-0d10-4ba4-a7f6-6882f32102e9"
},
"props": {
"pickupServiceTime": "PT0H10M0S",
"deliveryServiceTime": "PT0H10M0S",
"weight": 25,
"pickupTime": "2021-02-17T16:15:12.072Z",
"deliveryTime": "2021-02-17T16:15:12.072Z",
"priority": 1,
"pickupWindow": [
{
"start": "2021-02-17T16:15:12.072Z",
"end": "2021-02-17T23:36:12.072Z"
}
],
"deliveryWindow": [
{
"start": "2021-02-17T16:15:12.072Z",
"end": "2021-02-17T23:36:12.072Z"
}
],
"size": 2
},
"id": "f0b1f803-f347-4497-8f12-8b393ef35b21",
"euid": ""
}
}
Pair Pickup and Delivery Tasks
Optimally pair pickup tasks with delivery tasks, and vice versa, considering time windows, inventory (truck) type and distance between tasks. Pairing generation may be triggered for a specific date or set of tasks.
When pairing is triggered by date, the Wise Systems Optimization Engine will attempt to pair all unassigned tasks that begin on that date.
When pairing is triggered for specific tasks, the Wise Systems Optimization Engine will first attempt to pair a task passed in taskIds with other tasks passed in taskIds. If the Optimization Engine is unable to find a valid pair within taskIds, it will attempt to find a pair in unassignedTaskIds. If no valid pair is found within taskIds or unassignedTaskIds the task will not be paired.
POST /tasks/pairings?action=generate
QUERY STRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| route_date | string | Optional; given in YYYY-MM-DD format, pair all tasks for given route date |
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| taskIds | list of UUIDs | Required; array of the ids of tasks to be paired |
| unassignedTaskIds | list of UUIDs | Optional; array of the ids of tasks available to be paired with |
Request body JSON example
{
"taskIds": ["61111310-4743-11e8-a86b-25dc69243966"],
"unassignedTaskIds": ["0f4472e0-4ce4-11ea-957d-c9797b6a9c15", "c7d7a69e-0d10-4ba4-a7f6-6882f32102e9"]
}
Requests Expected to generate 422 (Unprocessable Entity) Response:
- Number of task ids in taskIds is less than one.
- Total number of task ids in request (taskIds + unassignedTaskIds ) is less than two.
- Given task ids do not correspond to at least one unassigned delivery task and one unassigned pickup task.
- Given routeDate is not in YYYY-MM-DD format.
- There is not at least one unassigned delivery and one unassigned pickup task on given routeDate.
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | UUID | Contains: |
| runId (UUID) | ||
| clientId (UUID) |
Return body JSON example
{
"meta": {},
"data": {
"runId": "14f4d3c0-2fba-11e5-891f-9d3d0c07dabb",
"clientId": "766a3636-2e54-4a97-8be5-82dc7ddc9899"
}
}
Mark Tasks as Eligible for Pairing
Given task ids, marks all the tasks as eligible for pairing in bulk. If a given task is already marked as eligible, then no action is taken on that task. Returns a NotFoundError if no task is found for a given task id.
POST https://api.wisesys.info/task/{id}?action=mark_eligible
RESPONSE BODY
| Parameter | Type | Description |
|---|---|---|
| taskIds | list of UUIDs | Required; array of the ids of tasks to be marked as eligible |
Request body JSON example
{
"taskIds": ["0f4472e0-4ce4-11ea-957d-c9797b6a9c15", "c7d7a69e-0d10-4ba4-a7f6-6882f32102e9"]
}
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| modifiedTasksCount | Number | Number of modified tasks |
Successful Request Example
{
"meta": {
"status": 0,
"message": ""
},
"modifiedTaskCount": 2
}
404 Bad Request Example
{
"meta": {
"status": 2,
"message": "Some tasks ids not found"
},
"modifiedTaskCount": 0
}
RESPONSE STATUS CODES
- 200 OK: Task was successfully marked as eligible
- 404 NotFoundError: Task of given id was not found
Mark Tasks as Ineligible for Pairing
Given task ids, marks all the tasks as ineligible for pairing in bulk. If a given task is already marked as ineligible, then no action is taken on that task. Returns a NotFoundError if no task is found for a given task id.
POST https://api.wisesys.info/task/{id}?action=mark_ineligible
RESPONSE BODY
| Parameter | Type | Description |
|---|---|---|
| taskIds | list of UUIDs | Required; array of the ids of tasks to be marked as eligible |
Request body JSON example
{
"taskIds": ["0f4472e0-4ce4-11ea-957d-c9797b6a9c15", "c7d7a69e-0d10-4ba4-a7f6-6882f32102e9"]
}
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| modifiedTasksCount | Number | Number of modified tasks |
Successful Request Example
{
"meta": {
"status": 0,
"message": ""
},
"modifiedTaskCount": 2
}
404 Bad Request Example
{
"meta": {
"status": 2,
"message": "Some tasks ids not found"
},
"modifiedTaskCount": 0
}
RESPONSE STATUS CODES
- 200 OK: Task was successfully marked as eligible
- 404 NotFoundError: Task of given id was not found
Add a Depot Pickup/Delivery to a Task
For a specific date, pair all unpaired pickups or deliveries with the appropriate counterpart depot tasks. For instance, an unpaired delivery task will be matched with a depot pickup.
/tasks/pairings?action=depot_pair
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| taskIds | list of UUIDs | Required; array of the ids of tasks to be paired |
{
"taskIds": ["61111310-4743-11e8-a86b-25dc69243966", "ed0705b1-3fe8-4a2a-b3ff-47b707ea0fad"]
}
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | object | contains: |
| tasksModifiedCount (integer) | ||
| inventoryCreatedCount (integer) | ||
| unacceptedTaskIds (array of UUIDs) |
{
"meta": {},
"data": {
"tasksModifiedCount": 3,
"inventoryCreatedCount": 0,
"unacceptedTaskIds": []
}
}
Move task to another client
- A planned task can be moved to another route in a different client.
- The task can either be from (1) a route with a driver or from (2) a route without a driver.
- The target driver can either be assigned to (3) an existing route or (4) be a dummy driver.
- Routes without drivers have
driverIds that start withdummy. - Target client id is required if the route does not have a driver.
- Routes without drivers have
PATCH /task/71740331-3503-1134-1922-169719251371 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
"""// Move task to another client"""
def multi_client_move_task(self, task_id, target_driver_id, target_client_id=None):
body = {
"taskId": task_id,
"driverId": target_driver_id
}
if target_client_id:
body["clientId"] = target_client_id
r = requests.patch(self.API_URL + "task?action=move", json=body, headers=self.JSON_HEADER)
if r.status_code is not 200:
print(r.status_code, r.reason)
return r.json()
Move task to another client response example
{
"data": {
"schedulerTaskIds": [
{
"clientId": "ed0705b1-3fe8-4a2a-b3ff-47b707ea0fad",
"schedulerTaskId": "dc2125be-9105-4427-b879-02ffb5e7bd42"
},
{
"clientId": "5c087850-2a99-11e5-9189-eb07c479dfd5",
"schedulerTaskId": "2d9812bb-b7d1-455c-b637-1fe7f8855d75"
}
],
"task": {
"name": "task-1",
"pickupContact": "9zb834c0-41ab-31e5-33c1-9ca1d2723de2",
"pickupLocation": "14e93b00-2fba-11e5-891f-9d3d0c07dabb",
"deliveryContact": "5ca935b0-31ab-41e5-93c1-5ba1d2723ce5",
"deliveryLocation": "14f43780-2fba-11e5-891f-9d3d0c07dabb",
"props": {
"priority": 1,
"size": 2,
"weight": 25,
"pickupTime": "2015-06-29T16:34:41.000Z",
"pickupServiceTime": "PT30M",
"pickupWindow": [
{
"start": "2015-06-29T16:30:00.000Z",
"end": "2015-06-29T16:45:00.000Z"
}
],
"deliveryTime": "2015-06-29T20:35:00.000Z",
"deliveryServiceTime": "PT30M",
"deliveryWindow": [
{
"start": "2015-06-29T20:30:00.000Z",
"end": "2015-06-29T20:50:00.000Z"
}
]
},
"id": "14f4d3c0-2fba-11e5-891f-9d3d0c07dabb",
"status": 1
}
},
"meta": {}
}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; task Id |
| action | string | Required; Must be move |
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| driverId | UUID | Required; Must belong to a different client |
| clientId | UUID | Optional; Required when driverId is a dummy driver id |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data.schedulerTaskIds | List of SchedulerTaskId Object | Length = 2; 1 for each client updated |
| data.task | TaskObject | Newly created task |
SchedulerTaskId Object
| Parameter | Type | Description |
|---|---|---|
| clientId | UUID | |
| schedulerTaskId | UUID |
Move multiple tasks to another client
- Multiple planned tasks can be moved to another route in a client.
- Tasks to be moved can belong to many different clients or the same client.
- Tasks can be moved to a route in a different client or one of the client's where a task originated from.
- All request entites can belong to the same client.
- Tasks can either be from (1) a route with a driver or from (2) a route without a driver.
- The target driver can either be assigned to (3) an existing route or (4) be dummy driver.
- Routes without drivers have
driverIds that start withdummy. - Target client id is required if the route does not have a driver.
- Routes without drivers have
PATCH /tasks HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
"""// Move task to another client"""
def multi_client_move_tasks(self, task_ids, target_driver_id, target_client_id=None):
body = {
"taskIds": task_ids,
"driverId": target_driver_id
}
if target_client_id:
body["clientId"] = target_client_id
r = requests.patch(self.API_URL + "tasks?action=move_route", json=body, headers=self.JSON_HEADER)
if r.status_code is not 200:
print(r.status_code, r.reason)
return r.json()
Move tasks to another client response example
{
"data": {
"schedulerTaskIds": [
{
"clientId": "ed0705b1-3fe8-4a2a-b3ff-47b707ea0fad",
"schedulerTaskId": "dc2125be-9105-4427-b879-02ffb5e7bd42"
},
{
"clientId": "5c087850-2a99-11e5-9189-eb07c479dfd5",
"schedulerTaskId": "2d9812bb-b7d1-455c-b637-1fe7f8855d75"
}
],
"taskIds": [
"6587be42-9135-46ff-abd3-e225f5090c8c",
"78c617c4-c898-4cb2-a136-a512f93d4ad9"
]
},
"meta": {}
}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| action | string | Required; Must be move_route |
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| taskIds | List of UUIDs | Required; |
| driverId | UUID | Required; Must belong to a different client |
| clientId | UUID | Optional; Required when driverId is a dummy driver id |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data.schedulerTaskIds | List of SchedulerTaskId Object | One for each client involved in the request |
| data.taskIds | List of UUIDs | Newly created task ids |
SchedulerTaskId Object
| Parameter | Type | Description |
|---|---|---|
| clientId | UUID | |
| schedulerTaskId | UUID |
PATCH /tasks HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
"""// Move task to another client"""
def multi_client_move_tasks(self, task_ids, target_driver_id, target_client_id=None):
body = {
"taskIds": task_ids,
"targetDriverId": target_driver_id
}
if target_client_id:
body["targetClientId"] = target_client_id
r = requests.patch(self.API_URL + "tasks?action=move_route", json=body, headers=self.JSON_HEADER)
if r.status_code is not 200:
print(r.status_code, r.reason)
return r.json()
Move task to another client response example
{
"data": {
"schedulerTaskIds": [
{
"clientId": "ed0705b1-3fe8-4a2a-b3ff-47b707ea0fad",
"schedulerTaskId": "dc2125be-9105-4427-b879-02ffb5e7bd42"
},
{
"clientId": "5c087850-2a99-11e5-9189-eb07c479dfd5",
"schedulerTaskId": "2d9812bb-b7d1-455c-b637-1fe7f8855d75"
}
],
"taskIds": [
"6587be42-9135-46ff-abd3-e225f5090c8c",
"78c617c4-c898-4cb2-a136-a512f93d4ad9"
]
},
"meta": {}
}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| action | string | Required; Must be move_route |
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| taskIds | List of UUIDs | Required; |
| driverId | UUID | Required; Must belong to a different client |
| clientId | UUID | Optional; Only required for dummy drivers |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data.taskIds | List of UUIDs | Newly created task ids |
| data.schedulerTaskIds | List of SchedulerTaskId Object | One for each client involved in the request |
SchedulerTaskId Object
| Parameter | Type | Description |
|---|---|---|
| clientId | UUID | |
| schedulerTaskId | UUID |
Move planned route tasks to future date
A planned route can be moved in it's entirety to a new route date.
- Tasks from the route will be removed from the original date's route plan.
- The tasks will be unplanned for the new route date until Route Planner runs for that date.
- The stop order of the route will be maintained when Route Planner creates a new route plan if a new EID is provided. Otherwise, stop order will not be preserved.
- If a new EID is provided in the request payload, the EID fields on the tasks on the route will be updated to match the new EID.
- Task routeDate will be updated to the new route date. pickupWindow, deliveryWindow, pickupTime and deliveryTime will be updated to have the same relative values of the new route date.
POST /schedules/evaluate?action=postpone&accept HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def postpone_route(self, date, new_date, route_id, new_eid=None):
body = {
"date": date,
"newDate": new_date,
"routeId": route_id,
"type": "Scheduler"
}
if new_eid:
body["newEid"] = new_eid
r = requests.patch(self.API_URL + "schedules/evaluate?action=postpone&accept", json=body, headers=self.JSON_HEADER)
if r.status_code is not 200:
print(r.status_code, r.reason)
return r.json()
Postpone route response example
{
"meta": {},
"data": {
"schedulerTaskIds": "df8a5ab6-c4a4-4d51-81f3-78474c68c532",
"taskIds": [
"6587be42-9135-46ff-abd3-e225f5090c8c",
"78c617c4-c898-4cb2-a136-a512f93d4ad9",
"6d47a511-1faa-40a4-b34c-ff00bbe00edd",
"fa9278b7-aa88-4592-a179-a36bbdba28c4",
"f1aad972-b167-4132-ad4b-1462c7c5de9f"
]
}
}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| action | string | Required; Must be postpone |
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| date | string | Required in format "YYYY-MM-DD"; |
| newDate | string | Required in format "YYYY-MM-DD"; |
| routeId | UUID | Required; UUID of route to be moved |
| newEid | string | Optional; Sets the routeEid or other EIDs set on the tasks |
| type | string | Required; must be "Scheduler" |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data.schedulerTaskId | UUID | Scheduler Task UUID |
| data.taskIds | List of UUIDs | Ids of tasks successfully moved to future date |
Assignments
An assignment in the Wise Systems platform is derived from a Task and represents a stop that is assigned to an active, dispatched driver. You can manually assign a task to a driver (if not auto-assigned), view the current assignments, modify an assignment, or remove an assignment.
GET https://api.wisesys.info/assignments{?extent}{?page}{?limit}
List all Assignments
GET /assignments HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def getAssignments(self, limit=1000, page=0, extents=None):
url = self.__get_request_url("assignments", limit, page, extents)
r = requests.get(url, headers=self.JSON_HEADER)
if r.status_code != 200:
print(r.status_code, r.reason)
return r.json()
List assignments response example
{
"meta": {
"page": 0,
"limit": 3,
"total": 32
},
"data": [
{
"id": "7b7g0f2c-g523-11f4-c9h4-1697f925ec7b",
"type": "delivery",
"location": "16e5b1d0-3bf0-11e5-9206-1324edd52c4d",
"contact": {
"name": "Homer Kwan",
"phone": "+15552581001"
},
"props": {
"time": "2015-06-20T16:34:41.000Z",
"serviceTime": "PT30M",
"window": {
"start": "2015-06-20T16:34:41.000Z",
"end": "2015-06-20T16:34:41.000Z"
}
},
"task": "84788f56-c617-4c2b-8677-53de01fb47fe",
"driver": "7a740f3c-f503-11e4-b9b2-1697f925ec7b",
"eta": "PT10M36S",
"completedAt": "2015-08-24T20:26:21.007Z",
"status": 2
}
]
}
List assignments of active tasks to drivers. Active tasks are those that have not been completed (status of 0, 1, or 2).
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| extent | string | Optional; name of field which shows its detail |
| page | int | Optional; defaults to 0; the pagination offset to return |
| limit | int | Optional; default to 10; the pagination limit of each page |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | List of AssignmentObject | List of assignments |
Create Assignment
POST /assignment HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def addAssignment(self, data):
r = requests.post(self.API_URL+"assignment", json=data, headers=self.JSON_HEADER)
if r.status_code != 200:
print r.status_code, r.reason
return r.status_code, r.json()
Create assignment request example
{
"task": "45ba3660-f8e9-11e4-a322-1697f925ec7b",
"driver": "45ba38a4-f8e9-11e4-a322-1697f925ec7b"
}
Create assignment response example (delivery)
{
"meta": {},
"data": [
{
"status": 0,
"task": "f0b1f803-f347-4497-8f12-8b393ef35b21",
"name": "Tatte to Flour",
"driver": "80d20df0-2025-11ea-9d44-cbee967533a6",
"contact": {
"phone": "+15558632637",
"name": "Test Driver"
},
"client": "5c087850-2a99-11e5-9189-eb07c479dfd5",
"location": {
"lat": 42.35901399999999,
"lng": -71.0947224
},
"props": {
"weight": 25,
"priority": 1,
"window": [
{
"start": 1576512912,
"end": 1576539372
}
],
"serviceTime": 600,
"time": 1576512912,
"size": 2
},
"type": "delivery",
"id": "fc9871b0-2046-11ea-9d44-cbee967533a6"
}
]
}
Create assignment response example (pickup and delivery)
{
"meta": {},
"data": [
{
"status": 0,
"task": "f0b1f803-f347-4497-8f12-8b393ef35b21",
"name": "Tatte to Flour",
"driver": "80d20df0-2025-11ea-9d44-cbee967533a6",
"contact": {
"phone": "+15558632637",
"name": "Test Driver"
},
"client": "5c087850-2a99-11e5-9189-eb07c479dfd5",
"location": {
"lat": 42.35901399999999,
"lng": -71.0947224
},
"props": {
"weight": 25,
"priority": 1,
"window": [
{
"start": 1576511912,
"end": 1576538372
}
],
"serviceTime": 600,
"time": 1576511912,
"size": 2
},
"type": "pickup",
"id": "fc9871b0-2046-11ea-9d44-cbee967533a6"
},
{
"status": 0,
"task": "f0b1f803-f347-4497-8f12-8b393ef35b21",
"name": "Tatte to Flour",
"driver": "80d20df0-2025-11ea-9d44-cbee967533a6",
"contact": {
"phone": "+15558632637",
"name": "Test Driver"
},
"client": "5c087850-2a99-11e5-9189-eb07c479dfd5",
"location": {
"lat": 42.35901399999999,
"lng": -71.0947224
},
"props": {
"weight": 25,
"priority": 1,
"window": [
{
"start": 1576512912,
"end": 1576539372
}
],
"serviceTime": 600,
"time": 1576512912,
"size": 2
},
"type": "delivery",
"id": "fc9871b0-2046-11ea-9d44-cbee967533a6"
}
]
}
Assign a task to a vehicle. This call will create an assignment for each unit of work that needs to be completed. A single assignment will be created for a single pickup or delivery task. Two assignments will be created for a task requiring a pickup and a delivery.
If the task's position is not provided, the system will find the best position in the driver's route to insert the task, while making sure vehicle constraints (such as capacity) are respected. Otherwise, that insertion position will be used and vehicle constraints won't be verified.
The system returns a success message with assignments with ETAs for the vehicle. The task status will be changed from unassigned (0) to assigned (1).
By default, an assignment is created even if an ETA calculation fails. If this is not desired,
optional query string require_eta=true can be passed. This will roll back and delete the created assignment
if the ETA calculation fails.
This process takes some time: please allow for around 10 to 20 seconds for the assignment to be cleaned up.
POST https://api.wisesys.info/assignment
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| task | UUID | Task's unique Id |
| driver | UUID | Driver's unique Id |
| pickupPosition | [Number] | (optional) Position returned by the Suggest Drivers method for a pickup task. If omitted, the system will calculate the optimal insertion position. |
| deliveryPosition | [Number] | (optional) Position returned by the Suggest Drivers method for a delivery task. If omitted, the system will calculate the optimal insertion position. |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | List of Assignment | Assignments, one for pickup and delivery parts of the task |
Optional Query Parameters
| Parameter | Type | Description |
|---|---|---|
| require_eta | Boolean | If true, an assignment created will be deleted if the ETA calculation fails |
Retrieve an Assignment
GET /assignment/71740133-1503-1104-1912-169739251179 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def getAssignment(self, asgn_id):
r = requests.get(self.API_URL + "assignment/" + asgn_id, headers=self.JSON_HEADER)
if r.status_code != 200:
print(r.status_code, r.reason)
return r.json()
Retrieve assignment response example
{
"meta": {},
"data": {
"type": "delivery",
"task": "14f4d3c0-2fba-11e5-891f-9d3d0c07dabb",
"location": "14f43780-2fba-11e5-891f-9d3d0c07dabb",
"driver": "14f7b9f0-2fba-11e5-891f-9d3d0c07dabb",
"props": {
"time": "2015-06-29T20:35:00.000Z",
"window": [
{
"end": "2015-06-29T20:50:00.000Z",
"start": "2015-06-29T20:30:00.000Z"
}
]
},
"id": "14ffd040-2fba-11e5-891f-9d3d0c07dabb",
"eta": "PT52M36S",
"status": 0
}
}
Get an assignment by id. Returns the assignment details including the vehicle, ETA, and status.
GET https://api.wisesys.info/assignment/{id}{?extent}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; task Id |
| extent | string | Optional; name of field which shows its detail |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | AssignmentObject | Assignment info |
Update Assignment
PUT /assignment/11423814-38e9-11e4-1322-169749250073 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def updateAssignment(self, asgn_id, data):
r = requests.put(self.API_URL + "assignment/" + asgn_id, json=data, headers=self.JSON_HEADER)
if r.status_code is not 200:
print r.status_code, r.reason
return r.json()
Update assignment request example
{
"props": {
"window": [
{
"end": "2015-06-29T20:50:00.000Z",
"start": "2015-06-29T20:30:00.000Z"
}
]
}
}
Update assignment information. You can only modify a subset of fields through this endpoint - see below.
PUT https://api.wisesys.info/assignment/{id}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; unique assignment Id |
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| contact | Contact | Contact information |
| props | AssignmentProps | Assignment properties - inventory and newWindow properties can't be modified through this endpoint - use Update Assignment Inventory Update Assignment Time Window respectively |
| location | UUID | Address ID of the location where the assignment takes place |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | AssignmentObject | Updated assignment info |
Bulk Update Assignments
Note: This endpoint is disabled by default, make sure it is enabled for your client. When disabled, the endpoint will return an HTTP 403 error.
Only assignments that are not arrived, completed or canceled may be updated.
Changing the location and service times may affect ETAs. New ETAs may not be calculated immediately and will likely be updated following the next driver location update.
When logged in as a driver, you may only update assignments for the driver you are logged in as. Trying to update an assignment that doesn't belong to the driver will result in a 403 HTTP error.
When logged in as a dispatcher, all eligible assignments can be updated.
PATCH /assignments HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def updateAssignments(self, asgn_id, data):
r = requests.patch(self.API_URL + "assignments", json=data, headers=self.JSON_HEADER)
if r.status_code is not 200:
print r.status_code, r.reason
return r.json()
Update assignments request example
The following payload updates the service time of the task associated with
assignment id 1d514c3f-719e-40c4-9bc7-28671355daff to 15 minutes and changes
its location to the specified latitude and longitude. It also changes the
service time of the task associated with assignment id
922289bb-b697-4e23-be45-6c7e40ac95d6 to an 1 hour 30 minutes and its location
to the specified latitude and longitude.
{
"1d514c3f-719e-40c4-9bc7-28671355daff": {
"serviceTime": "PT15M",
"location": {
"lat": 42.388396,
"lng": -71.132186
}
},
"922289bb-b697-4e23-be45-6c7e40ac95d6": {
"serviceTime": "PT1H30M",
"location": {
"lat": 45.505741,
"lng": -73.568294
}
}
}
Update assignment information. You can only modify a subset of fields through this endpoint - see below.
PATCH https://api.wisesys.info/assignments
REQUEST BODY
The request body consists of a key-value map where the key of each entry is the id of an assignment to be updated, and the value is an object containing the fields to be updated. The following properties are available for update.
| Parameter | Type | Description |
|---|---|---|
| serviceTime | String | Service time duration in ISO-8601 Duration notation |
| location | Location Data Model | New location of the assignment |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | Assignment Updates Response Data Model | Updated assignment info |
Delete an Assignment
DELETE /assignment/71740133-1503-1104-1912-169739251179 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def deleteAssignment(self, asgn_id):
r = requests.delete(self.API_URL + "assignment/" + asgn_id, headers=self.JSON_HEADER)
if r.status_code is not 200:
print(r.status_code, r.text)
return r.json()
Delete response example
{
"meta": {
"status": 0,
"message": "The resource was removed successfully"
},
"data": {
"id": "70a3cb60-f502-11e4-b9b2-1697f925ec7b",
"options": [
{
"driver": "djllz490--4e4a-480c-bbf7-d266c88e5fa5",
"eta": "2015-04-12T18:51:19Z"
}
]
}
}
Remove an assignment of a task from a driver. The task is still active and needs to be fulfilled. The system will remove the assignment and return a success message. The task is unassigned (status of 0) and will need to be reassigned.
DELETE https://api.wisesys.info/assignment/{id}{?extent}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; assignment Id |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | DeleteAssignmentObject | Return deleted assignment Id |
Update Assignment Status
PATCH /assignment/71740133-1503-1104-1912-169739251179 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def updateAssignmentStatus(self, asgn_id, code):
data = {"status": code}
url = self.API_URL+"assignment/" + asgn_id + "/status"
r = requests.patch(url, json=data, headers=self.JSON_HEADER)
if r.status_code is not 200:
print(r.status_code, r.reason)
return r.status_code, r.text
Update assignment request example
{
"status": 1,
"timestamp": "2015-08-13T21:00:00.000Z"
}
Response body JSON example
{
"meta": {
"status": 0,
"message": "The resource was updated successfully"
},
"data": {
"id": "7a740f3c-f503-11e4-b9b2-1697f925ec7b"
}
}
Updates the status of an assignment: * 0: Not Started * 1: In Progress - driver currently working on the assignment) * 2: Complete - the timestamp field is optional and useful if the status update happened in the past (e.g., the status was locally saved to the phone and then sent to Wise Systems when the connection was re-established)
PATCH https://api.wisesys.info/assignment/{id}/status
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; assignment Id |
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| status | int | Status of the assignment; for more info refer to this table |
| timestamp | DateTime | Optional; the date and time when the status was updated |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | IdObject | Return Id of the updated assignment |
Update Assignment Time Window
PATCH /assignment/71740133-1503-1104-1912-169739251179/timewindow HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def editTimeWindow(self, asgn_id, data):
r = requests.patch(self.API_URL + "assignment/" + asgn_id + "/timewindow",
json=data, headers=self.JSON_HEADER)
if r.status_code != 200:
self.notify("Failed when calling PATCH Edit Time Window: "+r.text)
return r.json()
Request body JSON example
{
"start": "2015-08-13T21:00:00.000Z",
"end": "2015-08-13T22:30:00.000Z"
}
Response body JSON example
{
"meta": {
"status": 0,
"message": "The resource was updated successfully"
},
"data": {
"id": "7a740f3c-f503-11e4-b9b2-1697f925ec7b"
}
}
This call logs a time window change request from the driver, but does not actually modify the live task or assignment's time window. This new time window is outputted to a downloadable report for managers to review and incorporate into their own systems. It will not be immediately used by Wise Systems for routing. To actually update a live assignment's time window, see PUT /assignment.
PATCH https://api.wisesys.info/assignment/{id}/timewindow
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; assignment Id |
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| start | DateTime | Start of the assignment time |
| end | DateTime | End of the the assignment time |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | IdObject | Return Id of the updated Assignment |
Auto Depart
PATCH /assignment/71740133-1503-1104-1912-169739251179/autodepart HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def autoDepart(self, asgn_id, timestamp):
data = {"timestamp": timestamp}
r = requests.patch(self.API_URL + "assignment/" + asgn_id + "/autodepart",
json=data, headers=self.JSON_HEADER)
if r.status_code != 200:
self.notify("Failed when calling PATCH Auto depart: "+r.text)
return r.json()
Request body JSON example
{
"timestamp": "2015-08-13T12:29:51.000Z"
}
Response body JSON example
{
"meta": {
"status": 0,
"message": "The resource was updated successfully"
},
"data": {
"id": "7a740f3c-f503-11e4-b9b2-1697f925ec7b"
}
}
Logs an auto-depart for an assignment — calling this endpoint does not update the assignment status.
PATCH https://api.wisesys.info/assignment/{id}/autodepart
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; assignment Id |
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| timestamp | DateTime | Time when the driver automatically departed from a stop |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | IdObject | Return Id of the updated assignment |
Update Assignment Address
PATCH /assignment/{id}/address/{id} HTTP/1.1
Accept: application/json
Authorization: Bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def patch_assignment_address(self, adr_id, asgn_id, data):
r = self.SESSION.patch(self.API_URL + "assignment/" + asgn_id + "/address/" + adr_id, json=data,
headers=self.JSON_HEADER)
if r.status_code is not 200:
print(r.status_code, r.reason)
return r.status_code, r.json()
Update assignment address request example
{
"name": "Tunis Logistics",
"addressLine1": "2100 Flagstaff Street",
"addressLine2": "",
"city": "Cambridge",
"state": "MA",
"zipcode": "02142",
"country": "USA",
"location": {
"lat": 42.999,
"lng": -71.999
}
}
This endpoint provides drivers with a mechansim for updating assignment address. This endpoint can be called exclusively with driver role.
PATCH https://api.wisesys.info/assignment/{assignmentId}/address/{addressId}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| assignmentId | UUID | Required; unique assignment Id |
| addressId | UUID | Required; unique address Id |
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| name | String | Address name |
| addressLine1 | String | The street address |
| addressLine2 | String | Additional non-standard details like apartment number, suite number, and other info |
| city | String | The city of the address |
| state | String | The two-letter abbreviation of the state or province of the address |
| zipcode | String | The zip or postal code of the address |
| country | String | The code country of the address in ISO codes |
| location | Location | Optional and will be recomputed based on other properties if not explicitly provided |
Requests expected to generate 422 (Unprocessable Entity) response:
- Either address, assignment, client id, list of clients that the user has access to, or the change address is missing.
- The address from the query parameter doesn't belong to the assignment from the query parameter.
Requests Expected to generate 403 (Forbidden) response:
- The logged-in user doesn't have
driverrole. - The address from the query parameter doesn't belong to the logged-in driver.
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | IdObject | Return new address |
Successfull response example (200)
{
"meta":{
},
"data":{
"geoLocation":{
"type":"Point",
"coordinates":[
-71.999,
42.999
]
},
"name":"Tunis Logistics",
"city":"Cambridge",
"country":"USA",
"parking":[
],
"zipcode":"02142",
"state":"MA",
"addressLine2":"",
"timeMoved":0,
"addressLine1":"2100 Flagstaff Street",
"id": "aeca5e74-1f12-47ba-a113-77bf528da578",
"location":{
"lat":42.999,
"lng":-71.999
}
}
Unprocessable Entity response example (422)
{
"meta": {
"status": 3,
"message": "Address abb75212-913b-4e3e-9b13-c2de6091638a doesn't belong to assignment
04d1a5e8-c65e-499d-a570-84e9f0490bfb"
},
"data": {}
}
Addresses
Addresses in the Wise Systems platform represent the destination for deliveries or pickups. The platform stores the address information along with the geocoded latitude and longitude coordinates for future usage. Address information is a property of drivers and tasks. You can manually create an address for a task or a driver (if not provided automatically), view existing addresses in the database, and modify addresses. The platform will geocode the address for future usage.
List all Addresses
GET /addresses HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def getAddresses(self, limit=1000, page=0):
url = self.__get_request_url("addresses", limit, page)
r = requests.get(url, headers=self.JSON_HEADER)
if r.status_code != 200:
print(r.status_code, r.reason)
return r.json()
Response body JSON example
{
"meta": {
"status": 0
},
"data": [{
"id": "45ba38a4-f8e9-11e4-a322-1697f925ec7b",
"name": "MIT Bookstore",
"addressLine1": "292 Main Street",
"addressLine2": "Suite 616",
"city": "Cambridge",
"state": "MA",
"zipcode": "02138",
"country": "USA",
"location": {
"lat": 42.387765,
"lng": -71.141427
}
},
{
"id": "95ba38a4-f8e9-11e4-a322-1697f925ec7b",
"name": "MIT Maseeh Hall",
"addressLine1": "77 Massachusetts Avenue",
"addressLine2": "Maseeh Hall, Room 317",
"city": "Cambridge",
"state": "MA",
"zipcode": "02138",
"country": "USA",
"location": {
"lat": 42.397765,
"lng": -71.123427
}
}
]
}
List all addresses that are currently in the system.
GET https://api.wisesys.info/addresses{?page}{?limit}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| page | int | Optional; defaults to 0; the pagination offset to return |
| limit | int | Optional; default to 10; the pagination limit of each page |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | list of Addresses | List of available addresses in the Wise Systems platform |
Create Address
GET /address HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def addAddress(self, data):
r = requests.post(self.API_URL+"address", json=data, headers=self.JSON_HEADER)
if r.status_code is not 200:
print r.status_code, r.reason
return r.json()
Create address request example
{
"name": "MIT Bookstore",
"addressLine1": "292 Main Street22",
"addressLine2": "Suite 616",
"city": "Cambridge",
"state": "MA",
"zipcode": "02138",
"country": "USA",
"location": {
"lat": 42.362153,
"lng": -71.08588
}
}
Create a new address in the system. The system will return a success message and make the address available for association with vehicles and tasks.
POST https://api.wisesys.info/address
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| name | String | Address name |
| addressLine1 | String | The street address |
| addressLine2 | String | Additional non-standard details like apartment number, suite number, and other info |
| city | String | The city of the address |
| state | String | The two-letter abbreviation of the state or province of the address |
| zipcode | String | The zip or postal code of the address |
| country | String | The code country of the address in ISO codes |
| location | Location | Optional and will be recomputed based on other properties if not explicitly provided |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | AddressObject | Return address along with coordinates |
Retrieve Specific Address
GET /address/11423814-38e9-11e4-1322-169749250073 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def getAddress(self, adr_id):
r = requests.get(self.API_URL + "address/" + adr_id, headers=self.JSON_HEADER)
if r.status_code != 200:
print(r.status_code, r.reason)
return r.json()
Retrieve specific address response example
{
"meta": {
"status": 0
},
"data": {
"id": "ab4a38a4-f8e9-11e4-a322-1697f925ec7b",
"name": "Tunis Logistics",
"addressLine1": "2100 Flagstaff Street",
"addressLine2": "",
"city": "Cambridge",
"state": "MA",
"zipcode": "02142",
"country": "USA",
"location": {
"lat": 42.367765,
"lng": -71.114427
},
"parking": [
{
"lat": 42.367765,
"lng": -71.114427
}
]
}
}
Get an address by id (returns the address details).
GET https://api.wisesys.info/address/{id}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; unique address Id |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | Address | Return address data |
Update Address
PUT /address/11423814-38e9-11e4-1322-169749250073 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def updateAddress(self, adr_id, data):
r = requests.put(self.API_URL + "address/" + adr_id, json=data, headers=self.JSON_HEADER)
if r.status_code is not 200:
print r.status_code, r.reason
return r.json()
Update address request example
{
"name": "Tunis Logistics",
"addressLine1": "2100 Flagstaff Street",
"addressLine2": "",
"city": "Cambridge",
"state": "MA",
"zipcode": "02142",
"country": "USA",
"location": {
"lat": 42.999,
"lng": -71.999
}
}
Update address information. You can change any fields of the address profile except for parking (see PATCH).
If any Tasks or Assignments refer to this address they will be updated automatically.
PUT https://api.wisesys.info/address/{id}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; unique address Id |
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| name | String | Address name |
| addressLine1 | String | The street address |
| addressLine2 | String | Additional non-standard details like apartment number, suite number, and other info |
| city | String | The city of the address |
| state | String | The two-letter abbreviation of the state or province of the address |
| zipcode | String | The zip or postal code of the address |
| country | String | The code country of the address in ISO codes |
| location | Location | Optional and will be recomputed based on other properties if not explicitly provided |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | IdObject | Return updated address Id |
Delete Address
DELETE /address/70133308-1502-1114-1942-169719253272 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def delete_address(self, addr_id):
r = requests.delete(self.API_URL + "address/" + addr_id, headers=self.JSON_HEADER)
if r.status_code is not 200:
print(r.status_code, r.reason)
return r.json()
Delete address response example
{
"meta": {
"status": 0,
"message": "The resource was removed successfully"
},
"data": {
"id": "703b710-3a1f-11e6-83d8-d7774a6e3894"
}
}
Delete an address record. This is available for admin user roles only. If you'd like to delete an address, always remove any "dependent" entities first to ensure safe state management. In particular, if you are deleting an address with a task or depot or customer related to it, please delete the related entity first, then safely remove the address.
Note: Do not remove the address record that is related to your hq depot.
DELETE https://api.wisesys.info/address/{id}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; unique Address Id |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | IdObject | Return unique address Id |
Update Parking Info
PATCH /address/11423814-38e9-11e4-1322-169749250073 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
Update parking request example
{
"parking": {
"lat": 42.367765,
"lng": -71.114427
}
}
Update address information. You can change any fields of the address profile except for parking (see PATCH).
PATCH https://api.wisesys.info/address/{id}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; unique address Id |
REQUEST BODY
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | IdObject | Return updated address Id |
Customers
Customers in the Wise Systems platform represent the profiles of customers at the destinations for pickups or deliveries. Customer profiles are associated with tasks to enable notifications and updates to and from customers.
List All Customers
GET /customers HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def getCustomers(self, query=None, limit=1000, page=0, extents=None):
params = {}
if query:
params["filter"] = query
url = self.__get_request_url("customers", limit, page, extents)
r = requests.get(url, params = params, headers=self.JSON_HEADER)
if r.status_code != 200:
print(r.status_code, r.reason)
return r.json()
List all customers request example
{
"meta": {
"status": 0
},
"data": [{
"id": "45ba38a4-f8e9-11e4-a322-1697f925ec7b",
"contact": {
"name": "Jamal Tunis",
"phone": "+15552581001"
},
"address": {
"name": "Tunis Logistics",
"addressLine1": "2100 Flagstaff Street",
"addressLine2": "",
"city": "Cambridge",
"state": "MA",
"zipcode": "02142",
"country": "USA"
}
},
{
"id": "45ba38a4-f8e9-11e4-a322-1697f925ec7b",
"contact": {
"name": "Benjamin Sisko",
"phone": "+15552581001"
},
"address": {
"name": "DS9 Station",
"addressLine1": "162 Brookline St.",
"addressLine2": "",
"city": "Cambridge",
"state": "MA",
"zipcode": "02139",
"country": "USA"
}
}
]
}
List all customers that are currently in the system, optionally filtering by name, email, and/or phone.
GET https://api.wisesys.info/customers{?page}{?limit}{?extent}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| extent | string | Optional; name of field which shows its detail |
| page | int | Optional; defaults to 0; the pagination offset to return |
| limit | int | Optional; default to 10; the pagination limit of each page |
| name | string | Optional; filters results by exact matches on the name field |
| string | Optional; filters results by exact matches on the email field | |
| phone | string | Optional; filters results by exact matches on the phone field |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | List of Contact | List of available contacts in the Wise Systems platform |
Create or Update Customer Profile
PUT /customer HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def addCustomer(self, data):
r = requests.put(self.API_URL+"customer", json=data, headers=self.JSON_HEADER)
if r.status_code is not 200:
print r.status_code, r.reason
return r.json()
def updateCustomer(self, cust_id, data):
r = requests.patch(self.API_URL + "customer/" + cust_id, json=data, headers=self.JSON_HEADER)
if r.status_code is not 200:
print r.status_code, r.reason
return r.json()
Request body JSON example for associating a new address with the contact
{
"name": "Voyager Inc.",
"contact": {
"name": "Jamal Tunis",
"phone": "+15552581001"
},
"address": {
"name": "Voyager Inc.",
"addressLine1": "2100 Flagstaff Street",
"addressLine2": "",
"city": "Cambridge",
"state": "MA",
"zipcode": "02142",
"country": "USA"
}
}
Request body JSON example for associating an existing address with a contact
{
"name": "Voyager Inc.",
"contact": {
"name": "Jamal Tunis",
"phone": "+15552581001"
},
"address": "45ba38a4-f8e9-11e4-a322-1697f925ec7b"
}
Response body JSON example for both requests: existing address and new address
{
"data": {
"id": "45ba38a4-f8e9-11e4-a322-1697f925ec7b"
}
}
Create a new customer profile in the system or update an existing one. The system will return a success message and make the profile available for association with tasks.
The lookup is made via the euid or, if not provided, the address property. If a complete address record is sent, the address lookup rules apply (see the Create Address section).
PUT https://api.wisesys.info/customer
REQUEST BODY (New Address)
| Parameter | Type | Description |
|---|---|---|
| name | String | Customer's name |
| contact | Contact | Customer's contact information |
| address | Address | Customer's address |
REQUEST BODY (Existing Address)
| Parameter | Type | Description |
|---|---|---|
| name | String | Customer's name |
| contact | Contact | Contact info of the customer |
| address | UUID | Unique address Id to be used to associate address with Contact. |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| data | Id | Return unique customer id |
Get Customer Profile
GET /customer/71740132-2503-1114-2912-169749251273 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def getCustomer(self, cust_id):
r = requests.get(self.API_URL + "customer/" + cust_id, headers=self.JSON_HEADER)
if r.status_code != 200:
print(r.status_code, r.reason)
return r.json()
Get Customer Profile response body
{
"meta": {
"status": 0
},
"data": {
"id": "45ba38a4-f8e9-11e4-a322-1697f925ec7b",
"contact": {
"name": "Kathryn Janeway",
"phone": "+15552581001"
},
"address": {
"name": "Voyager Inc.",
"addressLine1": "99 Allston Street",
"addressLine2": "",
"city": "Cambridge",
"state": "MA",
"zipcode": "02139",
"country": "USA"
},
"euid": "10913",
"routeEuid": "21318",
"deliveryServiceTime": "PT45M",
"deliveryHours": [
[{
"start": "10:00",
"end": "17:00"
}]
],
"pickupServiceTime": "PT15M",
"pickupHours": [
[{
"start": "11:00",
"end": "18:00"
}],
[{
"start": "11:00",
"end": "18:00"
}]
]
}
}
Get a customer profile by id. Returns the customer details.
GET https://api.wisesys.info/customer/{id}{?extent}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; unique customer Id |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | IdObject | Return unique customer Id |
Update Customer Profile
PATCH /customer/71740132-2503-1114-2912-169749251273 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
Update Customer Profile response body
{
"name": "Voyager Inc.",
"contact": {
"name": "Jamal Tunis",
"phone": "+15552581001"
},
"deliveryServiceTime": "PT15M",
"routeEuid": "AA12"
}
Update customer profile information. You can provide any subset of properties.
PATCH https://api.wisesys.info/customer/{id}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; unique Customer Id |
REQUEST BODY
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| data | Customer | Return unique customer Id |
Delete Customer
DELETE /customer/70133308-1502-1114-1942-169719253272 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def delete_customer(self, cust_id):
r = requests.delete(self.API_URL + "customer/" + cust_id, headers=self.JSON_HEADER)
if r.status_code is not 200:
print(r.status_code, r.reason)
return r.json()
Delete customer response example
{
"meta": {
"status": 0,
"message": "The resource was removed successfully"
},
"data": {
"id": "703b710-3a1f-11e6-83d8-d7774a6e3894"
}
}
Delete a customer record.
DELETE https://api.wisesys.info/customer/{id}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; unique Customer Id |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | IdObject | Return unique Customer Id |
Notes
Get note
GET /note/70133308-1502-1114-1942-169719253272 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def getNote(self, note_id):
r = requests.get(self.API_URL + "note/" + note_id, headers=self.JSON_HEADER)
if r.status_code != 200:
self.notify("Failed to obtain Note by id: "+r.text)
print(r.status_code, r.reason)
return r.json()
Get Note response body
{
"text": "some text1",
"driver": "f98fe4af-4e4a-480c-bbf7-d266c88e5fa5",
"scope": "parking",
"customer": "70a3c908-f502-11e4-b9b2-1697f925ec7b",
"createdAt": "2015-07-28T02:43:22.738Z"
}
Get a note by id (returns the note details).
GET https://api.wisesys.info/note/{id}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; unique Note Id |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| text | String | Note text |
| driver | UUID | Unique driver Id that is associated with the note |
| scope | String | Type of note |
| customer | UUID | Unique customer Id that is associated with the note |
| createdAt | DateTime | The date and time when the note was created |
Update note
PUT /note/70133308-1502-1114-1942-169719253272 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def updateNote(self, note_id):
r = requests.put(self.API_URL + "note/" + note_id, headers=self.JSON_HEADER)
if r.status_code is not 200:
print(r.status_code, r.reason)
return r.json()
Update note request example
>
{
"text": "Some informative text",
"scope": "parking"
}
Update note response example
{
"meta": {
"status": 0,
"message": "The resource was updated successfully"
},
"data": {
"id": "703b710-3a1f-11e6-83d8-d7774a6e3894"
}
}
Update an existing note.
PUT https://api.wisesys.info/note/{id}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; unique Note Id |
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| text | String | Note text |
| scope | String | Type of note |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | IdObject | Return unique Note Id |
Delete Note
DELETE /note/70133308-1502-1114-1942-169719253272 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def deleteNote(self, note_id):
r = requests.delete(self.API_URL + "note/" + note_id, headers=self.JSON_HEADER)
if r.status_code is not 200:
print(r.status_code, r.reason)
return r.json()
Delete note response example
{
"meta": {
"status": 0,
"message": "The resource was removed successfully"
},
"data": {
"id": "703b710-3a1f-11e6-83d8-d7774a6e3894"
}
}
Delete a note.
DELETE https://api.wisesys.info/note/{id}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; unique Note Id |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | IdObject | Return unique Note Id |
Get Customer's Notes
GET /note/70133308-1502-1114-1942-169719253272 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def getCustomerNotes(self, customer_id):
r = requests.get(self.API_URL+"customer/" + customer_id + "/notes", headers=self.JSON_HEADER)
if r.status_code != 200:
self.notify("Failed to obtain Customer Note: "+r.text)
print(r.status_code, r.reason)
return r.json()
Get Customer response example
[
{
"text": "some text1",
"driver": "f98fe4af-4e4a-480c-bbf7-d266c88e5fa5",
"scope": "parking",
"customer": "70a3c908-f502-11e4-b9b2-1697f925ec7b",
"createdAt": "2015-07-28T02:43:22.738Z"
},
{
"text": "some text2",
"driver": "f98fe4af-4e4a-480c-bbf7-d266c88e5fa5",
"scope": "access",
"customer": "70a3c908-f502-11e4-b9b2-1697f925ec7b",
"createdAt": "2015-07-27T03:41:28.452Z"
}
]
Retrieve all notes pertaining to a customer.
GET https://api.wisesys.info/customer/{id}/notes
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; unique customer Id |
RETURN VALUES
List of NoteObject
Add Note
POST /note/70133308-1502-1114-1942-169719253272 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def addCustomerNotes(self, customer_id, data):
r = requests.post(self.API_URL+"customer/" + customer_id + "/notes", json=data,
headers=self.JSON_HEADER)
if r.status_code != 200:
self.notify("Failed to add customer Note: "+r.text)
print(r.status_code, r.reason)
return r.json()
Add Note request example
{
"text": "some text",
"scope": "parking",
"customer": "70a3c908-f502-11e4-b9b2-1697f925ec7b"
}
Add a new note for a customer.
POST https://api.wisesys.info/customer/{id}/notes
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; unique Customer Id |
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| text | String | Note text |
| scope | UUID | Type of note |
| customer | UUID | Unique Customer Id that is associated with the note |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| text | String | Note text |
| driver | String | Unique Driver Id that is associated with the note |
| scope | UUID | Type of note |
| customer | UUID | Unique Customer Id that is associated with the note |
| createdAt | DateTime | The date and time when the note was created |
Collect on Delivery (COD)
Collect on Delivery (COD) is a feature that we provide to support payments at the time of pickup or delivery. The drivers get the payment information from the Driver mobile app.
Invoice details (including amount due) are represented as pickupInvoices or deliveryInvoices within a task's props. These invoices can be linked to one or more inventory items.
When an assignments is created from a task with pickup/delivery invoices, the invoice information will be available in assignment props as invoices. For each assignment with invoices, the driver can submit multiple codPayments. The assignment cannot be completed (and the associated inventory items will not be delivered) if a cod payment is not submitted for the assignment.
Get Cod Payments for a given assignment
GET /assignment/977ea200-8562-4350-ad97-9105c014089a/cod-payments HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
Get Cod Payments response example
{
"meta": {},
"data": [
{
"id": "56e69593-3466-4ca9-8951-24663eb92152",
"client_id": "5c087850-2a99-11e5-9189-eb07c479dfd5",
"assignment_id": "977ea200-8562-4350-ad97-9105c014089a",
"payment_type": "Cash",
"amount_collected": 250,
"check_number": null,
"reference_number": null,
"other_payment_method": null,
"currency": "USD",
"reason": null
},
{
"id": "bb514de5-e1e2-42a5-8f23-d02241c8e986",
"assignment_id": "977ea200-8562-4350-ad97-9105c014089a",
"payment_type": "Check",
"amount_collected": 150,
"check_number": "300001",
"reference_number": "reference",
"client_id": "5c087850-2a99-11e5-9189-eb07c479dfd5",
"currency": "USD",
"other_payment_method": null,
"reason": null
}
]
}
Create Cod Payments for a given assignment
POST /assignment/977ea200-8562-4350-ad97-9105c014089a/cod-payments HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
Body to create Cod Payments
{
"codPayments": [
{
"paymentType": "Cash",
"amountCollected": 250,
"groupNumber": 1,
"invoices": [
{
"invoiceNumber": "DLV001",
"amountDue": 25
},
{
"invoiceNumber": "DLV002",
"amountDue": 50
}
]
},
{
"paymentType": "Check",
"checkNumber": "300001",
"referenceNumber": "reference",
"amountCollected": 150
}
]
}
Sample response
{
"meta": {},
"data": {
"success": [
{
"id": "56e69593-3466-4ca9-8951-24663eb92152",
"assignment_id": "977ea200-8562-4350-ad97-9105c014089a",
"payment_type": "Cash",
"amount_collected": 250,
"client_id": "5c087850-2a99-11e5-9189-eb07c479dfd5",
"currency": "USD",
"check_number": null,
"reference_number": null,
"other_payment_method": null,
"reason": null
},
{
"id": "bb514de5-e1e2-42a5-8f23-d02241c8e986",
"assignment_id": "977ea200-8562-4350-ad97-9105c014089a",
"payment_type": "Check",
"amount_collected": 150,
"check_number": "300001",
"reference_number": "reference",
"client_id": "5c087850-2a99-11e5-9189-eb07c479dfd5",
"currency": "USD",
"other_payment_method": null,
"reason": null
}
],
"fail": []
}
}
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| codPayments | List of CodPayment Objects | Required; List of COD payments |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Object | Response meta data |
| data.success | List of Success Objects | List of successfully processed payments |
| data.fail | List | List of failed payments |
Success Object:
| Parameter | Type | Description |
|---|---|---|
| id | String | ID of the payment |
| currency | String | Currency of the payment |
| invoices | null | Placeholder for invoices (null in this response) |
| assignment_id | String | ID of the assignment |
| payment_type | String | Type of payment |
| group_number | int | Group number |
| amount_collected | int | Amount collected |
| check_number | String | Check number |
| reference_number | String | Reference number |
| client_id | String | ID of the client |
| other_payment_method | String | Other payment method |
| reason | String | Reason |
Note: The response may contain multiple success objects if multiple payments were successfully processed.
Create or replace Cod Payments for a given assignment
To replace an existing payment with new information, the cod-payment id must be provided as part of the request.
PUT /assignment/d2a9cee4-6cfd-4912-acb1-77c6c4f1f326/cod-payments HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
Body to create or replace Cod Payments
{
"codPayments": [
{
"id": "56e69593-3466-4ca9-8951-24663eb92152",
"paymentType": "Cash",
"amountCollected": 250,
"groupNumber": 1,
"invoices": [
{
"invoiceNumber": "DLV001",
"amountDue": 25
},
{
"invoiceNumber": "DLV002",
"amountDue": 50
}
]
},
{
"paymentType": "Certified Check",
"checkNumber": "400002",
"referenceNumber": "reference",
"amountCollected": 100,
"groupNumber": 1,
"invoices": [
{
"invoiceNumber": "DLV001",
"amountDue": 25
},
{
"invoiceNumber": "DLV002",
"amountDue": 50
}
]
}
]
}
Sample response
{
"meta": {},
"data": {
"success": [
{
"id": "56e69593-3466-4ca9-8951-24663eb92152",
"assignment_id": "977ea200-8562-4350-ad97-9105c014089a",
"payment_type": "Cash",
"amount_collected": 250,
"client_id": "5c087850-2a99-11e5-9189-eb07c479dfd5",
"currency": "USD",
"check_number": null,
"reference_number": null,
"other_payment_method": null,
"reason": null
}
{
"id": "54fab720-1115-4d16-8e98-b76ad9a2f7ef",
"assignment_id": "977ea200-8562-4350-ad97-9105c014089a",
"payment_type": "Certified_Check",
"amount_collected": 100,
"check_number": "400002",
"reference_number": "reference",
"client_id": "5c087850-2a99-11e5-9189-eb07c479dfd5",
"currency": "USD",
"other_payment_method": null,
"reason": null
}
],
"fail": []
}
}
Delete Cod Payments for a given assignment
A delete request without a request body will delete all the cod-payments for the assignment. Including a body with an array of cod-payment ids will only delete the cod payments with the specified ids.
DELETE /assignment/d2a9cee4-6cfd-4912-acb1-77c6c4f1f326/cod-payments HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
Body to delete Cod Payments
{
"ids": [
"54fab720-1115-4d16-8e98-b76ad9a2f7ef",
"56e69593-3466-4ca9-8951-24663eb92152",
"bb514de5-e1e2-42a5-8f23-d02241c8e986"
]
}
Sample response
{
"meta": {},
"data": "Successfully deleted 3 CodPayment(s) for assignment d2a9cee4-6cfd-4912-acb1-77c6c4f1f326"
}
Schedules (deprecated)
Warning: This endpoint is deprecated and should not be used. The information below is still present for historical reasons and will soon be removed. To retrieve planned route data from Wise Systems, see the Download Order Integration File section.
Schedules (or Plans) represent a snapshot of all the routes that have been planned for a fleet of drivers for a given day. A route is a grouping of tasks. Routes can be assigned to a driver. Routes can be planned via our Route Planner or they can be pre-specified by a client in which case Wise Systems will optimize respecting the routes (task groupings) specified.
List all schedules
GET /schedules HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
List Schedule response example
{
"meta": {},
"data": [{
"solutionName": "Scheduler",
"routes": [{
"driverId": "97d14830-1b32-11e8-ad8c-371183e4b63f",
"route": "fdb8a905-d34e-4769-8916-987e73dddeb3",
"routeInfo": {
"totalWaitingTime": 4640,
"numberOfUnassignedTasks": 0,
"totalDelay": 0,
"totalServiceTime": 7918,
"numberOfOpenRoutes": 1,
"totalTravelTime": 3338,
"totalMeters": 20375,
"numberOfViolatedHardTW": 0,
"numberOfExtraNeededVehicles": 0,
"numberOfViolatedTW": 0,
"timeOnRoad": 15896,
"numberOfTasks": 4
},
"schedule": [{
"task": "depot1",
"pickupTime": 1519641726,
"deliveryTime": 1519641726
},
{
"departureTime": 1519656864000,
"task": "a95a9200-1b32-11e8-ad8c-371183e4b63f",
"deliveryTime": 1519653861,
"violatedTW": false,
"delay": 0,
"waitingTime": 0,
"delayFlag": 0,
"pickupTime": 1519683228
},
{
"task": "depot2",
"pickupTime": 1519657622,
"deliveryTime": 1519657622
}
]
},
{
"driverId": "98844480-1b32-11e8-ad8c-371183e4b63f",
"route": "26019d09-8df5-44d3-b569-f839fd2ab7d1",
"routeInfo": {
"totalWaitingTime": 4855,
"numberOfUnassignedTasks": 0,
"totalDelay": 0,
"totalServiceTime": 20174,
"numberOfOpenRoutes": 1,
"totalTravelTime": 4162,
"totalMeters": 18483,
"numberOfViolatedHardTW": 0,
"numberOfExtraNeededVehicles": 0,
"numberOfViolatedTW": 0,
"timeOnRoad": 29191,
"numberOfTasks": 11
},
"schedule": [{
"task": "depot1",
"pickupTime": 1519642250,
"deliveryTime": 1519642250
},
{
"departureTime": 1519643912000,
"task": "a8847d50-1b32-11e8-ad8c-371183e4b63f",
"deliveryTime": 1519642800,
"violatedTW": false,
"delay": 0,
"waitingTime": 21050,
"delayFlag": -1,
"pickupTime": 1519683228
},
{
"departureTime": 1519651419000,
"task": "a932beb0-1b32-11e8-ad8c-371183e4b63f",
"deliveryTime": 1519650000,
"violatedTW": false,
"delay": 0,
"waitingTime": 4855,
"delayFlag": -1,
"pickupTime": 1519683228
},
{
"task": "depot2",
"pickupTime": 1519671441,
"deliveryTime": 1519671441
}
]
}
],
"solutionInfo": {
"totalWaitingTime": 11052,
"numberOfUnassignedTasks": 0,
"eta_type": "Google",
"totalDelay": 0,
"totalServiceTime": 46748,
"numberOfOpenRoutes": 3,
"totalTravelTime": 16988,
"totalMeters": 174701,
"numberOfViolatedHardTW": 0,
"numberOfExtraNeededVehicles": 0,
"numberOfViolatedTW": 0,
"timeOnRoad": 74788,
"numberOfTasks": 25
}
}]
}
Retrieve all schedules in the Wise Systems platform
GET https://api.wisesys.info/schedules{?date}{?type}{?subType}{?active}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| date | String | Required; date of the route logs formated as "YYYY-MM-DD"; example: "2019-07-04" |
| type | String | Optional; type of route logs; example: type=Driver |
| subType | String | Optional; SubType of route logs; example: sub_type==AssignmentComplete |
| page | int | Optional; defaults to 0; the pagination offset to return |
| limit | int | Optional; default to 10; the pagination limit of each page |
Retrieve Planned Tasks
GET /schedule/71740331-3503-1134-1922-169719251371 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def get_route_plan(self, schedulerTaskId, routeDate = None):
"""
:param schedulerTaskId: ID returned by scheduleTasks
:param routeDate: the date to search for, optional
:return: status of that Route Planner run and the route plan if ready
"""
query = "schedule/" + schedulerTaskId
data = {}
if (routeDate):
data["date"] = routeDate
r = requests.get(self.API_URL+query, headers=self.JSON_HEADER, json=data)
if r.status_code != 200:
print(r.status_code, r.reason)
return r.json()
Planned tasks response example
{
"meta": {},
"data": [{
"driver": "2cafc9a0-3ca0-11e5-a4e2-5598a5c5072a",
"schedule": [{
"task": "34016a10-3ca0-11e5-a4e2-5598a5c5072a",
"pickupTime": "2015-06-29T16:30:00.000Z",
"deliveryTime": "2015-07-14T15:23:20.000Z"
}]
},
{
"driver": "26b777a0-3ca0-11e5-a4e2-5598a5c5072a",
"schedule": [{
"task": "34053aa0-3ca0-11e5-a4e2-5598a5c5072a",
"pickupTime": "2015-06-29T16:30:00.000Z",
"deliveryTime": "2015-07-14T15:23:20.000Z"
}]
}
]
}
Utilize this endpoint to retrieve the results of the Route Planner called from the Schedule Tasks endpoint. Wise Systems recommends periodically calling this endpoint until the routes are available.
GET https://api.wisesys.info/schedule/{id}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| Id | UUID | Job Id returned by schedule Task API |
| routeDate | Date | Optional; schedule Tasks date; the date is formated as "YYYY-MM-DD"; example: "2019-07-04" |
RETRIEVE SCHEDULE RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | List of ScheduleTaskObject | Ordered list of drivers and their planned tasks |
Move route to another client
- A single route from can be moved to another driver in a different client.
- All request entites can belong to the same client.
- The route will be assigned to the target driver.
- If the target driver had an existing route then that route is assinged to a new dummy driver.
- Route can either be (1) a route with a driver or (2) a route without a driver.
- Routes without drivers have
driverIds that start withdummy. - Source client id is required if the route.
- Routes without drivers have
- The target driver can either be (3) assigned to an existing route or (4) be unassinged.
- All target drivers must refer to a valid instance of a driver.
- Routes cannot me moved to dummy drivers.
POST /schedule/evaluate HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
"""// Move route to another client"""
def multi_client_move_route(self, source_driver_id, target_driver_id, source_client_id, route_date, source_client_id=None):
body = {
"driverId1": source_driver_id,
"driverId2": target_driver_id
"routeDate": route_date
}
if source_client_id:
body["driverId1ClientId"] = source_client_id
r = requests.patch(self.API_URL + "schedules/evaluate?action=move_route", json=body, headers=self.JSON_HEADER)
if r.status_code is not 200:
print(r.status_code, r.reason)
return r.json()
Move task to another client response example
{
"data": {
"schedulerTaskIds": [
{
"clientId": "ed0705b1-3fe8-4a2a-b3ff-47b707ea0fad",
"schedulerTaskId": "dc2125be-9105-4427-b879-02ffb5e7bd42"
},
{
"clientId": "5c087850-2a99-11e5-9189-eb07c479dfd5",
"schedulerTaskId": "2d9812bb-b7d1-455c-b637-1fe7f8855d75"
}
],
"taskIds": [
"6587be42-9135-46ff-abd3-e225f5090c8c",
"78c617c4-c898-4cb2-a136-a512f93d4ad9"
]
},
"meta": {}
}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| action | string | Required; Must be move_route |
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| driverId1 | UUID | Required; Source driver |
| driverId2 | UUID | Required; Target driver |
| routeDate | String | Required; |
| driverId1Client | String | Optional; Required when driverId1 is a dummy driver id |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data.schedulerTaskIds | List of SchedulerTaskId Object | One for each client involved in the request |
| data.taskIds | List of UUIDs | Newly created task ids |
SchedulerTaskId Object
| Parameter | Type | Description |
|---|---|---|
| clientId | UUID | |
| schedulerTaskId | UUID |
Add a driver break to a planned route
Insert a driver break after a specified stop into an existing route in Route Planner.
POST https://api.wisesys.info/schedules/evaluate?action=add_break
POST /schedule/evaluate?action=add_break HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
"""// Add driver break"""
def add_break(self, date, routePlanType, routeId, stopId, durationSeconds):
body = {
"date": date,
"type": routePlanType,
"routeId": routeId,
"stopIdBeforeBreak": stopId,
"durationSeconds": durationSeconds
}
r = requests.post(self.API_URL + "schedules/evaluate?action=add_break", json=body, headers=self.JSON_HEADER)
if r.status_code is not 200:
print(r.status_code, r.reason)
return r.json()
Request body JSON example
{
"date": "2023-03-28",
"type": "Scheduler",
"routeId": "3124f8be-85dd-4cf2-b583-0e914804dbb8",
"stopIdBeforeBreak": "e494f5ff-be22-4fc1-be9b-c7893efcbccc",
"durationSeconds": 300,
}
Response body JSON example
{
"meta": {},
"data": {
"routeId": "23477423-874c-463d-b1fa-9ca106e20ffe",
"schedulerTaskId": "12118c8a-6d49-4da6-ad67-fd744bbee26d"
}
}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| action | string | Required; Must be add_break |
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| date | String | Required; Date of the route formatted as "YYYY-MM-DD"; example: "2019-07-04" |
| type | String | Required; Type of route plan ("Scheduler") |
| routeId | UUID | Required; Unique route Id; example: "3124f8be-85dd-4cf2-b583-0e914804dbb8" |
| stopIdBeforeBreak | UUID | Required; Unique stop Id where the break will be inserted after; example: "e494f5ff-be22-4fc1-be9b-c7893efcbccc" |
| durationSeconds | int | Required; Duration of the new break to be inserted in seconds; example: 300 |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data.routeId | UUID | Unique id of route involved in the request |
| data.schedulerTaskId | UUID | Unique scheduler task id |
Delete a driver break from a planned route
Delete an existing driver break in a route in Route Planner.
POST https://api.wisesys.info/schedules/evaluate?action=delete_break
POST /schedule/evaluate?action=delete_break HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
"""// Delete driver break"""
def delete_break(self, date, routePlanType, routeId, breakRuleId):
body = {
"date": date,
"type": routePlanType,
"routeId": routeId,
"breakRuleId": breakRuleId
}
r = requests.post(self.API_URL + "schedules/evaluate?action=delete_break", json=body, headers=self.JSON_HEADER)
if r.status_code is not 200:
print(r.status_code, r.reason)
return r.json()
Request body JSON example
{
"date": "2023-03-28",
"type": "Scheduler",
"routeId": "3124f8be-85dd-4cf2-b583-0e914804dbb8",
"breakRuleId": "afb94284-3a23-4a12-a909-b67807545695",
}
Response body JSON example
{
"meta": {},
"data": {
"routeId": "23477423-874c-463d-b1fa-9ca106e20ffe",
"schedulerTaskId": "12118c8a-6d49-4da6-ad67-fd744bbee26d"
}
}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| action | string | Required; Must be delete_break |
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| date | String | Required; Date of the route formatted as "YYYY-MM-DD"; example: "2019-07-04" |
| type | String | Required; Type of route plan ("Scheduler") |
| routeId | UUID | Required; Unique route Id; example: "3124f8be-85dd-4cf2-b583-0e914804dbb8" |
| breakRuleId | UUID | Required; Unique id of break rule associated with the break to be removed; example: "afb94284-3a23-4a12-a909-b67807545695" |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data.routeId | UUID | Unique id of route involved in the request |
| data.schedulerTaskId | UUID | Unique scheduler task id |
Edit a driver break in a planned route
Edit an existing Driver Break in a route in Route Planner. There are 2 possible edit actions: resequencing and editing the duration of a break. Depending on the request body, one or both edits can be applied in a single request.
POST https://api.wisesys.info/schedules/evaluate?action=edit_break
POST /schedule/evaluate?action=edit_break HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
"""// Edit driver break"""
def edit_break(self, date, routePlanType, routeId, breakRuleId, stopIdBeforeBreak, durationSeconds):
body = {
"date": date,
"type": routePlanType,
"routeId": routeId,
"breakRuleId": breakRuleId
}
if stopIdBeforeBreak:
body["stopIdBeforeBreak"] = stopIdBeforeBreak
if durationSeconds:
body["durationSeconds"] = durationSeconds
r = requests.post(self.API_URL + "schedules/evaluate?action=edit_break", json=body, headers=self.JSON_HEADER)
if r.status_code is not 200:
print(r.status_code, r.reason)
return r.json()
Request body for resequence JSON example
{
"date": "2023-03-28",
"type": "Scheduler",
"routeId": "3124f8be-85dd-4cf2-b583-0e914804dbb8",
"breakRuleId": "afb94284-3a23-4a12-a909-b67807545695",
"stopIdBeforeBreak": "e494f5ff-be22-4fc1-be9b-c7893efcbccc"
}
Request body for editing break duration JSON example
{
"date": "2023-03-28",
"type": "Scheduler",
"routeId": "3124f8be-85dd-4cf2-b583-0e914804dbb8",
"breakRuleId": "afb94284-3a23-4a12-a909-b67807545695",
"durationSeconds": 300,
}
Response body JSON example
{
"meta": {},
"data": {
"routeId": "23477423-874c-463d-b1fa-9ca106e20ffe",
"schedulerTaskId": "12118c8a-6d49-4da6-ad67-fd744bbee26d"
}
}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| action | string | Required; Must be delete_break |
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| date | String | Required; Date of the route formatted as "YYYY-MM-DD"; example: "2019-07-04" |
| type | String | Required; Type of route plan ("Scheduler") |
| routeId | UUID | Required; Unique route Id; example: "3124f8be-85dd-4cf2-b583-0e914804dbb8" |
| breakRuleId | UUID | Required; Unique id of break rule associated with the break to be removed; example: "afb94284-3a23-4a12-a909-b67807545695" |
| stopIdBeforeBreak | UUID | Optional; Unique stop Id where the current break will be inserted after; example: "e494f5ff-be22-4fc1-be9b-c7893efcbccc" |
| durationSeconds | int | Optional; New duration of the break in seconds; example: 300 |
Note: Must provide either durationSeconds(to edit duration) or stopIdBeforeBreak(to resequence).
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data.routeId | UUID | Unique id of route involved in the request |
| data.schedulerTaskId | UUID | Unique scheduler task id |
Routeplans (deprecated)
Warning: This endpoint is deprecated and should not be used. The information below is still present for historical reasons and will soon be removed. To retrieve planned route data from Wise Systems, see the Download Order Integration File section.
Routeplans are created after a successful Route Planner run. They contain high level summary data, as well as the routes for the fleet of drivers.
The default behavior of this endpoint is to return data for all clients the requester has access to. If the requester is not an admin, but rather a driver, the routes information is limited to that driver.
List Routeplans
Get a list of Routeplans. If no results found, an empty array is returned.
GET /routeplans HTTP/1.1
Accept: application/json
Authorization: Bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def get_routeplans(self, limit=100, page=0, client_ids, start_from, active, include):
r = requests.get(self.API_URL + "routeplans?page=" + page + "&limit=" + limit + "&client_ids=" + client_ids + "&start_from=" + start_from + "&active=" + active + "&include=" + include, headers=self.JSON_HEADER)
if r.status_code != 200:
print r.status_code, r.reason
return r.status_code, r.json()
List Routeplans response example
{
"meta":{
"page":0,
"limit":10,
"startAt":0,
"sortdir":"ASC"
},
"data":[
{
"id":"206e5c14-fa8d-4a72-8e78-0e2136381879",
"route_date":"2020-12-18",
"client_id":"aa67d443-91bf-4f5c-a1af-c91c3c9eebed",
"type":"Scheduler",
"sub_type":"SequentialInsertion",
"eta_type":"Google",
"total_travel_time":25871,
"total_waiting_time":0,
"number_of_tasks":1,
"number_of_extra_needed_vehicles":0,
"number_of_violated_hard_tw":0,
"total_delay":0,
"total_service_time":14474,
"total_meters":494984,
"number_of_open_routes":0,
"number_of_unassigned_tasks":0,
"time_on_road":40345,
"number_of_violated_tw":0,
"active":false,
"valid":false,
"stage":"Update",
"routes":[
{
"driverId":"c90ee9a2-1189-4d38-876e-0f979f8be9bb",
"routeInfo":{
"driverShiftCloseTimeViolation":22561,
"maxTaskViolation":2147483641,
"numberOfExtraNeededVehicles":0,
"numberOfOpenRoutes":0,
"numberOfTasks":1,
"numberOfUnassignedTasks":0,
"numberOfVehicleTypeViolation":0,
"numberOfViolatedHardTW":0,
"numberOfViolatedTW":0,
"routeDurationViolation":38260,
"sizeViolation":-235,
"timeOnRoad":12140,
"totalCapacity":{
"volume":435,
"weight":150
},
"totalDelay":0,
"totalMeters":123050,
"totalServiceTime":4997,
"totalTravelTime":7143,
"totalWaitingTime":0,
"weightViolation":19850
},
"routeInfoV2":{
"Note":"",
"numberOfDriverShiftCloseTimeViolation":0,
"numberOfExtraNeededVehicles":0,
"numberOfMaxTaskViolation":0,
"numberOfOpenRoutes":0,
"numberOfRouteDurationViolation":0,
"numberOfSizeViolation":1,
"numberOfTasks":1,
"numberOfUnassignedTasks":0,
"numberOfVehicleTypeViolation":0,
"numberOfViolatedHardTW":0,
"numberOfViolatedTW":0,
"numberOfWeightViolation":0,
"timeOnRoad":12140,
"totalCapacity":{
"volume":435,
"weight":150
},
"totalDelay":0,
"totalMeters":123050,
"totalServiceTime":4997,
"totalTravelTime":7143,
"totalWaitingTime":0
},
"routes":[
{
"routeId":"f5c06565-b993-4a86-a8a5-e275508ade2a",
"routeInfo":{
"driverShiftCloseTimeViolation":22561,
"maxTaskViolation":2147483641,
"numberOfExtraNeededVehicles":0,
"numberOfOpenRoutes":0,
"numberOfTasks":1,
"numberOfUnassignedTasks":0,
"numberOfVehicleTypeViolation":0,
"numberOfViolatedHardTW":0,
"numberOfViolatedTW":0,
"routeDurationViolation":38260,
"sizeViolation":-235,
"timeOnRoad":12140,
"totalCapacity":{
"volume":435,
"weight":150
},
"totalDelay":0,
"totalMeters":123050,
"totalServiceTime":4997,
"totalTravelTime":7143,
"totalWaitingTime":0,
"weightViolation":19850
},
"stops":[
{
"deliveryTime":1608304899000,
"departureTime":1608304899000,
"depotId":"07621a12-d318-4a14-a97e-909b36eb0258",
"id":"depot1",
"location":{
"lat":42.362153,
"lng":-71.08588
},
"pickupTime":1608304899000,
"stopType":"depot",
"task":"depot1"
},
{
"delay":0,
"delayFlag":-1,
"deliveryTime":1608308295000,
"departureTime":1608308295000,
"distanceFromPrevious":52660,
"distanceToNext":5751,
"id":"cf7254a4-746e-4206-b789-81170b8293cc",
"location":{
"lat":42.634223,
"lng":-71.355736
},
"pickupTime":1608307200000,
"startServiceTime":1608307200000,
"stopType":"pickup",
"task":"cf7254a4-746e-4206-b789-81170b8293cc",
"travelTimeFromPrevious":2301,
"travelTimeToNext":554,
"violatedTW":false,
"waitingTime":19299
},
{
"deliveryTime":1608317039000,
"departureTime":1608317039000,
"depotId":"07621a12-d318-4a14-a97e-909b36eb0258",
"id":"depot2",
"location":{
"lat":42.362153,
"lng":-71.08588
},
"pickupTime":1608317039000,
"stopType":"depot",
"task":"depot2"
}
]
}
],
"vehicleId":"16dfbe2e-cf35-442a-bce7-553dad1df6fe",
"vehicleProps":{
"type":"truck_sideload",
"volumeCapacity":200,
"weightCapacity":20000
}
}
],
"scheduler_id":"83fbfba4-7719-4c44-8921-7b0bf488d46d",
"created_at":"2020-12-17T19:44:58.682Z",
"updated_at":"2020-12-17T19:45:00.208Z"
}
]
}
HTTP Request
GET https://api.wisesys.info/routeplans{?querystringParameters}
Querystring Parameters
| Parameter | Type | Description |
|---|---|---|
| client_ids | String | (optional) UUIDS joined by commas. Specify which clients you want to pull data for, which you have access to. |
| start_from | Date | (optional) Date in yyyy-mm-dd format. Only pull records with a route_date greater than or equal to this value. |
| active | Boolean | (optional) Value must be true or false. |
| include | String | (optional) Column names joined by commas. Only the columns specified, in addition to some base columns, will be returned in the response payload. |
| page | Number | (optional) The pagination offset to return. Default: 0 |
| limit | Number | (optional) The number of results per page. Default: 10 |
Return Values
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | List of Routeplans | Array of Routeplan objects |
Get a Routeplan
Get a specific Routeplan by id. If no results found, an error is returned.
GET /routeplans/206e5c14-fa8d-4a72-8e78-0e2136381879 HTTP/1.1
Accept: application/json
Authorization: Bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def get_routeplan(self, idRoutePlan, limit=100, page=0, client_ids, start_from, active, include):
r = requests.get(self.API_URL + "routeplans/" + idRoutePlan + "?page=" + page + "&limit=" + limit + "&client_ids=" + client_ids + "&start_from=" + start_from + "&active=" + active + "&include=" + include,headers=self.JSON_HEADER)
if r.status_code != 200:
print r.status_code, r.reason
return r.status_code, r.json()
Get a Routeplan response example
{
"meta":{},
"data":{
"id":"206e5c14-fa8d-4a72-8e78-0e2136381879",
"route_date":"2020-12-18",
"client_id":"aa67d443-91bf-4f5c-a1af-c91c3c9eebed",
"type":"Scheduler",
"sub_type":"SequentialInsertion",
"eta_type":"Google",
"total_travel_time":25871,
"total_waiting_time":0,
"number_of_tasks":1,
"number_of_extra_needed_vehicles":0,
"number_of_violated_hard_tw":0,
"total_delay":0,
"total_service_time":14474,
"total_meters":494984,
"number_of_open_routes":0,
"number_of_unassigned_tasks":0,
"time_on_road":40345,
"number_of_violated_tw":0,
"active":false,
"valid":false,
"stage":"Update",
"routes":[
{
"driverId":"c90ee9a2-1189-4d38-876e-0f979f8be9bb",
"routeInfo":{
"driverShiftCloseTimeViolation":22561,
"maxTaskViolation":2147483641,
"numberOfExtraNeededVehicles":0,
"numberOfOpenRoutes":0,
"numberOfTasks":1,
"numberOfUnassignedTasks":0,
"numberOfVehicleTypeViolation":0,
"numberOfViolatedHardTW":0,
"numberOfViolatedTW":0,
"routeDurationViolation":38260,
"sizeViolation":-235,
"timeOnRoad":12140,
"totalCapacity":{
"volume":435,
"weight":150
},
"totalDelay":0,
"totalMeters":123050,
"totalServiceTime":4997,
"totalTravelTime":7143,
"totalWaitingTime":0,
"weightViolation":19850
},
"routeInfoV2":{
"Note":"",
"numberOfDriverShiftCloseTimeViolation":0,
"numberOfExtraNeededVehicles":0,
"numberOfMaxTaskViolation":0,
"numberOfOpenRoutes":0,
"numberOfRouteDurationViolation":0,
"numberOfSizeViolation":1,
"numberOfTasks":1,
"numberOfUnassignedTasks":0,
"numberOfVehicleTypeViolation":0,
"numberOfViolatedHardTW":0,
"numberOfViolatedTW":0,
"numberOfWeightViolation":0,
"timeOnRoad":12140,
"totalCapacity":{
"volume":435,
"weight":150
},
"totalDelay":0,
"totalMeters":123050,
"totalServiceTime":4997,
"totalTravelTime":7143,
"totalWaitingTime":0
},
"routes":[
{
"routeId":"f5c06565-b993-4a86-a8a5-e275508ade2a",
"routeInfo":{
"driverShiftCloseTimeViolation":22561,
"maxTaskViolation":2147483641,
"numberOfExtraNeededVehicles":0,
"numberOfOpenRoutes":0,
"numberOfTasks":1,
"numberOfUnassignedTasks":0,
"numberOfVehicleTypeViolation":0,
"numberOfViolatedHardTW":0,
"numberOfViolatedTW":0,
"routeDurationViolation":38260,
"sizeViolation":-235,
"timeOnRoad":12140,
"totalCapacity":{
"volume":435,
"weight":150
},
"totalDelay":0,
"totalMeters":123050,
"totalServiceTime":4997,
"totalTravelTime":7143,
"totalWaitingTime":0,
"weightViolation":19850
},
"stops":[
{
"deliveryTime":1608304899000,
"departureTime":1608304899000,
"depotId":"07621a12-d318-4a14-a97e-909b36eb0258",
"id":"depot1",
"location":{
"lat":42.362153,
"lng":-71.08588
},
"pickupTime":1608304899000,
"stopType":"depot",
"task":"depot1"
},
{
"delay":0,
"delayFlag":-1,
"deliveryTime":1608308295000,
"departureTime":1608308295000,
"distanceFromPrevious":52660,
"distanceToNext":5751,
"id":"cf7254a4-746e-4206-b789-81170b8293cc",
"location":{
"lat":42.634223,
"lng":-71.355736
},
"pickupTime":1608307200000,
"startServiceTime":1608307200000,
"stopType":"pickup",
"task":"cf7254a4-746e-4206-b789-81170b8293cc",
"travelTimeFromPrevious":2301,
"travelTimeToNext":554,
"violatedTW":false,
"waitingTime":19299
},
{
"deliveryTime":1608317039000,
"departureTime":1608317039000,
"depotId":"07621a12-d318-4a14-a97e-909b36eb0258",
"id":"depot2",
"location":{
"lat":42.362153,
"lng":-71.08588
},
"pickupTime":1608317039000,
"stopType":"depot",
"task":"depot2"
}
]
}
],
"vehicleId":"16dfbe2e-cf35-442a-bce7-553dad1df6fe",
"vehicleProps":{
"type":"truck_sideload",
"volumeCapacity":200,
"weightCapacity":20000
}
}
],
"scheduler_id":"83fbfba4-7719-4c44-8921-7b0bf488d46d",
"created_at":"2020-12-17T19:44:58.682Z",
"updated_at":"2020-12-17T19:45:00.208Z"
}
}
HTTP Request
GET https://api.wisesys.info/routeplans/{id}{?querystringParameters}
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Unique Routeplan id |
Querystring Parameters
| Parameter | Type | Description |
|---|---|---|
| client_ids | String | (optional) UUIDS joined by commas. Specify which clients you want to pull data for, which you have access to. |
| start_from | Date | (optional) Date in yyyy-mm-dd format. Only pull records with a route_date greater than or equal to this value. |
| active | Boolean | (optional) Value must be true or false. |
| include | String | (optional) Column names joined by commas. Only the columns specified, in addition to some base columns, will be returned in the response payload. |
Return Values
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | Routeplan | Routeplan |
Depots
Depots represent cargo distribution centers, dispatch centers, offices, or other central locations from which vehicles depart and arrive to. When a Client is created, it automatically gets a depot at its main location with an HQ property set to true. This will service all trips by default. Additional non-HQ depots may be created depending on the use case. Currently depots can be associated with one or more vehicles.
Register a Depot
POST /depot HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def add_depot(self, address_id):
r = requests.post(self.API_URL + "depot", json={"address": address_id},
headers=self.JSON_HEADER)
if r.status_code != 200:
print r.status_code, r.reason
return r.status_code, r.json()
Register request example
{
"address": "12651031-0000-4449-0000-000001111119"
}
Depots created this way may not have an HQ property set to true — a single HQ depot is created automatically during client onboarding. This method is idempotent.
HTTP REQUEST
POST https://api.wisesys.info/depot
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| address | UUID | Depot's address (e.g., "12651031-0000-4449-0000-000001111119") |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | IdObject | Return depot unique Id |
Get Specific a Depot
GET /depot/71740232-1503-1134-1932-169739253471 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
Get Depot response example
{
"meta": {},
"data": {
"id": "7a740f3c-f503-11e4-b9b2-1697f925ec7b",
"address": "7a740e4d-f503-11e4-b9b2-1697f925ec7b",
"hq": false
}
}
Retrieving depot info
HTTP REQUEST
GET https://api.wisesys.info/depot/{id}{?extent}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; unique Depot Id |
| extent | String | Optional; the extended (id to detail) fields in response; example: address |
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| address | UUID | Depot's address (e.g., "12651031-0000-4449-0000-000001111119") |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | DepotObject | Return depot object |
Update Depot
PATCH /depot/71740232-1503-1134-1932-169739253471 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def edit_depot(self, depot_id, update):
r = requests.patch(self.API_URL + "depot/" + depot_id, json=update,
headers=self.JSON_HEADER)
if r.status_code != 200:
print r.status_code, r.reason
return r.status_code, r.json()
Update depot request body JSON example
{
"address": "7a740e4d-f503-11e4-b9b2-1697f925ec7b"
}
Update depot response body JSON example
{
"meta": {},
"data": {
"id": "7a740f3c-f503-11e4-b9b2-1697f925ec7b"
}
}
Update the depot information. Only the address ID may be updated.
HTTP REQUEST
PATCH https://api.wisesys.info/depot/{id}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; unique depot Id |
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| address | UUID | Depot's address (e.g., "12651031-0000-4449-0000-000001111119") |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | IdObject | Return depot unique Id |
Remove Depot
DELETE /depot/71740232-1503-1134-1932-169739253471 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def delete_depot(self, depot_id):
r = requests.delete(self.API_URL + "depot/" + depot_id,
headers=self.JSON_HEADER)
if r.status_code != 200:
print r.status_code, r.reason
return r.status_code, r.json()
Remove depot response body JSON example
{
"meta": {},
"data": {
"id": "7a740f3c-f503-11e4-b9b2-1697f925ec7b"
}
}
Remove a non-HQ depot. HQ depots may not be removed. This method is idempotent.
HTTP REQUEST
DELETE https://api.wisesys.info/depot/{id}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; unique Depot Id |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | IdObject | Return depot unique Id |
List All Depots
GET /depots HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def get_depots(self, limit=100, page=0, extents=None):
url = self.__get_request_url("depots", limit, page, extents)
r = requests.get(url, headers=self.JSON_HEADER)
if r.status_code != 200:
print(r.status_code, r.reason)
return r.json()
Response body JSON example
{
"meta": {
"page": 1,
"limit": 2,
"total": 8
},
"data": [
{
"id": "7a740f3c-f503-11e4-b9b2-1697f925ec7b",
"address": "7a740e4d-f503-11e4-b9b2-1697f925ec7b",
"hq": true
},
{
"id": "7a740f4d-f503-11e4-b9b2-1697f925ec7b",
"address": "7a740b5a-f503-11e4-b9b2-1697f925ec7b",
"hq": false
}
]
}
HTTP REQUEST
GET https://api.wisesys.info/depots{?page}{?limit}{?extent}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| page | int | (optional) Default: 0; the pagination offset to return; example: 0 |
| limit | int | (optional) Default: 10; the pagination limit of each page; example: 8 |
| extent | String | Optional; the extended (id to detail) fields in response; example: vehicle |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | List of DepotObject | Return available Depots |
Admin
Upload a Route File
POST /admin?action=upload_schedule_file HTTP/1.1
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: multipart/form-data
def upload_file(self, filepath, data_type="schedule"):
"""
Upload a file with the given type of contents
:param filepath: absolute path to the file
:param data_type: type of file: "schedule" (tasks), "customer", "driver"
:return:
"""
extension = filepath.split(".")[-1]
if extension == "xlsx":
mime_type = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
elif extension == "xls":
mime_type = "application/vnd.ms-excel"
else:
mime_type = "text/csv"
files = {'file': (filepath, open(filepath, 'rb'), mime_type, {'Expires': '0'})}
url = "{}admin?action=upload_{}_file".format(self.API_URL, data_type)
# Use self.auth and not self.headers because self.headers deals with json and text
r = requests.post(url, files=files, headers=self.auth)
# TODO: Prashanth 03/07/2018
# The following check is not quite accurate; it tells whether the POST was successful and not tasks' creation
if r.status_code is not 200:
print r.status_code, r.reason
return r.json()
JSON request example
{
"file": <file data>
}
Upload a file containing driver routes with dates interpreted according to timezone.
HTTP REQUEST
POST https://api.wisesys.info/admin?action=upload_schedule_file{?timezone}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| timezone | String | Optional; defaults to 0; the pagination offset to return; example: 07:00 |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | Data | Returns requests status |
Download Order Integration File
POST /admin?action=export_order_integration_file HTTP/1.1
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: multipart/form-data
def download_order_integration_file(self, route_date=None):
"""
Downloads order integration file
:param route_date: The date for which the file is needed; if None, today's date in client timezone is used
:return: On success, (temporary) link to the file's location in S3.
"""
if not route_date:
client_timezone = self.getMe()["data"]["client"]["timezone"]
now_in_timezone = utils.now_in_tz(client_timezone)
route_date = utils.date_str_dateonly(now_in_timezone)
r = requests.post(
self.API_URL + "admin?action=export_order_integration_file",
json={"date": route_date},
headers=self.JSON_HEADER
)
response_json = r.json()
if r.status_code is 200 and response_json.get("data") and response_json.get("data").get("location"):
return response_json["data"]
else:
print r.status_code, r.reason
return r.status_code, response_json
{
"file": <file data>
}
Downloads order integration file param route_date: the date for which the file is needed; if None, today's date in client timezone is used.
Upload a file containing driver routes with dates interpreted according to timezone.
'This method is only allowed for users in the “administrator” role.'
HTTP REQUEST
POST https://api.wisesys.info/admin?action=export_order_integration_file{?timezone}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| timezone | String | Optional; defaults to 0; the pagination offset to return; example: 07:00 |
RETURN VALUES
On success, a temporary link to the file's location in S3 is returned.
Webhooks
Wise Systems' Webhooks API is a newly-released beta feature, and we'd love if you could send any feedback to support@wisesystems.com"
Webhooks provide a way for the Wise Systems Platform to notify clients when an event happens within the system by sending a notification message from the Wise Systems Platform to a unique URL. These events include Task creation, Task update (Tasks Overview), Assignment created (Assignments Overview), Schedule Created (Schedules Overview) among others.
Webhooks can be used to keep external systems in sync: when data is modified in the Wise Systems platform, your external system can be notified immediately and updated in real time. Some examples of use cases might be maintaining custom order status dashboards, real-time reports, warehouse management systems + vehicle-packing systems, and real-time recipient notifications tools.
Notification Object
Webhook notifications are sent in the following format:
{
"time": "2020-05-12T17:40:11.311Z",
"subscription_id": "83091c0a-811b-4637-a3a5-3df21b106141",
"secret_token": "UaXYlVevU8",
"event_type": "task.status.updated",
"data": {
...
}
}
The data object contains event specific payloads, listed below:
- Default single object event:
"data": {
"object": { Full Object }
Bulk object event:
json "data": { "objectIds": [Array of each new object id (String[]) ] }Scheduler event:
json "data": { "objectIds": [schedulerTaskId (String)] }
Retrieve Supported Events
Returns a list of all currently-supported events that trigger a notification message. Please utilize this endpoint for the latest up-to-date list of support events.
GET /webhooks/supportedevents HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def get_webhook_supportedevents(self):
r = requests.get(self.API_URL + "webhooks/supportedevents",
headers=self.JSON_HEADER)
r.raise_for_status()
return r.json()
Response body JSON example
{
"meta": {},
"data": [
"task.created",
"task.updated",
"task.deleted",
"task.dispatched",
"task.started",
"task.completed",
"task.cancelled",
"task.unassigned",
"task.route.updated",
"task.bulk.created",
"assignment.created",
"assignment.updated",
"assignment.deleted",
"assignment.started",
"assignment.completed",
"assignment.cancelled",
"schedule.created"
]
}
HTTP REQUEST
GET https://api.wisesys.info/webhooks/supportedevents
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | String[] | List containing all events whose occurrence triggers a notification message |
Add new Webhook Subscription
Create a new webhook for a given list of events. Every webhook subscription for the same client must have a unique URL. A plaintext secret will be generated at creation time and returned in the response. This secret can be used to verify that the webhook notifications are from Wise Systems.
POST /webhooks/ HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def add_webhook(self, data):
r = requests.post(self.API_URL + "webhooks/",
json=data, headers=self.JSON_HEADER)
r.raise_for_status()
return r.json()
Request JSON example
{
"url": "https://my-application-notifications-url.com",
"subscribed_events": ["task.created","scheduler.done"],
"description": "Sample webhook",
"enabled": true
}
Response body JSON example
{
"meta": {},
"data": {
"id": "41b7b7b3-a3d2-42db-b4e4-479367c31e09",
"url": "https://my-application-notifications-url.com",
"subscribed_events": [
"task.created",
"scheduler.done"
],
"description": "Sample webhook",
"enabled": true,
"client": "5c087850-2a99-11e5-9189-eb07c479dfd5",
"secret_token": "za4DEqDDuP"
}
}
HTTP REQUEST
POST https://api.wisesys.info/webhooks/
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| url | String | (Required) URL to which the notification message will be sent |
| subscribed_events | String[] | (Required) List of events whose occurrence will trigger a notification message |
| description | String | (Optional) Detail about the subscription |
| enabled | Boolean | (Required) Determines whether the subscription is active to receive messages or not |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | Webhook Subscription | Webhook object with generated secret |
Retrieve all Webhook Subscriptions
Returns a list of all webhook subscriptions
GET /webhooks/ HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def get_webhooks(self):
r = requests.get(self.API_URL + "webhooks/",
headers=self.JSON_HEADER)
r.raise_for_status()
return r.json()
Response body JSON example
{
"meta": {
"page": 0,
"limit": 10,
"startAt": 0,
"sortdir": "ASC"
},
"data": [
{
"id": "41b7b7b3-a3d2-42db-b4e4-479367c31e09",
"client": "5c087850-2a99-11e5-9189-eb07c479dfd5",
"url": "https://my-application-notifications-url.com",
"description": "Sample webhook",
"enabled": true,
"subscribed_events": [
"task.created",
"scheduler.done"
],
},
{
"id": "c465177a-4c63-413b-95dc-c6f5a058b41d",
"client": "5c087850-2a99-11e5-9189-eb07c479dfd5",
"url": "https://my-other-notifications-url.com",
"description": "Sample webhook 2",
"enabled": true,
"subscribed_events": [
"task.deleted",
"assignment.created"
],
}
]
}
HTTP REQUEST
GET https://api.wisesys.info/webhooks/
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | List of Webhook Subscription Objects | List of all available subscription objects |
Retrieve one Webhook
Returns a specific webhook subscription by its id.
GET /webhooks/28810350-f216-411e-b48e-7ef1f3360065 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def get_webhook(self, id):
r = requests.get(self.API_URL + "webhooks/" + id,
headers=self.JSON_HEADER)
r.raise_for_status()
return r.json()
Response body JSON example
{
"meta": {},
"data": {
"id": "28810350-f216-411e-b48e-7ef1f3360065",
"client": "0ec8b330-4ce4-11ea-957d-c9797b6a9c15",
"url": "https://my-other-notifications-url.com",
"description": "Sample webhook 2",
"enabled": true,
"subscribed_events": [
"task.deleted",
"assignment.created"
],
}
}
HTTP REQUEST
GET https://api.wisesys.info/webhooks/{id}
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | Webhook Subscription | Object containing subscription details |
Delete Webhook Subscription
Removes the subscription from the database by subscription id
DELETE webhooks/6a3f5780-33d8-495b-aa21-27b669d9c8da HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def delete_webhook(self, id):
r = requests.delete(self.API_URL + "webhooks/" + id,
headers=self.JSON_HEADER)
r.raise_for_status()
return r.json()
Response body JSON example
{
"meta": {},
"data": {
"id": "6a3f5780-33d8-495b-aa21-27b669d9c8da"
}
}
HTTP Request
DELETE https://api.wisesys.info/webhooks/{id}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Id of a subscription. |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | IdObject | return subscriptionId upon success |
Modify Webhook Subscription
Updates a subscription values. Supports editing the enabled, url, description, and subscribed_events fields, one by one, all at once or any combination in between. Returns an array containing the update count (always 1) and an array containing the modified webhook
PATCH webhooks/63b46402-ea88-493b-8441-75900b411742 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def update_webhook(self, id, data):
r = requests.patch(self.API_URL + "webhooks/" + id,
json=data, headers=self.JSON_HEADER)
r.raise_for_status()
return r.json()
Request JSON example
{
"subscribed_events": [
"schedule_created"
]
}
Response body JSON example
{
"meta": {},
"data": {
"id": "63b46402-ea88-493b-8441-75900b411742",
"client": "5c087850-2a99-11e5-9189-eb07c479dfd5",
"url": "https://webhook.site/bdb89edf-df10-4e5a-bc88-8d89a7ce40a4",
"description": "Sample webhook 2",
"enabled": true,
"subscribed_events": [
"schedule_created",
],
"created_at": "2020-08-05T15:58:07.594Z",
"updated_at": "2020-08-06T17:10:33.943Z"
}
}
HTTP Request
PATCH https://api.wisesys.info/webhooks/{id}
QUERYSTRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Id of a subscription |
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| description | String | (Optional) Brief webhook description |
| url | String | (Optional) Url where the message will be sent to |
| enabled | Boolean | (Optional) Validates whether the subscription is active or not |
| subscribed_events | String[] | (Optional) List of event that trigger message sending |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | List of Webhook Subscription Objects | Array containing the modified webhook subscription (It's always one subscription) |
Inventory Items
Inventory items are used to keep track of what is delivered or picked up for a given task.
Create an Inventory Item
Inventory items can be added both before and after dispatching a route. When creating an inventory item for a "two-part" task, the type set on the inventory item determines which assignment the item is assigned to ("pickup", or "delivery").
The following fields cannot be written to, since they are either automatically generated or assigned:
- id
- assignment_id
- created_at
The assignment_id is automatically assigned based on the task_id.
POST /inventoryitems HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def create_inventory_item(self, task_id, type, item_id, item_name, expected_quantity):
json = {"task_id": task_id, "type": type, "item_id": item_id, "item_name": item_name, "expected_quantity": expected_quantity}
r = requests.post(self.API_URL + "inventoryitems", json, headers=self.JSON_HEADER)
if r.status_code != 200:
print r.status_code, r.reason
return r.status_code, r.json()
Create Inventory Item sample payload
json { "task_id": "60a7a679-73d7-4054-9679-c61c384bf007", "invoice_id": "38e74bcb-45ea-410b-bf6d-e3c70d9199c0", "type": "delivery", "item_id": "abc123", "item_name": "apple", "expected_quantity": 20 }
HTTP Request
POST https://api.wisesys.info/inventoryitems
Request Body
| Parameter | Type | Description |
|---|---|---|
| task_id | UUID | Id of the task the inventory item will belong to |
| type | String | "delivery" or "pickup" |
| item_id | String | Arbitrary id pertinent to your system |
| item_name | String | Arbitrary name pertinent to your system |
| expected_quantity | Number | Positive number value with four decimal place precision. |
Return Values
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | InventoryItem | New inventory item |
List Inventory Items
Get a list of Inventory Items currently present in the system. If no results are found, an empty array is returned.
GET /inventoryitems HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def get_inventory_items(self, limit=100, page=0, task_id, assignment_id, driver_id):
r = requests.get(self.API_URL + "inventoryitems?page=" + page + "&limit=" + limit + "&task_id=" + task_id + "&assignment_id=" + assignment_id + "&driver_id=" + driver_id, headers=self.JSON_HEADER)
if r.status_code != 200:
print r.status_code, r.reason
return r.status_code, r.json()
List Inventory Items response example
{
"meta": {
"page": 0,
"limit": 10,
"startAt": 0,
"sortdir": "ASC"
},
"data": [
{
"id": "6c536112-c18c-4b0f-b756-3202487453c1",
"task_id": "60a7a679-73d7-4054-9679-c61c384bf007",
"assignment_id": null,
"type": "delivery",
"item_id": "abc-123",
"item_name": "apples",
"item_detail": null,
"order_id": null,
"barcode_id": null,
"expected_quantity": "20.0000",
"actual_quantity": "0.0000",
"unit_price": "0.0000",
"unit_weight": "0.0000",
"unit_type": null,
"status": "unconfirmed",
"reason_code": null,
"scanned_at": null,
"scanned_delivered_at": null,
"signature_url": null,
"signatory_name": null,
"photo_url": null,
"photo_urls": [],
"notes": null,
"props": null,
"updated_at": "2020-07-17T15:55:25.077Z",
"created_at": "2020-07-17T15:55:25.077Z"
},
{
"id": "d356fe41-b14e-4e78-911b-1c3f45da6273",
"task_id": "60a7a679-73d7-4054-9679-c61c384bf007",
"assignment_id": null,
"type": "delivery",
"item_id": "abc-124",
"item_name": "orange",
"item_detail": null,
"order_id": null,
"barcode_id": null,
"expected_quantity": "30.0000",
"actual_quantity": "0.0000",
"unit_price": "0.0000",
"unit_weight": "0.0000",
"unit_type": null,
"status": "unconfirmed",
"reason_code": null,
"scanned_at": null,
"scanned_delivered_at": null,
"signature_url": null,
"signatory_name": null,
"photo_url": null,
"photo_urls": [],
"notes": null,
"props": null,
"updated_at": "2020-07-17T18:55:50.503Z",
"created_at": "2020-07-17T18:55:50.503Z"
}
]
}
HTTP Request
GET https://api.wisesys.info/inventoryitems{?page}{?limit}{?querystringParameters}
Signing URLs
By default signature_url, photo_url and photo_urls are not signed, and will not be valid. To get the signed URLs include signed=true in the querystring. Signed URLs are valid for 7 days.
Querystring Parameters
| Parameter | Type | Description |
|---|---|---|
| page | Number | (optional) The pagination offset to return. Default: 0 |
| limit | Number | (optional) The number of results per page. Default: 10 |
| task_id | UUID | (optional) Task unique id |
| assignment_id | UUID | (optional) Assignment unique id |
| driver_id | UUID | (optional) Driver unique id |
| signed | String | e.g. "true". If signed=true is present on the querystring, the AWS S3 URLs are signed and become valid. |
Return Values
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | List of InventoryItemObject | Returns inventory items currently present in the system |
Get an Inventory Item
GET /inventoryitems/6c536112-c18c-4b0f-b756-3202487453c1 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def get_inventory_item(self, inventory_item_id):
r = requests.get(self.API_URL + "inventoryitems/" + inventory_item_id, headers=self.JSON_HEADER)
if r.status_code != 200:
print r.status_code, r.reason
return r.status_code, r.json()
Get an Inventory Item response example
{
"meta": {},
"data": {
"id": "6c536112-c18c-4b0f-b756-3202487453c1",
"task_id": "60a7a679-73d7-4054-9679-c61c384bf007",
"assignment_id": null,
"type": "delivery",
"item_id": "abc-123",
"item_name": "apples",
"item_detail": null,
"order_id": null,
"barcode_id": null,
"expected_quantity": "20.0000",
"actual_quantity": "0.0000",
"unit_price": "0.0000",
"unit_weight": "0.0000",
"unit_type": null,
"status": "unconfirmed",
"reason_code": null,
"scanned_at": null,
"scanned_delivered_at": null,
"signature_url": null,
"signatory_name": null,
"photo_url": null,
"photo_urls": [],
"notes": null,
"props": null,
"invoice_id": null,
"updated_at": "2020-07-17T15:55:25.077Z",
"created_at": "2020-07-17T15:55:25.077Z"
}
}
HTTP Request
GET https://api.wisesys.info/inventoryitems/{id}{?querystringParameters}
Signing URLs
By default signature_url, photo_url and photo_urls are not signed, and will not be valid. To get the signed URLs include signed=true in the querystring. Signed URLs are valid for 7 days.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Unique inventory item id |
Querystring Parameters
The below querystring parameters are optional.
| Parameter | Type | Description |
|---|---|---|
| task_id | UUID | Unique Task id |
| assignment_id | UUID | Unique Assignment id |
| route_date | String | Date in YYYY-MM-DD format. Filters inventory items which belong to a task with the provided route_date. route_date is ignored if a task_id is provided. |
| signed | String | e.g. "true". If signed=true is present on the querystring, the AWS S3 URLs are signed and become valid. |
Return Values
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | InventoryItemObject | Inventory Item |
Update Inventory Items
Updates all inventory items linked to an assignment
The following fields cannot be written to:
- id
- task_id
- assignment_id
- created_at
- client_id
- expected_quantity
- type
- item_id
- item_name
- item_detail
PATCH /inventoryitems?assignment_id=7c4c7819-1159-49c3-bb5a-10a44717161e HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def update_inventory_items(self, assignment_id, update):
r = requests.patch(self.API_URL + "inventoryitems?assignment_id=" + assignment_id, json=update, headers=self.JSON_HEADER)
if r.status_code != 200:
print r.status_code, r.reason
return r.status_code, r.json()
Update inventory item sample request body JSON
json { "signatory_name": "John Doe", "signature_url": "/photos/sample_photo.jpg" }Update inventory item sample response body JSONjson { "meta": {}, "data": [ { "id": "6c536112-c18c-4b0f-b756-3202487453c1", "task_id": "60a7a679-73d7-4054-9679-c61c384bf007", "assignment_id": "7c4c7819-1159-49c3-bb5a-10a44717161e", "type": "delivery", "item_id": "abc-1", "item_name": "apples", "item_detail": null, "order_id": null, "barcode_id": null, "expected_quantity": "30.0000", "actual_quantity": "30.0000", "unit_price": "0.0000", "unit_weight": "0.0000", "unit_type": null, "status": "confirmed", "reason_code": null, "scanned_at": null, "scanned_delivered_at": null, "signature_url": "/photos/sample_photo.jpg", "signatory_name": "John Doe", "photo_url": null, "photo_urls": [], "notes": null, "props": null, "invoice_id": "38e74bcb-45ea-410b-bf6d-e3c70d9199c0", "updated_at": "2020-07-15T20:07:32.759Z", "created_at": "2020-07-15T20:06:10.957Z" }, { "id": "3fec2639-dc85-4eab-85a0-2376f1868732", "task_id": "60a7a679-73d7-4054-9679-c61c384bf007", "assignment_id": "7c4c7819-1159-49c3-bb5a-10a44717161e", "type": "delivery", "item_id": "def-2", "item_name": "bananas", "item_detail": null, "order_id": null, "barcode_id": null, "expected_quantity": "25.0000", "actual_quantity": "25.0000", "unit_price": "0.0000", "unit_weight": "0.0000", "unit_type": null, "status": "confirmed", "reason_code": null, "scanned_at": null, "scanned_delivered_at": null, "signature_url": "/photos/sample_photo.jpg", "signatory_name": "John Doe", "photo_url": null, "photo_urls": [], "notes": null, "props": null, "invoice_id": null, "updated_at": "2020-07-15T20:07:32.759Z", "created_at": "2020-07-15T20:06:10.957Z" }, ] }
HTTP Request
PATCH https://api.wisesys.info/inventoryitems?assignment_id={id}
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| assignment_id | UUID | Required; unique assignment id of the items that need to be updated |
Return Values
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | InventoryItemObject [] | Array of Inventory Items |
Update an Inventory Item
Update an existing inventory item.
The following fields cannot be written to:
- id
- task_id
- assignment_id
- created_at
If the Inventory Item has an assignment_id value (which is automatically set when a route is dispatched), the following fields can no longer be written to:
- expected_quantity
- type
PATCH /inventoryitems/6c536112-c18c-4b0f-b756-3202487453c1 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def update_inventory_item(self, inventory_item_id, update):
r = requests.patch(self.API_URL + "inventoryitems/" + inventory_item_id, json=update, headers=self.JSON_HEADER)
if r.status_code != 200:
print r.status_code, r.reason
return r.status_code, r.json()
Update inventory item sample request body JSON
json { "actual_quantity": 30, "status": "confirmed" }Update inventory item sample response body JSONjson { "meta": {}, "data": { "id": "6c536112-c18c-4b0f-b756-3202487453c1", "task_id": "60a7a679-73d7-4054-9679-c61c384bf007", "assignment_id": null, "type": "delivery", "item_id": "abc-1", "item_name": "apples", "item_detail": null, "order_id": null, "barcode_id": null, "expected_quantity": "30.0000", "actual_quantity": "30.0000", "unit_price": "0.0000", "unit_weight": "0.0000", "unit_type": null, "status": "confirmed", "reason_code": null, "scanned_at": null, "scanned_delivered_at": null, "signature_url": null, "signatory_name": null, "photo_url": null, "photo_urls", "notes": null, "props": null, "updated_at": "2020-07-15T20:07:32.759Z", "created_at": "2020-07-15T20:06:10.957Z" } }
HTTP Request
PATCH https://api.wisesys.info/inventoryitems/{id}
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; unique inventory item id |
Return Values
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | InventoryItemObject | Inventory Item |
Delete an Inventory Item
DELETE /inventoryitems/6c536112-c18c-4b0f-b756-3202487453c1 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def delete_inventory_item(self, inventory_item_id):
r = requests.delete(self.API_URL + "inventoryitems/" + inventory_item_id, headers=self.JSON_HEADER)
if r.status_code != 200:
print r.status_code, r.reason
return r.status_code, r.json()
Delete Inventory Item sample response body JSON
{
"meta": {},
"data": {
"id": "6c536112-c18c-4b0f-b756-3202487453c1"
}
}
HTTP Request
DELETE https://api.wisesys.info/inventoryitems/{id}
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; Unique InventoryItem id |
Return Values
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | IdObject | Return Inventory Item unique id |
Inventory Item Lifetime
Inventory items are deleted during the task and assignment archival process.
Custom Costs
Custom costs allow users to add costs for services associated with tasks, as well as route dependent custom costs.
Task Services
Task Services are services associated with a specific task. They're stored as their service name in an attribute of the task with that service.
Add Task Service
Creates new taskService with provided cost, name, and client ID.
POST /task_services
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| task_services | Object | Required; Task service to be created with required attributes: service_name, service_cost, and client_id |
Request body JSON example
{
"task_services": {
"client_id": "5c087850-2a99-11e5-9189-eb07c479dfd5",
"service_name": "service name",
"service_cost": 20.99
}
}
Requests Expected to generate 422 (Unprocessable Entity) Response:
- Service cost is not a number (decimal number ok).
- Service cost is negative.
- Service cost is more than 1,000,000,000.
- Client ID is not a valid ID.
- User does not have access to client provided in client_id.
- Service name is not a String.
- Service name is longer than 64 characters.
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | Object | Created task service body |
Return body JSON example
{
"meta": {
"status": 0,
"message": "TaskService created"
},
"data": {
"id": "eb6c6d2b-8b94-4fd7-ad9b-715083b4c116",
"client_id": "766a3636-2e54-4a97-8be5-82dc7ddc9899",
"service_name": "service name",
"service_cost": 20.99,
"created_at": "2022-04-26T17:51:34.772Z",
"updated_at": "2022-04-26T17:51:34.772Z"
}
}
Bulk Add Task Service
Bulk create for task services
POST /task_services
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| task_services | Array | Required; Array of task services to be created with required attributes: service_name, service_cost, and client_id |
Request body JSON example
{
"task_services": [
{
"client_id": "5c087850-2a99-11e5-9189-eb07c479dfd5",
"service_name": "service name",
"service_cost": 20.99
},
{
"client_id": "5c087850-2a99-11e5-9189-eb07c479dfd5",
"service_name": "other service name",
"service_cost": 30
}
]
}
Requests Expected to generate 422 (Unprocessable Entity) Response:
If one or more of the tasks services meet the following criteria: 1. Service cost is not a number (decimal number ok). 2. Service cost is negative. 3. Service cost is more than 1,000,000,000. 4. Client ID is not a valid ID. 5. User does not have access to client provided in client_id. 6. Service name is not a String. 7. Service name is longer than 64 characters.
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | Array | Contains created task services |
Return body JSON example
{
"meta": {
"status": 0,
"message": "2 taskServices created"
},
"data": {
"task_services": [
{
"id": "eb6c6d2b-8b94-4fd7-ad9b-715083b4c116",
"client_id": "766a3636-2e54-4a97-8be5-82dc7ddc9899",
"service_name": "service name",
"service_cost": 20.99,
"created_at": "2022-04-26T17:51:34.772Z",
"updated_at": "2022-04-26T17:51:34.772Z"
},
{
"id": "bb6c6d2b-8b94-4fd7-ad9b-715083b4c116",
"client_id": "766a3636-2e54-4a97-8be5-82dc7ddc9899",
"service_name": "other service name",
"service_cost": 30,
"created_at": "2022-04-26T17:51:34.772Z",
"updated_at": "2022-04-26T17:51:34.772Z"
}
]
}
}
Find Task Services
Find task service by id, list of IDs, or client.
GET /task_services{?client_id}
QUERY STRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| task_services | string | Optional: finds task service with given ID |
| client_id | string | Optional; finds task services for given client ID |
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| task_services | array of UUIDs | Optional; array of the ids of task services to be retrieved |
Request body JSON example
{
"task_services": ["61111310-4743-11e8-a86b-25dc69243966", "766a3636-2e54-4a97-8be5-82dc7ddc9899"]
}
Requests Expected to generate 422 (Unprocessable Entity) Response:
- Task Service ID in array is not valid UUID
If Task Service passed in query params is not a valid UUID, the task services for the user's client will be returned.
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | Object | Contains: |
| task_services (Array of task services) |
Return body JSON example
{
"meta": {
"status": 0,
"message": "2 taskServices found"
},
"data": {
"task_services": [
{
"id": "eb6c6d2b-8b94-4fd7-ad9b-715083b4c116",
"client_id": "766a3636-2e54-4a97-8be5-82dc7ddc9899",
"service_name": "service name",
"service_cost": 20.99,
"created_at": "2022-04-26T17:51:34.772Z",
"updated_at": "2022-04-26T17:51:34.772Z"
},
{
"id": "bb6c6d2b-8b94-4fd7-ad9b-715083b4c116",
"client_id": "766a3636-2e54-4a97-8be5-82dc7ddc9899",
"service_name": "other service name",
"service_cost": 30,
"created_at": "2022-04-26T17:51:34.772Z",
"updated_at": "2022-04-26T17:51:34.772Z"
}
]
}
}
Update Task Services
Find task service by id, list of IDs, or client.
PATCH /task_services
QUERY STRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| task_services | String | Required: ID of task service to update |
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| service_name | Array | Optional; updated Service Name |
| service_cost | Decimal Number | Optional; updated Service Cost |
Request body JSON example
{
"service_cost": 199.99,
"service_name": "New Name"
}
Requests Expected to generate 422 (Unprocessable Entity) Response:
- Task service ID is invalid
- No task service ID is provided
- Request body does not contain either service_cost or service_name
- Service cost is not a number (decimal number ok).
- Service cost is negative.
- Service cost is more than 1,000,000,000.
- Service name is not a String.
- Service name is longer than 64 characters.
If Task Service passed in query params is not a valid UUID, the task services for the user's client will be returned.
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | Object | Contains: |
| task_services (Array of task services) |
{
"meta": {
"status": 0,
"message": "taskService cb779f70-c62c-40bb-add2-bccb741aa5e2 updated"
},
"data": [
{
"id": "cb779f70-c62c-40bb-add2-bccb741aa5e2",
"client_id": "766a3636-2e54-4a97-8be5-82dc7ddc9899",
"service_name": "New name",
"service_cost": 19.99,
"created_at": "2022-04-26T13:02:34.697Z",
"updated_at": "2022-04-26T20:43:29.653Z"
}
]
}
Delete Task Services
Delete specific task service by ID.
DELETE /task_services
QUERY STRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| task_services | string | Required: ID of task service to delete |
Requests Expected to generate 422 (Unprocessable Entity) Response:
- Task service ID is invalid
- No task service ID is provided
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | Object | Contains: |
| task_services (Array of task services) |
{
"meta": {
"status": 0,
"message": "Task Service cb779f70-c62c-40bb-add2-bccb741aa5e2 deleted"
},
"data": "cb779f70-c62c-40bb-add2-bccb741aa5e2"
}
Custom Cost Matrix
Custom cost matrices organize cost matrix entries so that multiple matrix entries can be managed at once. A matrix has a name and an active flag. A client can have at most one active custom cost matrix at a time. The active matrix is used in custom cost computation applications such as suggest.
Add Coustom Cost Matrix
Creates a new custom cost matrix with the provided name and active flag. It is also possible to create cost matrix entries for that matrix at the same time as the matrix creation. Validation of the entries included in the custom cost matrix payload follows the POST /cost_matrix_entries validation.
POST /custom_cost_matrices
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| name | String | Required; Name of the custom cost matrix |
| active | Boolean | Optional; Makes the created matrix active. Default: false |
| entries | List of cost matrix entries | Optional; Creates the given cost matrix entries and associates them to the created matrix |
Request body JSON example
json { "name": "Cost Matrix - Summer 2022", "active": false, "entries": [ { "start_zone_id": "9dbb1e5b-e4da-4e23-83a8-76508c791532", "end_zone_id": "9dbb1e5b-e4da-4e23-83a8-76508c791532", "custom_cost_terms": { "constantTerm" { "value": 42 }, "tripTerms": [], "stopTerms": [] } } ] }Note: It is also possible to create more than one matrix at once by making the request body an array of objects following the above schema.
Requests Expected to generate 422 (Unprocessable Entity) Response:
- Matrix
nameis missing - Matrix
nameis not a string activeis not a boolean- If included,
entriesis not an array - If included, an entry in
entriesfails cost matrix entry validation- Note: Matrix and entry creation is atomic. If an include entry fails validation or fails to be created, the associated matrix is not created
RETURN VALUE
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response metadata |
| data | Object | Created matrices and entries |
Example respnse JSON
json { "meta": { "status": 0, "message": "Created 1 custom cost matrix" }, "data": { "createdMatrices": [ { "id": "427e11ef-7522-4a2b-ac14-438cf73a6f73", "name": "Cost Matrix - Summer 2022", "active": false, "created_at": "2022-06-22T21:27:26.396Z", "updated_at": "2022-06-22T21:27:26.396Z" } ], "createdEntries": [ { "id": "d2b17b85-5e80-4563-ac73-a34b918672c8", "start_zone_id": "9dbb1e5b-e4da-4e23-83a8-76508c791532", "end_zone_id": "9dbb1e5b-e4da-4e23-83a8-76508c791532", "custom_cost_terms": { "constantTerm" { "value": 42 }, "tripTerms": [], "stopTerms": [] }, "created_at": "2022-06-22T21:27:26.396Z", "updated_at": "2022-06-22T21:27:26.396Z" } ] } }
Find Custom Cost Matrix
Finds the custom cost matrices matching the query.
GET /custom_cost_matrices/:id{?active}{?extent}
PATH PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | The id of the custom cost matrix to get |
QUERY STRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| active | Boolean | Optional; when true, gets the active matrix |
| extent | Comma-separated list of fields to populate | Optional; extends the listed fields with associated objects; currently only supports entries |
RETURN VALUE
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response metadata |
| data | Object or Array | Array of matching arrays |
Example response JSON
json { "meta": { "status": 0 }, "data": [ { "id": "427e11ef-7522-4a2b-ac14-438cf73a6f73", "name": "Cost Matrix - Summer 2022", "active": false, "entries": [ { "id": "816240c8-94b3-4fa2-9535-805ab6707363", "start_zone_id": "51207567-be35-430b-bdd8-4a1c1a6142ea", "end_zone_id": "378efc28-ab4d-4169-93dc-d32dc1de7c62", "custom_cost_terms": { "constantTerm": { "value": 42 }, "tripTerms": [], "stopTerms": [] }, "created_at": "2022-06-22T21:27:26.396Z", "updated_at": "2022-06-22T21:27:26.396Z" } ], "created_at": "2022-06-22T21:27:26.396Z", "updated_at": "2022-06-22T21:27:26.396Z" } ] }
Update Custom Cost Matrix
Updates allowed fields of the given custom cost matrix. Can make the given matrix active and all others inactive with the ?action=make_active query parameter
PATCH /custom_cost_matrices/:id{?action}
PATH PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Required; ID of the matrix to update |
QUERY STRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| action | String | Optional; Supported values: make_active |
Request example
http PATCH /custom_cost_matrices/880a1fbc-09ab-46ae-abc1-3d34358ac0ebjson { "name": "New name" }
Requests Expected to generate 422 (Unprocessable Entity) Response:
- Id path parameter is missing
- Id path parameter is not a UUID
nameis not a string, if providedactiveis not a boolean, if provided
RETURN VALUE
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response metadata |
| data | Object | Response data |
Response JSON example
json { "meta": { "status": 0 }, "data" { "message": "Matrix with id 880a1fbc-09ab-46ae-abc1-3d34358ac0eb was updated" } }
Delete Custom Cost Matrix
Deletes the custom cost matrix with the given id.
DELETE /custom_cost_matrices/:id
PATH PARAMTERS
| Parameter | Type | Description |
|---|---|---|
| id | UUID | id of the matrix to be deleted |
Request example
http DELETE /custom_cost_matrices/880a1fbc-09ab-46ae-abc1-3d34358ac0eb
Requests Expected to generate 422 (Unprocessable Entity) Response:
- Id path parameter is missing
- Id path parameter is not a valid UUID
RETURN VALUE
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response metadata |
| data | Object | Response data |
Response JSON example
json { "meta": { "status": 0 }, "data": { "message": "Matrix with id 880a1fbc-09ab-46ae-abc1-3d34358ac0eb was deleted" } }
Custom Cost Matrix Entries
Custom cost matrices store custom functions for calculating costs across zone to zone trips. Each entry represents the cost from the start zone to the end zone. Custom costs can include flat rates costs, threshold based costs, and/or variable costs based on trip or stop attributes. All of these, if applicable, are stored as the custom cost terms of each entry.
The available trip attributes are trip_distance and trip_weight. The only available stop attributes is wait_time.
Add Cost Matrix Entry
Creates new cost matrix entry with provided matrix id, start zone, end zone, and custom cost terms. Custom Cost Terms may contain a constant term, trip terms, and stop terms.
POST /cost_matrix_entries
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| matrix_id | String | Required; id of associated custom cost matrix |
| start_zone_id | String | Required; id of zone in which the trip begins |
| end_zone_id | String | Required; id of zone in which the trip ends |
| custom_cost_terms | Object | Required; must have valid subset of tripTerms, stopTerms and/or constantTerm |
Custom Cost Terms
Custom Cost Terms contain at least one of the following: constantTerm, tripTerms, and stopTerms.
constantTerm
| Parameter | Type |
|---|---|
| value | numeric |
tripTerms
| Parameter | Type | Description |
|---|---|---|
| termName | String | |
| termDescription | String | |
| thresholds | object | with parameters: attribute, values, firstOfType, lastOfType |
| weights | object | with parameters: attribute, values, firstOfType, lastOfType |
| isProgressive | boolean |
Request body JSON example
{
"matrix_id": "80d764e5-198d-4d31-884a-047da3c62575",
"start_zone_id": "98aa69dc-4c5d-4690-aa5b-019faa7b9793",
"end_zone_id": "998ac473-e821-4d10-afba-60e087f9ddb7",
"custom_cost_terms": {
"constantTerm": {
"value": 7
},
"tripTerms": [
{
"termName": "Trip weight premium",
"termDescription": "A trip weight premium term",
"thresholds": {
"attribute": "trip_weight",
"values": [0, 10],
"firstOfType": [5, 10],
"lastOfType": [2, 8]
},
"weights": {
"attribute": "trip_distance",
"values": [0, 10],
"firstOfType": [5, 10],
"lastOfType": [2, 8]
},
"isProgressive": false
},
{
"termName": "Trip distance",
"termDescription": "A trip distance term",
"thresholds": {
"attribute": "trip_weight",
"values": [0, 10],
"firstOfType": [5, 10],
"lastOfType": [2, 8]
},
"weights": {
"attribute": "trip_distance",
"values": [0, 10],
"firstOfType": [5, 10],
"lastOfType": [2, 8]
},
"isProgressive": false
}
],
"stopTerms": [
{
"termName": "Stop term",
"termDescription": "A stop term",
"thresholds": {
"attribute": "wait_time",
"values": [0, 10],
"firstOfType": [5, 10],
"lastOfType": [2, 8]
},
"weights": {
"attribute": "wait_time",
"values": [0, 10],
"firstOfType": [5, 10],
"lastOfType": [2, 8]
},
"isProgressive": false
}
]
}
}
Requests Expected to generate 422 (Unprocessable Entity) Response:
- matrix_id is not a UUID.
- matrix_id is not included
- start_zone_id is not a UUID
- start_zone_id is not included
- end_zone_id is not a UUID
- end_zone_id is not included
- custom_cost_terms is not included
- custom cost terms fail validation:
- constantTerm fails validation:
- constantTerm is not an object
- constantTerm.value is missing
- constantTerm.value is not a positive number
- tripTerms or stopTerms fails validation:
- tripTerms or stopTerms is not an array of objects
- tripTerms or stopTerms contains a term that fails the following validation:
- term.isProgressive is missing
- term.isProgressive is not a boolean
- term.weights is missing
- term.weights must be an object
- term.weights.attribute is missing
- term.weights.attribute is not a string
- term.thresholds is missing
- term.thresholds is not an object
- tripTerm.thresholds.attribute is missing
- term.thresholds.attribute is not a string
- term.thresholds.attribute and threshold.weight are not the same (if isProgressive is true)
- term.values is missing
- term.values is not an array
- term.values must contain finite positive numbers
- term.weight attribute is not a string
- term first and last of type is not an array (if provided)
- term first and last of type are not of same length (if provided)
- constantTerm fails validation:
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | Object | Created custom cost matrix entry body |
Return body JSON example
{
"meta": {
"status": 0,
"message": "Cost Matrix Entry Created"
},
"data": {
"id": "80d764e5-198d-4d31-884a-047da3c62575",
"matrix_id": "80d764e5-198d-4d31-884a-047da3c62575",
"start_zone_id": "98aa69dc-4c5d-4690-aa5b-019faa7b9793",
"end_zone_id": "998ac473-e821-4d10-afba-60e087f9ddb7",
"custom_cost_terms": {
"constantTerm": {
"value": 7
},
"tripTerms": [
{
"termName": "Trip weight premium",
"termDescription": "A trip weight premium term",
"thresholds": {
"attribute": "trip_weight",
"values": [0, 10],
"firstOfType": [5, 10],
"lastOfType": [2, 8]
},
"weights": {
"attribute": "trip_distance",
"values": [0, 10],
"firstOfType": [5, 10],
"lastOfType": [2, 8]
},
"isProgressive": false
},
{
"termName": "Trip distance",
"termDescription": "A trip distance term",
"thresholds": {
"attribute": "trip_weight",
"values": [0, 10],
"firstOfType": [5, 10],
"lastOfType": [2, 8]
},
"weights": {
"attribute": "trip_distance",
"values": [0, 10],
"firstOfType": [5, 10],
"lastOfType": [2, 8]
},
"isProgressive": false
}
],
"stopTerms": [
{
"termName": "Stop term",
"termDescription": "A stop term",
"thresholds": {
"attribute": "wait_time",
"values": [0, 10],
"firstOfType": [5, 10],
"lastOfType": [2, 8]
},
"weights": {
"attribute": "wait_time",
"values": [0, 10],
"firstOfType": [5, 10],
"lastOfType": [2, 8]
},
"isProgressive": false
}
]
},
"updated_at": "2022-06-02T14:29:10.981Z",
"created_at": "2022-06-02T14:29:10.981Z"
}
}
Find Cost Matrix Entries
Find cost matrix entry by ID, or find all cost matrix entries for a given custom cost matrix.
GET /cost_matrix_entries{?cost_matrix_entries}{?matrix_id}
QUERY STRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| cost_matrix_entries | string | Optional: finds cost matrix entry with given ID |
| matrix_id | string | Optional; finds all matrix entries for given matric ID |
Requests Expected to generate 422 (Unprocessable Entity) Response:
- Both cost matrix entry id or matrix id are missing
- Provided matrix_id is not a valid UUID
- Provided cost_matrix_entries is not a valid UUID
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | Object | cost matrix entry object |
Return body JSON example
{
"meta": {
"status": 0,
"message": "Cost Matrix Entry 80d764e5-198d-4d31-884a-047da3c62575 Found"
},
"data": {
"id": "80d764e5-198d-4d31-884a-047da3c62575",
"matrix_id": "80d764e5-198d-4d31-884a-047da3c62575",
"start_zone_id": "98aa69dc-4c5d-4690-aa5b-019faa7b9793",
"end_zone_id": "998ac473-e821-4d10-afba-60e087f9ddb7",
"custom_cost_terms": {
"constantTerm": {
"value": 7
},
"tripTerms": [
{
"termName": "Trip weight premium",
"termDescription": "A trip weight premium term",
"thresholds": {
"attribute": "trip_weight",
"values": [0, 10],
"firstOfType": [5, 10],
"lastOfType": [2, 8]
},
"weights": {
"attribute": "trip_distance",
"values": [0, 10],
"firstOfType": [5, 10],
"lastOfType": [2, 8]
},
"isProgressive": false
},
{
"termName": "Trip distance",
"termDescription": "A trip distance term",
"thresholds": {
"attribute": "trip_weight",
"values": [0, 10],
"firstOfType": [5, 10],
"lastOfType": [2, 8]
},
"weights": {
"attribute": "trip_distance",
"values": [0, 10],
"firstOfType": [5, 10],
"lastOfType": [2, 8]
},
"isProgressive": false
}
],
"stopTerms": [
{
"termName": "Stop term",
"termDescription": "A stop term",
"thresholds": {
"attribute": "wait_time",
"values": [0, 10],
"firstOfType": [5, 10],
"lastOfType": [2, 8]
},
"weights": {
"attribute": "wait_time",
"values": [0, 10],
"firstOfType": [5, 10],
"lastOfType": [2, 8]
},
"isProgressive": false
}
]
},
"updated_at": "2022-06-02T14:29:10.981Z",
"created_at": "2022-06-02T14:29:10.981Z"
}
}
Update Cost Matrix Entries
Update allowed fields of cost matrix entry
PATCH /cost_matrix_entries{?cost_matrix_entries}
QUERY STRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| cost_matrix_entries | string | Required: updates cost matrix entry with given ID |
REQUEST BODY
| Parameter | Type | Description |
|---|---|---|
| matrix_id | String | Optional; id of associated custom cost matrix |
| start_zone_id | String | Optional; id of zone in which the trip begins |
| end_zone_id | String | Optional; id of zone in which the trip ends |
| custom_cost_terms | Object | Optional; must have valid subset of tripTerms, stopTerms and/or constantTerm |
Request body JSON example
{
"start_zone_id": null,
"custom_cost_terms": {
"constantTerm": {
"value": 100
}
}
}
Requests Expected to generate 422 (Unprocessable Entity) Response:
- No valid update is sent
- cost_matrix_entries is not a valid UUID
- matrix_id is not a UUID (if provided)
- start_zone_id is not a UUID (if provided)
- end_zone_id is not a UUID (if provided)
- custom cost terms fail validation (if provided)
For detailed information about cost terms please see the create section.
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | Object | Updated cost matrix entry object |
Return body JSON example
{
"meta": {
"status": 0,
"message": "Cost Matrix Entry 80d764e5-198d-4d31-884a-047da3c62575 Updated"
},
"data": {
"id": "80d764e5-198d-4d31-884a-047da3c62575",
"matrix_id": "80d764e5-198d-4d31-884a-047da3c62575",
"start_zone_id": null,
"end_zone_id": "998ac473-e821-4d10-afba-60e087f9ddb7",
"custom_cost_terms": {
"constantTerm": {
"value": 100
}
},
"updated_at": "2022-06-02T14:29:10.981Z",
"created_at": "2022-06-02T18:26:56.981Z"
}
}
Delete Cost Matrix Entries
Delete cost matrix entry by ID
DELETE /cost_matrix_entries{?cost_matrix_entries}
QUERY STRING PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| cost_matrix_entries | string | Required: deletes cost matrix entry with given ID |
Requests Expected to generate 422 (Unprocessable Entity) Response:
- Cost matrix entry id is missing
- Provided cost_matrix_entries is not a valid UUID
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | Object | deleted cost matrix entry ID |
Return body JSON example
{
"meta": {
"status": 0,
"message": "Cost Matrix Entry Deleted"
},
"data": "80d764e5-198d-4d31-884a-047da3c62575"
}
Zones
Zones is a feature that allows users to upload or create polygons to that limit the geographic areas from which specified vehicles can perform tasks.
Add Zones
Creates new zones from an array of Geojson features
POST /zones HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def add_zones(self, zones):
r = requests.post("{api_url}zones".format(api_url=self.API_URL), headers=self.JSON_HEADER, json=zones)
if r.status_code != 200:
print(r.status_code, r.reason)
return r.json()
Request body JSON example
[
{
"type": "Feature",
"properties": {
"name": "Boston"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
-71.07004165649414,
42.36463232550283
],
[
-71.04909896850586,
42.36653483201386
],
[
-71.05596542358397,
42.368944590884574
],
[
-71.07004165649414,
42.36463232550283
]
]
]
}
},
{
"type": "Feature",
"properties": {
"name": "Cambridge"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
-71.11604690551758,
42.3609539828782
],
[
-71.11295700073242,
42.35435779476656
],
[
-71.07845306396484,
42.361207668593636
],
[
-71.11604690551758,
42.3609539828782
]
]
]
}
}
]
Response body JSON example
{
"meta": {},
"data": {
"success": [
{
"type": "Feature",
"properties": {
"name": "Boston"
},
"id": "2cad7a47-d249-404a-8b03-2783aa924279",
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
-71.07004165649414,
42.36463232550283
],
[
-71.04909896850586,
42.36653483201386
],
[
-71.05596542358397,
42.368944590884574
],
[
-71.07004165649414,
42.36463232550283
]
]
]
}
},
{
"type": "Feature",
"properties": {
"name": "Cambridge"
},
"id": "2cad7a47-d249-404a-8b03-2783aa924278",
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
-71.11604690551758,
42.3609539828782
],
[
-71.11295700073242,
42.35435779476656
],
[
-71.07845306396484,
42.361207668593636
],
[
-71.11604690551758,
42.3609539828782
]
]
]
}
}
],
"fail": []
}
}
HTTP REQUEST
POST https://api.wisesys.info/zones
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | Object | Json object containing list of successfully created and failed zones |
Retrieve Zones
Gets zones by id or name
GET /zones HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def get_zones(self, ids=None, names=None):
"""
:param ids: an array of zone ids
:param names: an array of zone names
If both are none, gets all zones for a client
"""
params = {"name[]": names, "id[]": ids}
r = requests.get("{api_url}zones".format(api_url=self.API_URL), headers=self.JSON_HEADER, params=params)
if r.status_code != 200:
print(r.status_code, r.reason)
return r.json()
Response body JSON example
{
"meta": {},
"data": [
{
"type": "Feature",
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
-71.07004165649414,
42.36463232550283
],
[
-71.04909896850586,
42.36653483201386
],
[
-71.05596542358397,
42.368944590884574
],
[
-71.07004165649414,
42.36463232550283
]
]
]
},
"properties": {
"name": "Allston"
},
"id": "2cad7a47-d249-404a-8b03-2783aa924278"
}
]
}
HTTP REQUEST
GET https://api.wisesys.info/zones
QUERYSTRING PARAMS
| Parameter | Type | Description |
|---|---|---|
| ids[] | UUID[] | (Optional) array of zone ids to retrieve |
| names[] | String[] | (Optional) array of zone names to retrieve |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | Zone[] | Array of zones formatted as geojson polygons |
Update a zone
The name and/or geometry of an existing zone can be updated
PATCH /zones/2cad7a47-d249-404a-8b03-2783aa924278 HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def update_zone(self, zone_id, update):
r = requests.patch("{api_url}zones/{id}".format(api_url=self.API_URL, id=zone_id), headers=self.JSON_HEADER, json=update)
if r.status_code != 200:
print(r.status_code, r.reason)
return r.json()
Request JSON example
{
"name": "Allston",
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
-71.07004165649414,
42.36463232550283
],
[
-71.04909896850586,
42.36653483201386
],
[
-71.05596542358397,
42.368944590884574
],
[
-71.07004165649414,
42.36463232550283
]
]
]
}
}
Response body JSON example
{
"meta": {},
"data": {
"type": "Feature",
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
-71.07004165649414,
42.36463232550283
],
[
-71.04909896850586,
42.36653483201386
],
[
-71.05596542358397,
42.368944590884574
],
[
-71.07004165649414,
42.36463232550283
]
]
]
},
"properties": {
"name": "Allston"
},
"id": "2cad7a47-d249-404a-8b03-2783aa924278"
}
}
HTTP REQUEST
PATCH https://api.wisesys.info/zones/{id}
PATH PARAMETERS
| Parameter | Type | Description |
|---|---|---|
| id | String | (Required) id of existing zone to update |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | Zone | Zone formatted as a Geojson polygon |
Delete a zone
DELETE /zones HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def delete_zones(self, ids):
r = requests.delete("{api_url}zones".format(api_url=self.API_URL), headers=self.JSON_HEADER, json={"ids": ids})
if r.status_code != 200:
print(r.status_code, r.reason)
return r.json()
Request JSON example
{
"ids": ["2cad7a47-d249-404a-8b03-2783aa924278", "2cad7a47-d249-404a-8b03-2783aa924279"]
}
HTTP REQUEST
DELETE https://api.wisesys.info/zones
Add a vehicle to a zone
Vehicles can be assigned to zones to be given tasks that fall within that zone's boundaries. A vehicle can be assigned to multiple zones and zones can have multiple vehicles associated to it. These associations, and their implied planning restrictions, can be in effect all the time or can be in effect at specific times during the day. Users can specify any number of shift_times that should be respected. For example a zone restriction could only be in effect during rush hour 6AM - 10AM and 4PM - 8PM.
POST /zonevehicleassociation HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def add_vehicle_to_zone(self, vehicle_id, zone_id, shift_times=None):
"""
Assigns vehicle with vehicle_id to zone with zone_id,
if shift_times is None the vehicle will always be associated to the zone
:param vehicle_id: uuid for the vehicle
:param zone_id: uuid for the zone
:param shift_times: list of dictionaries in the format [{start: , duration: }, ..]
"""
data = [{
"vehicle_id": vehicle_id,
"zone_id": zone_id,
}]
if shift_times:
data[0]["shift_times"] = {"0": shift_times}
print data
r = requests.post("{api_url}zonevehicleassociation".format(api_url=self.API_URL), headers=self.JSON_HEADER,
json=data)
r.raise_for_status()
return r.json()
Request JSON example
[{"zone_id":"f2435f0a-f275-4d3f-80d6-936a63879ec1",
"vehicle_id":"59964529-47c4-4324-b9da-c76426aa801b"}]
Response body JSON example
{
"meta": {},
"data": {
"success": [
{
"id": "c5a1c177-347e-4fe6-aec9-e2a3670cad80",
"client_id": "f4871436-f5b7-4109-a595-92096c36ca7f",
"zone_id": "f2435f0a-f275-4d3f-80d6-936a63879ec1",
"vehicle_id": "59964529-47c4-4324-b9da-c76426aa801b",
"shift_times": null
}
],
"fail": []
}
}
HTTP REQUEST
POST https://api.wisesys.info/zonevehicleassociation
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | ZoneVehicleAssociation[] | An array of successfully created associations |
Remove a vehicle from a zone
DELETE /zonevehicleassociation HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def remove_vehicle_from_zone(self, zone_id=None, vehicle_id=None):
"""
Deletes zone/ vehicle association for (zone_id, vehicle_id)
if only a vehicle id is specified, all associations with that vehicle will be deleted,
if only a zone id is specified, all associations with that zone will be deleted
:param zone_id: uuid for the zone
:param vehicle_id: uuid for the vehicle
"""
params = {"zone_id" : zone_id, "vehicle_id" : vehicle_id}
r = requests.delete("{api_url}zonevehicleassociation".format(api_url=self.API_URL), headers=self.JSON_HEADER,
params=params)
r.raise_for_status()
return r.json()
Request JSON example
[{"zone_id":"f2435f0a-f275-4d3f-80d6-936a63879ec1",
"vehicle_id":"59964529-47c4-4324-b9da-c76426aa801b"}]
HTTP REQUEST
DELETE https://api.wisesys.info/zonevehicleassociation?zone_id={id}
QUERYSTRING PARAMS
Must specify either a zone id, vehicle id, or both
| Parameter | Type | Description |
|---|---|---|
| zone_id | UUID | (optional) ID of zone |
| vehicle_id | UUID | (oprional) ID of vehicle |
Get zone vehicle associations
GET /zonevehicleassociation HTTP/1.1
Accept: application/json
Authorization: bearer UEloPJWttQpuhxMkkyZFFFaaqsFwqJ
Content-Type: application/json
def get_zone_vehicle_associations(self, zone_id=None, vehicle_id=None):
"""
Get zone/ vehicle association for (zone_id, vehicle_id)
if only a vehicle id is specified, all associations with that vehicle will be returned,
if only a zone id is specified, all associations with that zone will be returned
if both are none, all associations are returned
:param zone_id: uuid for the zone
:param vehicle_id: uuid for the vehicle
"""
params = {"zone_id" : zone_id, "vehicle_id" : vehicle_id}
r = requests.get("{api_url}zonevehicleassociation".format(api_url=self.API_URL), headers=self.JSON_HEADER,
params=params)
r.raise_for_status()
return r.json()
Response body JSON example
{
"meta": {},
"data": [
{
"id": "f4871436-f5b7-4109-a595-92096c36ca7f",
"client_id": "5c087850-2a99-11e5-9189-eb07c479dfd5",
"zone_id": "f2435f0a-f275-4d3f-80d6-936a63879ec1",
"vehicle_id": "59964529-47c4-4324-b9da-c76426aa801b",
"shift_times": null
}
]
}
HTTP REQUEST
GET https://api.wisesys.info/zonevehicleassociation
QUERYSTRING PARAMS
If only a vehicle id is specified, all associations with that vehicle will be returned. If only a zone id is specified, all associations with that zone will be returned. If both are none, all associations are returned.
| Parameter | Type | Description |
|---|---|---|
| zone_id | UUID | (optional) ID of zone |
| vehicle_id | UUID | (oprional) ID of vehicle |
RETURN VALUES
| Parameter | Type | Description |
|---|---|---|
| meta | Meta | Response meta data |
| data | ZoneVehicleAssociation[] | An array of matching zone vehicle associations |
Model Definitions
Primitive Types
Date Time
String in the ISO8601 format with an additional requirement that all components up to and including seconds must be specified. The only allowed timezone is UTC ("Z" offset). Example: "2015-06-29T16:30:00.000Z".
Unix Timestamp
Integer representing seconds since epoch. Example: 1519150119.
Error
| Parameter | Type | Description |
|---|---|---|
| code | int | One of the result codes listed in this table |
| error | String | Optional; a general error description |
| message | String | Optional; readable message providing additional details about the request result |
Result Status Codes
| Status | Status Code | Description |
|---|---|---|
| OK | 0 | Success (usually omitted) |
| GENERAL | 1 | Bad request |
| NOT_FOUND | 2 | Entity not found |
| INVALID_DATA | 3 | Invalid input data |
| INCORRECT_LOGIN | 4 | Invalid login credentials |
| EXISTS | 5 | The record already exists |
| MISSING_FIELD | 6 | Required input field(s) missing |
| NO_METHOD | 7 | Method Not Allowed |
| FORBIDDEN | 8 | Unauthorized |
| TIMEOUT | 11 | Operation timed out |
| SERVER_ERROR | 12 | Internal server error |
Meta
| Parameter | Type | Description |
|---|---|---|
| page | int | Page number starting from 0 |
| limit | int | Number of returned objects |
| sortDir | ASC | Sort type of returned results |
| startAt | int | Page starting point for next page of records returned |
| total | int | Total available objects (approximate) |
User Data Models
User Data Model
| Parameter | Type | Description |
|---|---|---|
| id | UUID | User's unique Id |
| firstname | String | User's first name |
| lastname | String | User's last name |
| username | String | Username id |
| String | this value is unique per account | |
| access | List of Access | Clients the user has access to, and the corresponding roles |
| roles | List of String | Deprecated in favor of access |
Access Data Model
| Parameter | Type | Description |
|---|---|---|
| client | UUID | Client ID |
| roles | List of String | Roles control what operations a user has permissions for; in the Wise Systems platform there are three roles: “user”, “sales”, and “administrator” |
User Group Data Model
| Parameter | Type | Description |
|---|---|---|
| id | UUID | User Group ID |
| name | String | User Group name |
| client_access[] | UserGroupClientAccess[] | Object that pairs the permissions the group is granted with the client the permissions will apply to. |
User Group Client Access Data Model
| Parameter | Type | Description |
|---|---|---|
| client_id | UUID | Client for which the permissions are granted. |
| permission | ClientAccessPermission | Object representing the permissions the User Group is granted |
Client Access Permission Data Model
| Parameter | Type | Description |
|---|---|---|
| role | String | The assigned role for the paired feature. Supported roles are viewer, editor |
| feature | String | The feature to which the user is granted access. Supported features are driver_booking, driver_management, planning, user_management |
User to User Group Association Data Model
| Parameter | Type | Description |
|---|---|---|
| id | UUID | User to User Group Association id |
| client_id | UUID | Client Id for the association |
| user_group_id | UUID | User Group associated to the User |
| user_id | UUID | User Associated to the User Group |
Client Request Data Model
| Parameter | Type | Description |
|---|---|---|
| name | String | Client's name |
| domain | String | Client's domain (e.g., wisesystems.com) |
| address | Address | Client's HQ address |
Client Response Data Model
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Unique Client ID |
| name | String | Client's name |
| domain | String | Client's web domain (e.g., wisesystems.com) |
| code | String | Mnemonic code representing the client record |
| address | UUID | Unique address ID |
| timezone | String | an ISO timezone name corresponding to the address location, e.g. "America/New_York" |
Driver Data Models
Driver Data Model
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Unique Driver ID |
| firstname | String | Driver's first name |
| lastname | String | Driver's last name |
| telephone | String | Driver's phone number; example: "+15552581001"; must be unique |
| username | String | Driver's username; must be unique |
| deviceType | String | Driver's device type; android or ios |
| location | Location | The coordinates of the address |
| defaultVehicle | Vehicle | Vehicle the driver should be planned to use |
| vehicle | Vehicle | Vehicle the driver is actively driving |
| profile | Profile | Driver's profile info |
| props | DriverProps | Driver properties |
| eid | String | (Deprecated) External reference ID |
| assignments | List of Assignment | Assignments associated with the driver |
| schedule | List of Schedule | Planned assignments ordered by ETA |
Profile Data Model
| Parameter | Type | Description |
|---|---|---|
| name | String | Full name |
| phone | String | Phone number including country code and leading + (e.g., +15552581001) |
Driver Props Data Model
{
"props": {
"shiftExceptions": {
"2019-12-21": [{
"duration": "PT7H",
"start": "08:00:00"
}]
"2019-12-25": [ ]
},
"shiftTimes": {
"0": [ ],
"1": [{
"duration": "PT8H",
"start": "09:00"
}],
"2": [{
"duration": "PT8H",
"start": "09:00"
}],
"3": [{
"duration": "PT8H",
"start": "09:00"
}],
"4": [ ],
"5": [ ],
"6": [ ],
},
"shiftTime": [ ]
}
}
| Parameter | Type | Description |
|---|---|---|
| shiftTimes | Object | Mapping between numbered days of the week and Shifts. Indicates the weekly shifts for a driver. An empty array indicates that the driver does not have a shift on that day. |
| shiftExceptions | Object | Mapping between specific dates and Shifts. Overrides what is specified in shiftTimes. A date with an empty array indicates that the driver does not have a shift on that date regardless of their normal shift schedule. |
| shiftTime | List of ShiftTime | (Deprecated) Driver daily working shifts |
Driver Assignment Data Model
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Unique Assignment Id |
| task | UUID | Unique task Id that is associated with assignment |
| location | Location | The assignment location |
| driver | UUID | The Driver unique Id that is associated with the assignment |
| type | String | Possible values: pickup, delivery, depot |
| props | AssignmentProperties | Contains details about assignment properties |
| status | int | Status of the assignment; for more info refer to this table |
Driver Assignment Properties Data Model
| Parameter | Type | Description |
|---|---|---|
| time | DateTime | Time when the pickup/delivery needs to occur |
| window | List of TimeWindow | Time windows indicating when location is accepting service |
| serviceTime | Int | Expected duration of service in seconds |
| size | Float | The volume of the goods to be carried by the vehicle, in the same units as the vehicles' volume, if used |
| weight | Float | The weight of the goods to be carried by the vehicle, in the same units as the vehicles' weight, if used |
| priority | Int | Priority of the assignment (1: high, 2: medium, 3: low); high priority assignments are scheduled to ensure arrival within customer-specified time window |
Driver Schedule Data Model
| Parameter | Type | Description |
|---|---|---|
| assignment | UUID | Unique Assignment Id |
| eta | DateTime | The actual or estimated time of arrival |
| status | int | Status of the assignment; for more info refer to this table |
| delay | int | Delay state of the assignment; for more info refer to this table |
| maybeBreakDurationMill | Number | (optional) Duration of driver break before assignment in milli-seconds |
Break Rule Data Model
| Parameter | Type | Description |
|---|---|---|
| startOffsetSeconds | Number | Specifies when the break should be taken, w.r.t. the start time of a route |
| endOffsetSeconds | Number | (optional) Specifies by how long a break can be deferred |
| durationSeconds | Number | Duration of break |
| isMandatory | Boolean | (optional) Flag indicates if the break has to be taken by the driver |
Break Rule By Start Time Data Model
| Parameter | Type | Description |
|---|---|---|
| startsAfter | Number | Specifies when the break should be taken, expressed as milliseconds since the Epoch. The break will be inserted at the earliest opportunity following the specified time. |
| duration | Number | Duration of the break in seconds |
Schedule Data Model
| Parameter | Type | Description |
|---|---|---|
| task | UUID | Unique task Id |
| pickupTime | DateTime | (optional) The ETA for a pickup task |
| deliveryTime | DateTime | (optional) The ETA for a delivery task |
Suggested Drivers Model
| Parameter | Type | Description |
|---|---|---|
| suggestedDrivers | List of SuggestedDriver | Ordered list of driver suggestions, sorted by priority |
Suggested Driver Model
| Parameter | Type | Description |
|---|---|---|
| driver | UUID | Unique driver Id |
| pickupPosition | Number | (optional) The best insertion position for a pickup task |
| deliveryPosition | Number | (optional) The best insertion position for a delivery task |
| taskId | UUID | (optional) TaskId for which suggestion applies. Returned only in case of using bulk suggest. |
| metricValue | Number | Value of the sort metric |
| explainMetrics | SuggestedDriverMetrics | (optional) Value of all possible sort metrics |
Suggested Driver Metrics Model
| Parameter | Type | Description |
|---|---|---|
| deliverySequenceInNewRoute | Number | The suggested sequence number for the proposed delivery stop |
| pickupSequenceInNewRoute | Number | The suggested sequence number for the proposed pickup stop |
| newTotalRouteTime | Number | The total route time including the proposed task(s), in seconds |
| inducedRouteTime | Number | The route time induced by the proposed task(s), in seconds |
| newNumberOfDelays | Number | The total number of delays including after adding the proposed task(s) to the schedule |
| inducedNumberOfDelays | Number | The number of delays induced by the proposed task(s) |
| customCost | Number | The total custom cost of the route after including the proposed task(s). 0 if custom cost is disabled or client has no active custom cost matrix. |
| inducedCustomCost | Number | The custom cost induced by the proposed task(s). 0 if custom cost is disabled or client has no active custom cost matrix. |
Schedule Task Data Model
| Parameter | Type | Description |
|---|---|---|
| driver | UUID | Unique driver Id |
| schedule | List of Schedule | Schedule information associated with a driver |
Manual Sequencing Response Data Model
| Parameter | Type | Description |
|---|---|---|
| delayedAssignments | List of Ids | Ids of delayed assignment |
| changedDistance | int | Additional distance the new sequence produced measured in miles |
| changedTime | int | Additional time the sequence produced measured in minutes |
| reasoncode | String | Indicates the delay reason; for the reason code mapping refer to the table |
Reason Code Data Model
| Reason | Code |
|---|---|
| R01 | Path to Delivery Blocked/Dock Full |
| R02 | Account Contact Unavailable/Closed |
| R03 | System Time Window Incorrect |
| R04 | Suggested Route Causes Increase in Time or Mileage |
| R05 | Other |
Time Window Data Model
| Parameter | Type | Description |
|---|---|---|
| start | DateTime | Start of the shift time |
| end | DateTime | End of the shift time |
Shift Data Model
| Parameter | Type | Description |
|---|---|---|
| start | DateTime | Start of the shift time in the local timezone in 24hr HH:MM format |
| duration | DateTime | Length of the shift in ISO_8601 duration format (e.g. PT8H30M) |
Compartment Types Data Models
Compartment Types Data Model
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Unique Compartment Type ID |
| client | UUID | The client to which the compartment type belongs to |
| label | String | The label for this Compartment Type |
| unit | String | The unit for this Compartment Type |
| isDefault | Boolean | The default Compartment Type for this client. Used when no compartment information is specified on Vehicles or Tasks. The default compartment can be edited, but cannot be deleted. |
Vehicle Data Models
Vehicle Data Model
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Unique Vehicle ID |
| licensePlate | String | The vehicle license plate |
| type | String | Type of the vehicle; example: truck |
| makemodel | String | The make and model of the vehicle; example: Ford F150 |
| year | String | The year of the vehicle; example: "2012" |
| weightCapacity | int | Weight limits apply for pickup tasks and take into account the type of vehicle and its weight-carrying capacity |
| volumeCapacity | int | (Deprecated, see compartments) Volume limits apply for pickup tasks and take into account the type of vehicle and its volumetric carrying capacity |
| compartments | List of Compartment Types | The list of compartments for the Vehicle with their individual capacity. The volumetric carrying capacity of each compartment can be taken into account when planning routes |
| description | String | Vehicle description |
Task Data Models
Task Data Model
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Task unique Id |
| name | String | Name of the task for display purposes |
| routeDate | String | (optional) Date (local timezone) on which the task should be planned, in YYYY-MM-DD format. If omitted current date will be used. This date doesn't have to be related to pickup/delivery windows - it's only used to group tasks together to be planned on the same date. |
| pickupContact | ContactObject | Pickup point of contact information |
| pickupLocation | Location | Address of the location where the pickup needs to occur |
| deliveryContact | ContactObject | Delivery point of contact information |
| deliveryLocation | Location | Address of the location where the delivery needs to occur |
| status | Int | Status of the task (can't be directly set by the user); for more info refer to this table |
| routeEid | String | External ID of a route. All tasks sharing the same EID will be grouped under this route and assigned to the same vehicle together. The vehicle will be optimally chosen by Route Planner. |
| vehicleEid | String | External ID of a vehicle. All tasks sharing the same EID will be grouped under this route and assigned to the vehicle that has the same external ID. |
| routeId | UUID | Can't be set by the user. Refers to a route ID in the current route plan, if the task has been planned. Empty otherwise. |
| sizeByCompartment | List of Compartment Types | The list of required compartments for the Task with their individual capacity values. The size requirement of each compartment is taken into account when planning routes. |
| eorder | Int | Used together with routeEid/vehicleEid. If specified, tasks sharing the same EID will be initially sorted based on eorder during planning. Depending on account preferences the system will either keep this sequence or further optimize it. Must be between 0 and 999. |
| props | TaskProps | Task properties |
Task Properties Data Model
| Parameter | Type | Description |
|---|---|---|
| priority | Int | Priority of the task (1: high priority, 2: medium, 3: low priority); high priority tasks are planned to ensure arrival within customer-specified time window |
| size | Float | Deprecated and replaced by sizeByCompartment. The volume of the goods to be carried by the vehicle, in the same units as the vehicles' volume, if used |
| weight | Float | The weight of the goods to be carried by the vehicle, in the same units as the vehicles' weight, if used |
| pickupTime | DateTime | Time when the pickup needs to occur |
| pickupServiceTime | String | Expected duration of pickup in ISO8601 duration format |
| pickupWindow | List of TimeWindow | Time windows indicating when location is accepting pickups |
| pickupInventory | List of Inventory | Inventory line items to be picked up |
| pickupInvoices | List of Invoices | invoices that represent money that has to be paid to successfully complete the task |
| deliveryTime | DateTime | Time when the delivery needs to occur |
| deliveryServiceTime | String | Expected duration of delivery in ISO8601 duration format |
| deliveryWindow | List of TimeWindow | Time windows indicating when location is accepting deliveries |
| deliveryInventory | List of Inventory | Inventory line items to be delivered |
| deliveryInvoices | List of Invoices | invoices that represent money that has to be paid to successfully complete the task |
Task Status Data Model
| Status | Status Code | Description |
|---|---|---|
| unassigned | 0 | Task has not been assigned to a driver |
| assigned | 1 | Task has been assigned to a driver but has not been started |
| in progress | 2 | Task currently in progress |
| completed | 3 | Task completed |
| failed | 4 | Task failed to complete |
Split Task Response Data Model
| Status | Status Code | Description |
|---|---|---|
| pickup | Task | Resulting pickup task |
| delivery | Task | Resulting delivery task |
Invoice Data Model
| Parameter | Type | Description |
|---|---|---|
| amountDue | Number | The amount of money that needs to be collected |
| invoiceNumber | String | The customer's identifier for the invoice |
Assignment Data Models
Assignment Data Model
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Assignment unique Id |
| task | UUID | Task unique id |
| driver | UUID | Driver unique id |
| status | int | Status of the assignment; for more info refer to this table |
| delay | int | Delay state of the assignment; for more info refer to this table |
| name | String | Name of the assignment |
| type | String | Possible values: pickup, delivery, depot |
| arrivalTime | DateTime | Estimated (for uncompleted) or actual (for completed assignments) arrival time |
| startServiceAt | DateTime | Time when assignment was marked as "in progress"; omitted for non-started assignments |
| completedAt | DateTime | Time when assignment was marked as "completed"; omitted for non-completed assignments |
| contact | ContactObject | Point of contact information |
| location | Location | Address of the location where the assignment takes place |
| props | AssignmentProps | Assignment properties |
Assignment Properties Data Model
| Parameter | Type | Description |
|---|---|---|
| size | Float | The volume of the goods to be carried by the vehicle, in the same units as the vehicles' volume, if used |
| weight | Float | The weight of the goods to be carried by the vehicle, in the same units as the vehicles' weight, if used |
| time | DateTime | The start time for the service time window |
| serviceTime | String | Expected duration of service in ISO8601 duration format |
| window | List of TimeWindow | Time windows indicating when location is accepting service |
| inventory | List of Inventory | Inventory line items to be picked up or delivered |
| invoices | List of Invoices | invoices that represent money that has to be paid to successfully complete the assignment |
Assignment Status Data Model
| Status | Status Code | Description |
|---|---|---|
| assigned | 0 | assigned to a driver but has not been started yet |
| in progress | 1 | currently in progress |
| completed | 2 | completed |
| canceled | 3 | assignment was canceled and can no longer be completed |
Assignment Delay Data Model
| Status | Delay Code | Description |
|---|---|---|
| early | -1 | ETA is before the time window start |
| on-time | 0 | ETA is within the time window |
| at risk | 1 | ETA + service time is past the time window end |
| delay | 2 | ETA is past the time window end |
Assignment Updates Response Data Model
| Parameter | Type | Description |
|---|---|---|
| id | String | UUID of the updated assignment |
Address Data Models
Address Data Model
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Unique Address ID |
| name | String | Address name |
| addressLine1 | String | The street address |
| addressLine2 | String | Additional non-standard details like apartment number, suite number, and other info |
| city | String | The city of the address |
| state | String | The two-letter abbreviation of the state or province of the address |
| zipcode | String | The zip or postal code of the address |
| country | String | The code country of the address in ISO codes |
| location | Location | The coordinates of the address |
| parking | Location | The coordinates of the address' parking |
Location Data Model
| Parameter | Type | Description |
|---|---|---|
| lat | Float | The latitude of the location coordinates; must be between -90.0 and +90.0 |
| lng | Float | The longitude of the location coordinates; must be between -180.0 and +180.0 |
Customer Data Models
Customer Data Model
| Parameter | Type | Description |
|---|---|---|
| contact | Contact | Customer's contact info |
| address | Address | Customer's address |
| euid | String | Customer unique Id |
| routeEuid | String | Route unique Id that is associated with the customer |
| deliveryServiceTime | String | Expected duration of the delivery; formatted as an ISO8601 duration; example: "PT1H10M36S" |
| deliveryHours | List of lists of TimeWindow | When delivery task can be serviced during each day |
| pickupServiceTime | String | Expected duration of the pickup; formatted as an ISO8601 duration; example: "PT1H10M36S" |
| pickupHours | List of lists of TimeWindow | When delivery task can be serviced during each day |
Contact Data Model
| Parameter | Type | Description |
|---|---|---|
| name | String | Full name |
| phone | String | Optional; Phone number including country code and leading + (e.g., +15552581001) |
| String | Optional; Email address |
Cod Payment Data Model
| Parameter | Type | Description |
|---|---|---|
| paymentType | enum Required; Can be [Cash, Check, Certified_Check, No_Payment, Other] |
|
| amountCollected | Number | Required; The amount of money collected by the driver for this payment |
| currency | String | Required; Currency in which the payment is made. USD is the default. |
| checkNumber | String | Optional; Must be included when paymentType is Check or Certified_Check |
| referenceNumber | String | Optional; Additional reference number can be included |
| reason | String | Optional; Mandatory when paymentType is No_Payment |
Depot Data Models
Depot Data Model
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Unique depot ID |
| address | UUID | Depot address unique ID |
| hq | Boolean | Flag indicates if the depot is used as headquarters; defaults to false |
Depot Routes Data Model
| Parameter | Type | Description |
|---|---|---|
| depotId | UUID | Unique Depot Id |
| routeId | String | Unique route Id that is associated with the depot |
Response Data Models
Address CRUD Response Data Model
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Unique Address ID |
Assignment CRUD Response Data Model
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Unique Assignment ID |
Customer CRUD Response Data Model
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Unique Customer ID |
Driver CRUD Response Data Model
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Unique Driver ID |
Depot CRUD Response Data Model
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Unique Depot ID |
Note CRUD Response Data Model
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Unique Note ID |
Schedule Task Response Data Model
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Scheduled job Id |
User CRUD Response Data Model
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Unique User ID |
Vehicle CRUD Response Data Model
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Unique Vehicle ID |
Compartment Type CRUD Response Data Model
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Unique Compartment Type ID |
Inventory Item CRUD Response Data Model
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Unique InventoryItem ID |
Subscription Id Object
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Unique Subscription ID |
Route Data Model
| Parameter | Type | Description |
|---|---|---|
| driverId | UUID | Unique Depot Id |
| route | String | Unique route Id that is associated with the depot |
| routeInfo | UUID | Unique Depot Id |
RouteInfo Data Model
| Parameter | Type | Description |
|---|---|---|
| totalWaitingTime | int | Route's idle time measured in seconds |
| numberOfUnassignedTasks | int | The number of tasks that remain in an unassigned state |
| totalDelay | int | Route delay time measured in seconds |
| totalServiceTime | int | Total service time for all tasks that belong to the route |
| numberOfOpenRoutes | int | Indicates the number of routes that have capacity |
| totalTravelTime | int | The route's travel time for all tasks |
| totalMeters | int | Total distance vehicle travelled to serve all tasks that belong to the route |
| numberOfExtraNeededVehicles | int | Vehicles need to compensate for the task capacity |
| numberOfViolatedTW | int | Number of violated time windows |
| timeOnRoad | int | Total duration vehicle spent on the road to complete all tasks in the route |
| numberOfTasks | int | Number of tasks that belong to the route |
Schedule Data Model
| Parameter | Type | Description |
|---|---|---|
| departureTime | int | Time when the pickup needs to occur |
| task | UUID | Task unique Id |
| deliveryTime | int | The time window for the delivery measured in Unix time |
| violatedTW | Boolean | Number of time windows that have been violated |
| delay | int | Duration of the delay measured in seconds |
| waitingTime | int | Duration of the waiting time measured in seconds |
| delayFlag | int | 0 indicates there is a delay and -1 indicates no delay |
| pickupTime | int | Measured in Unix time |
SolutionInfo Data Model
| Parameter | Type | Description |
|---|---|---|
| totalWaitingTime | int | Route's idle time measured in seconds |
| numberOfUnassignedTasks | int | The number of tasks that remain an in unassigned state |
| eta_type | int | Indicates which method was used to calculate the route's eta |
| totalDelay | int | Route plan's total delay time measured in seconds |
| totalServiceTime | int | The sum of service time for all tasks in the entire solution |
| numberOfOpenRoutes | int | Number of the routes that have capacity |
| totalTravelTime | int | Measured in seconds |
| totalMeters | int | Total travelled distances for all vehicles measured in meters |
| numberOfExtraNeededVehicles | int | Vehicles needed to compensate for the task capacity |
| numberOfViolatedTW | int | Number of time windows violated |
| timeOnRoad | int | The sum of the total time spent on the road for all routes |
| numberOfTasks | int | Number of tasks that are part of the routes |
Routeplan Data Model
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Unique Routeplan id |
| route_date | Date | Date in yyyy-mm-dd format |
| client_id | UUID | Unique Client Id of whom this routeplan belongs to |
| type | String | Which method was used for generating this routeplan |
| sub_type | String | Which internal algorithm was used |
| eta_type | String | Provider of the estimate |
| total_travel_time | Number | Measured in seconds |
| total_waiting_time | Number | Route's idle time measured in seconds |
| number_of_tasks | Number | Number of tasks that are part of the routes |
| number_of_extra_needed_vehicles | Number | Vehicles needed to compensate for task capacity |
| number_of_violated_hard_tw | Number | Number of hard time windows violated |
| total_delay | Number | Route plan's total delay time measured in seconds |
| total_service_time | Number | Sum of service time for all tasks in the solution |
| total_meters | Number | Total travelled distances for all vehicles measured in meters |
| number_of_open_routes | Number | Number of routes with no tasks assigned |
| number_of_unassigned_tasks | Number | Number of tasks which have not been assigned |
| time_on_road | Number | Sum of total time spent on road for all routes |
| number_of_violated_tw | Number | Number of time windows violated |
| active | Boolean | Is the current routeplan being used |
| valid | Boolean | Is this routeplan valid |
| stage | String | At what point in the internal process was this routeplan left. |
| routes | List of Routeplan Route Data | List of Routeplan Route Data |
| scheduler_id | UUID | Unique scheudler id |
| created_at | Timestamp | When was this record created |
| updated_at | Timestamp | When was this record last updated |
Routeplan Route Data Model
| Parameter | Type | Description |
|---|---|---|
| driverId | UUID | Unique id of driver who has this route |
| routeInfo | RouteInfo | A RouteInfo object |
| routeInfoV2 | RouteInfo | A RouteInfo object |
| routes | List of Routeplan Route objects | A Routeplan Route Object |
| vehicleId | UUID | Unique id of the vehicle used on this route |
| vehicleProps | Vehicle Props Object | Object of vehicle props |
Vehicle Props Data Model
| Parameter | Type | Description |
|---|---|---|
| type | String | Unique id of driver who has this route |
| volumeCapacity | Number | volume capacity of the vheicle |
| weightCapacity | Number | weight capacity of the vehicle |
Routeplan Route Object Model
| Parameter | Type | Description |
|---|---|---|
| routeId | UUID | Description |
| routeInfo | RouteInfo | Description |
| stops | List of Stop Data | Description |
Depot Delete Route Data Model
| Parameter | Type | Description |
|---|---|---|
| routeId | String | Unique route Id that is associated with the depot |
Webhook Subscription Data Model
| Parameter | Type | Description |
|---|---|---|
| id | uuid | Subscription Id |
| client | uuid | Client Id |
| enabled | Boolean | Validates whether the subscription is active or not |
| url | String | URL where the message will be sent to |
| description | String | Brief webhook description |
| secret_token | String | Text used to authenticate that the received requests come from the Wise Systems Platform |
| subscribed_events | String[] | List of event that trigger message sending |
Inventory Item Data Model
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Unique InventoryItem ID |
| task_id | UUID | Unique Task ID |
| assignment_id | UUID | Unique Assignment ID |
| type | String | "delivery" or "pickup" |
| item_id | String | Externally provided |
| item_name | String | Externally provided. Primary name displayed for the item, in Wise Applications. |
| item_detail | String | Externally provided |
| order_id | String | Externally provided |
| barcode_id | String | Externally provided |
| invoice_id | UUID | Externally provided |
| expected_quantity | Number | The amount that was expected to be picked up or delivered. Positive number value with four decimal place precision. |
| actual_quantity | Number | The amount that was actually picked up or delivered. Positive number value with four decimal place precision. |
| unit_price | Number | Price of a single unit of the item. Number value with four decimal place precision. |
| unit_weight | Number | Weight of a single unit of the item. Number value with four decimal place precision. |
| unit_type | String | Specify what type of unit, each unit is. e.g., "kegs", or "boxes". 16 Characters max. |
| status | String | "confirmed", "unconfirmed", "cancelled", "try-later", "partial". Defaults to "unconfirmed" |
| reason_code | String | Reason code usually chosen by driver from a pre-selected set for success or failure of inventory item. |
| scanned_at | Date | Timestamp of when the item was scanned during loading, if scanned. |
| scanned_delivered_at | Date | Timestamp when the item was scanned during delivery, if scanned. |
| signature_url | String | URL of the signature, if signature taken. Valid for 7 days after requested. |
| signatory_name | String | Name of signatory upon delivery/pickup, if signature taken. |
| photo_url | String | (Deprecated in favor of supporting multiple URLs with photo_urls) URL of a photo taken, if taken. Valid for 7 days after requested. |
| photo_urls | String ] | Array of urls of photos taken, if taken. Valid for 7 days after requested. |
| notes | String | Notes relevant to the inventory item. |
| props | Object | Externally provided key: value pairs. |
| updated_at | Date | Timestamp of last time inventory item was updated. |
| created_at | Date | Timestamp of when inventory item was created. |
Zone Data Model
Zones are represented as geojson polygons with a specified
geometryandnameand should be formatted as follows:
{
"type": "Feature",
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
-71.07004165649414,
42.36463232550283
],
[
-71.04909896850586,
42.36653483201386
],
[
-71.05596542358397,
42.368944590884574
],
[
-71.07004165649414,
42.36463232550283
]
]
]
},
"properties": {
"name": "Allston"
}
}
The zone geojson will also get an id parameter after it's created in the system. For more details on geojson format see https://tools.ietf.org/html/rfc7946.
Zone Vehicle Association Data Model
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Unique ZoneVehicleAssociation Id |
| client_id | UUID | client Id |
| zone_id | UUID | zone Id |
| vehicle_id | UUID | vehicle Id |
| shift_times | {“0”: {start: string, duration: string}[]} | (Optional) times that a vehicle is associated to a zone |
Revision History
| Date | Description |
|---|---|
| 2019/10/04 | First public revision |
| 2019/12/03 | Copy edit public revision |