The Terminals endpoint contains a list of the locations for the motor carrier’s Terminals. It is used to filter results on the portal, e.g. to show all Drivers or Equipment assigned under a particular Terminal. Both the Drivers and Equipment APIs have a foreign key relationship with Terminals API.
Fields
Aside from the name field, the Terminals API also requires the startTimeofDay field to set the same field on the Drivers assigned to it upon creation. The full address is divided up into separate fields and a corresponding timezone. There is also an optional terminalCode field as an alternate way to identify the Terminal on a per Account basis.
| Tag | Data Type | Required | Description |
| accountId | Long | No | The id of the Account that owns this record. |
| city | Text (unlimited) | No | The city where the Terminal is located |
| country | Text (unlimited) | No | The country where the Terminal is located. Can be:
|
| deletedAt | Text (unlimited) | No | Indicates the date and time when the Terminal was soft-deleted. Note: Format is in timestamp and timezone (YYYY-MM-DDTHH:MM:SS.sssZ, e.g: 1970-01-01T00:00:00.000Z). This is not returned for Terminals that have not been soft-deleted. |
| id | Auto-incremented Long | Auto | Unique Identifier |
| lastChangedDate | Text | Auto | Auto-generated timestamp of the last change made to this record Note: Format is in timestamp and timezone (YYYY-MM-DDTHH:MM:SS.sssZ, e.g: 1970-01-01T00:00:00.000Z) |
| latitude | Double Precision | Auto | Indicates the latitude coordinate of the location where the Terminal is located |
| longitude | Double Precision | Auto | Indicates the longitude coordinate of the location where the Terminal is located |
| mainOffice | Boolean | No | Indicates if the Terminal is the main office or not. Only one Terminal can be main office at a time. Setting this to true for one Terminal will set all other Terminals to false |
| name | Text (unlimited) | Yes | The name of the Terminal |
| phoneNumber | Character (50) | No | The phone number of the Terminal |
| postalCode | Text (unlimited) | No | The postal code where the Terminal is located |
| startTimeOfDay | Text | Yes | The start time of day set for the terminal Note: Format can be in (HH:MM:SS) or (HH:MM:SS.sss) |
| state | Text (unlimited) | No | The state where the Terminal is located. Can either be one of the following state codes:
|
| street | Text (unlimited) | No | The street where the Terminal is located |
| terminalCode | Text (unlimited) | No | The optional in-account code used to identify the Terminal |
| timeZone | Text (unlimited) | Yes |
Time zone where the Terminal is located. Can either be:
|
| ymRadiusThresholdKm | Double Precision | No |
The amount in km within the terminal’s location to be assigned as yard moves when the driver is within that range. |
Read
| API PATH: | /api/v2/terminals |
| METHOD: | GET |
| PARAMETERS: | name – Retrieves matching records with the specific name (e.g. name=Terminal1, all Terminals by default) terminal-code – Retrieves matching records with the specific terminalCode (e.g. terminal-code=HT-001, all Terminal codes by default) from-deleted-at – Retrieves matching records that were deleted after the specified timestamp. Setting to * will return all records. (e.g. from-deleted-at=2016-11-11T06:57:06.629Z, null by default – returns only non-deleted records) offset – Retrieves matching records after an offset value (e.g. offset=2) limit – Retrieves a number of records per page specified by the value (e.g. limit=10) |
| SORTING | sort=id – Sort records by their id field in ascending order (DEFAULT) sort=-id – Sort records by their id field in descending order sort=name – Sort records by their name field in ascending order sort=-name – Sort records by their name field in descending order |
| QUERY STRING EXAMPLES: | Get the Terminal with the specified id: api/v2/terminals/39 Get two Terminals of the current Account with an offset of 1 : ?offset=1&limit=2 Get all Terminals of the current Account sorted by name alphabetically: ?sort=name |
| EXAMPLE RESPONSE: |
[
{
"name": "Terminal1",
"street": "Central Avenue. Lake Station",
"city": "Lake County",
"state": "Indiana",
"postalCode": "46405",
"country": "United States of America",
"timeZone": "CST6CDT",
"startTimeOfDay": "00:00:00.000",
"terminalCode": "HT-001",
"latitude": 41.8911622,
"longitude": -87.6235815,
"mainOffice": true,
"phoneNumber": "1223334444",
"ymRadiusThresholdKm": 0.25,
"accountId": 1248100,
"id": 39,
"lastChangedDate": "2018-06-11T12:00:00.000Z"
}
]
|
| ymRadiusThresholdKm | The terminal’s radius for yard moves in KM. |
Create
| API PATH: | /api/v2/terminals |
| METHOD: | POST |
| REQUIRED FIELDS: | name, startTimeOfDay |
| EXAMPLE REQUEST: |
[
{
"name": "Terminal1",
"street": "Central Avenue. Lake Station",
"city": "Lake County",
"state": "Indiana",
"postalCode": "46405",
"country": "United States of America",
"timeZone": "CST6CDT",
"startTimeOfDay": "00:00:00.000",
"terminalCode": "HT-001",
"mainOffice": false,
"phoneNumber": "1223334444"
}
]
|
| EXAMPLE RESPONSE: |
[
{
"name": "Terminal1",
"street": "Central Avenue. Lake Station",
"city": "Lake County",
"state": "Indiana",
"postalCode": "46405",
"country": "United States of America",
"timeZone": "CST6CDT",
"startTimeOfDay": "00:00:00.000",
"terminalCode": "HT-001",
"latitude": 41.8911622,
"longitude": -87.6235815,
"mainOffice": false,
"phoneNumber": "1223334444",
"ymRadiusThresholdKm": 0.25,
"accountId": 1248100,
"id": 39,
"lastChangedDate": "2018-06-11T12:00:00.000Z"
}
]
|
Update
| API PATH: | /api/v2/terminals |
| METHOD: | PUT |
| EXAMPLE REQUEST: |
[
{
"name": "Terminal2",
"street": "Central Avenue. Lake Station",
"city": "Lake County",
"state": "Indiana",
"postalCode": "46405",
"country": "United States of America",
"timeZone": "CST6CDT",
"startTimeOfDay": "01:00:00.000",
"terminalCode": "HT-001",
"mainOffice": true,
"phoneNumber": "1223334444",
"id": 39
}
]
|
| EXAMPLE RESPONSE: |
[
{
"name": "Terminal2",
"street": "Central Avenue. Lake Station",
"city": "Lake County",
"state": "Indiana",
"postalCode": "46405",
"country": "United States of America",
"timeZone": "CST6CDT",
"startTimeOfDay": "01:00:00.000",
"terminalCode": "HT-001",
"latitude": 41.8911622,
"longitude": -87.6235815,
"mainOffice": true,
"phoneNumber": "1223334444",
"ymRadiusThresholdKm": 0.25,
"accountId": 1248100,
"id": 39,
"lastChangedDate": "2018-06-11T12:00:00.000Z"
}
]
|
Delete
| API PATH: | /api/v2/terminals/<id> |
| METHOD: | DELETE |
| REQUIRED FIELDS: | id |
Drivers assigned under the deleted Terminal are moved to the default main office Terminal. Delete for the Terminals API is implemented using a soft-delete. This prevents SQL’s Cascade Delete from deleting any driving records associated with a deleted Terminal. Eventually, following the motor carrier’s data retention policy, the soft-delete will become a hard-delete.
Single Nearest Terminal
| API PATH: | /api/v2/terminals/meta/nearest |
| METHOD: | GET |
| PARAMETERS | ?lat=40.484674&long=-88.984680 |
| EXAMPLE REQUEST: |
[
{
"id": 183,
"name": "Loc1",
"latitude": 41.4851517,
"longitude": -88.98509159999999,
"distance": 0.063,
"terminalCode": "HT-001"
}
]
|
Multiple Nearest Terminals
| API PATH: | /api/v2/terminals/meta/nearest |
| METHOD: | POST |
| EXAMPLE REQUEST: |
[
{
"correlationId": 225,
"lat": 44.223,
"long": -88.4422
},
{
"correlationId": 226,
"lat": 20.223,
"long": -90.73
}
]
|
| EXAMPLE RESPONSE: |
[
{
"correlationId": 225,
"terminals": [
{
"id": 4320454,
"name": "Chicago Navy Pier Branch Terminal",
"latitude": 44.222,
"longitude": -88.4421,
"distance": 71.84,
"terminalCode": "HT-001"
}
]
},
{
"correlationId": 226,
"terminals": [
{
"id": 5322555,
"name": "A Terminal Near This Location",
"latitude": 20.34,
"longitude": -91.4,
"distance": 400.84,
"terminalCode": "HT-002"
}
]
}
]
|
API error calls
| ERROR MESSAGE | HTTP STATUS | ERROR CODE | POSSIBLE CAUSES |
| Entities should not contain an Id when creating. | 500 | 11000 | POST error because request must not contain an id |
| Terminal should have a name. | 500 | 7000 | POST error because the Terminal must have a name |
| Terminal should have a value for Start Time of Day. | 500 | 7000 | POST error because the Terminal must have a Start Time of Day |
| Unable to save record | 500 | 500 | POST or PUT error because required fields are missing or incorrect |
|
Access Denied. User is not authorized for this request.
|
403
|
8000
|
POST and PUT methods require permission of PERM_IS_ACCOUNT_ADMIN and PERM_EDIT_TERMINALS |
| DELETE method require permission of PERM_EDIT_TERMINALS | |||
| Unable to save the Terminal. Name already in use. | 500 | 1001 | POST or PUT error because the Terminal name is already used by another Terminal. |
| Unable to save the Terminal. Terminal Code already in use. | 500 | 1001 | POST or PUT error because the Terminal Code is already used by another Terminal. |
| Cannot find requested entity. (id = <id>) | 500 | 3000 | PUT or DELETE error because the supplied id does not exist |
| Main Office Terminal cannot be deleted | 500 | 11000 | DELETE error because a Terminal that is set as main office cannot be deleted |
| Error while handling request | 500 | 500 | Generic error message. Something is wrong with the request |