Overview
This article contains documentation for the Mileage web service, all related API calls, and possible errors.
You can use Ctrl+F to search for the required error message.
For more information about all available Web Services and corresponding methods, refer to the Introduction to Web Services article.
Information
The mileage web service allows you to retrieve all the trip information and also calculates the trip distance, total expenses, and duration of the trip.
This web service includes the following methods:
getTrips
Provides all the trips for the requested customer id for the given date range. The date range should not exceed 90 days.
Method Signature
|
Ordinal |
DataType |
Required |
Description |
|---|---|---|---|
|
startDate |
SvDate |
Yes |
Starting date of the search range. |
|
endDate |
SvDate |
Yes |
Ending date of the search range. |
|
Return Result |
SvTrip[] |
Yes |
Returns an array of SvTrip. |
Validation Errors
- “The start date cannot be null.” – thrown if the start date is null
- “The end date cannot be null.” – thrown if the end date is null
- “The end date must be after the start date.” – thrown if the start date is after the end date.
- “You are only allowed to query for 90 days of data at a time.” – thrown if the search range exceeds 90 days.
getTripsByWorker
This API provides the entire trip done by the requested worker for the given time range.
Method Signature
|
Ordinal |
DataType |
Required |
Description |
|---|---|---|---|
|
startDate |
SvDate |
Yes |
Starting date of the search range. |
|
endDate |
SvDate |
Yes |
Ending date of the search range. |
|
workerName |
SvString |
Yes |
The username of the worker who has performed the trips. |
|
Return Result |
SvTrip[] |
Yes |
Returns an array of SvTrip. Returns empty array if no trips found. |
Validation Errors
- “The start date cannot be null.” – thrown if the start date is null
- “The end date cannot be null.” – thrown if the end date is null
- “The end date must be after the start date.” – thrown if the start date is after the end date.
- “You are only allowed to query for 90 days of data at a time.” – thrown if the search range exceeds 90 days.
- “The worker name cannot be null.” – thrown if the workerName is null or blank.
- “Could not find a worker with the username.” – thrown if the specified workerName cannot be found.
getTripsByJob
This API provides all the trip data associated with the requested Job for the given time range.
Method Signature
|
Ordinal |
DataType |
Required |
Description |
|---|---|---|---|
|
startDate |
SvDate |
Yes |
Starting date of the search range. |
|
endDate |
SvDate |
Yes |
Ending date of the search range. |
|
jobReferenceNumber |
SvString |
Yes |
jobReferenceNumber of the linked trips. |
|
Return Result |
SvTrip[] |
Yes |
Returns an array of SvTrip. Returns empty array if no trips found. |
Validation Errors
- “The start date cannot be null.” – thrown if the start date is null
- “The end date cannot be null.” – thrown if the end date is null
- “The end date must be after the start date.” – thrown if the start date is after the end date.
- “You are only allowed to query for 90 days of data at a time.” – thrown if the search range exceeds 90 days.
- “The jobReferenceNumber cannot be null.” – Thrown if jobReferenceNumber is null or blank.
- “Could not find a job with the jobReferenceNumber.” – Thrown if the job with the specified jobReferenceNumber cannot be found.
Interface Objects
SvTrip
|
Field |
Data Type |
Description |
|---|---|---|
|
startDateTime |
SvDate |
Trip start date and time. |
|
endDateTime |
SvDate |
Trip end date and time. |
|
workerName |
SvString |
In version 0.0.1, returns first name and last name. If first name and last name is null then returns preferred name. All later versions return the username of the worker. |
|
workerGroup |
SvString |
Group name of the worker who performed the trip. |
|
category |
SvString |
Category of the trip. Used for the calculation of the expenses. |
|
purpose |
SvString |
Purpose of the trip (e.g. Sales Call, Delivery) |
|
status |
SvString |
Current status of the trip: Started or Completed. |
|
jobName |
SvString |
Name of the linked job. |
|
jobReferenceNumber |
SvString |
jobReferenceNumber of the linked job. |
|
duration |
Integer |
The duration of the trip in minutes. |
|
odometerDistance |
Double |
Distance covered in the trip according to odometer reading. |
|
gpsDistance |
Double |
Distance covered according to the GPS points collected by the device. |
|
suggestedRouteDistance |
Double |
Distance of the suggested route between start and end trip point provided by Google. |
|
startOdometer |
Double |
Start trip odometer reading. |
|
endOdometer |
Double |
End trip odometer reading. |
|
reimbursementRate |
Double |
Reimburse rate according to the category of the trip. |
|
additionalExpenses |
Double |
Any additional expenses for the trip. |
|
totalExpense |
Double |
Sum of Reimbursement and the additional expenses. |
|
notes |
SvString |
Notes entered by the trip worker. |
|
tripStartLocation |
SvTripLocation |
Trip start location details. |
|
tripEndLocation |
SvTripLocation |
Trip end location details. |
|
gpsPoints |
SvGpsPosition[] |
All the GPS points of the user route. |
|
placeHolder1 |
String |
Extra placeholder field for future usage. |
|
placeHolder2 |
String |
Extra placeholder field for future usage. |
|
placeHolder3 |
String |
Extra placeholder field for future usage. |
|
placeHolder4 |
String |
Extra placeholder field for future usage. |
SvTripLocation
|
Field |
Data Type |
Description |
|---|---|---|
|
locationName |
SvString |
The nearest landmark to the trip start/end. |
|
locationReferenceNumber |
SvString |
Reference number of the start/end trip landmark. |
|
latitude |
SvString |
Start/End trip GPS point latitude. |
|
longitude |
SvString |
Start/End trip GPS point longitude. |
|
address |
SvString |
Start/End trip address. |