Overview
This article contains documentation for the GPS 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
This web service includes the following methods:
- GetGps
- GetGpsByDivision
- GetGpsByWorker
- GetStopsAndTravel
- getStopsAndTravelByWorker
- getStopsAndTravelByDivision
- getStops
- getStopsByWorker
- getStopsByDivision
- getTravel
- getTravelByWorker
- getTravelByDivision
- SubmitGps
GetGps
The getGps (String, SvDate, SvDateHolder) service method provides the ability to retrieve GPS information for an entire company over a specified time range. The intended usage of this service call is to provide a way to periodically synchronize an external system’s data with Field Force Manager. The external system is expected to call this service incrementally using adjacent time ranges such as:
Call 1: 2004-01-28 13:50:00.0000 to 2004-01-28 14:52:00.000
Call 2: 2004-01-28 14:52:00.0000 to 2004-01-28 15:49:07.000
Call 3: 2004-01-28 15:49:07.0000 to 2004-01-28 16:55:43.000
The external system must keep track of the last call’s endTime and should use the last endTime as the startTime for the next call. The results returned are inclusive on the startTime and exclusive on the endTime to prevent you from receiving overlapping results.
Method Signature
|
Ordinal |
DataType |
Can be Null? |
Description |
|---|---|---|---|
|
StartDate |
SvDate |
No |
The starting date and time for the requested range of results. The query returns changes including the specified start time. The time date format must be provided in the following format: yyyy-MM-dd HH:mm:ss.SSS For example, a start time of 1:50 PM on January 28th, 2004 would be 2004-01-28 13:50:00.000 |
| EndDate | SvDateHolder | No |
Ending date for the range of results. The query returns changes up to BUT NOT including the specified end time. The time date format must be provided as: yyyy-MM-dd HH:mm:ss.SSS |
| Return Result | SvGpsPositio n[] | No |
An array of SvGpsPosition instances. See documentation on SvGpsPosition for more details |
Expected behavior
- GPS positions are returned with a coverage status code. Valid GPS positions have a value of 0 for the status code. Invalid GPS position will have a non-0 status code value. The status code values indicate why the GPS acquisition failed (e.g., user indoors and cannot get GPS, battery too low, user turned off GPS permissions, etc.)
- If the status code value for a position is non-0 (invalid), the latitude and longitude will be 0.
- If the endDate is equal to or before the startDate, an exception is thrown.
- If either the start or end time and date parameters are null, an exception is thrown.
- If no new GPS points are detected for the company, an empty array is returned (i.e., Field Force Manager received no GPS information for the specified time range).
- The maximum date range that can be requested is 7 days. If the date range exceeds 7 days, a validation exception is thrown.
- The maximum number of GPS points returned is 500.
- If the difference between the GPS collection date (fix) on the mobile device and the date when the GPS point actually reached the Field Force Manager server, is more than 4 days, then that GPS point is not returned back in the web service response. This may happen if the GPS was collected on the mobile device (but not sent to Field Force Manager yet), and then the device was turned off and then turned on after 4 days.
GetGpsByDivision
Description
The getGpsByDivision (String, SvDate, SvDateHolder) service method provides the ability to retrieve GPS information for a specified division over a specified time range. The division must exist in Field Force Manager, otherwise, an exception is thrown. The intended usage of this service call is to provide a way to periodically synchronize an external system’s data with Field Force Manager. The external system is expected to call this service incrementally using adjacent time ranges such as:
Call 1: 2004-01-28 13:50:00.0000 to 2004-01-28 14:52:00.000
Call 2: 2004-01-28 14:52:00.0000 to 2004-01-28 15:49:07.000
Call 3: 2004-01-28 15:49:07.0000 to 2004-01-28 16:55:43.000
The external system must keep track of the last call’s endTime and should use the last endTime as the startTime for the next call. The results returned are inclusive on the startTime and exclusive on the endTime to prevent you from receiving overlapping results.
Method Signature
|
Ordinal |
DataType |
Can be Null? |
Description |
|---|---|---|---|
|
Divisions |
String[] |
No |
List of divisions for which GPS points will be retrieved. |
|
StartDate |
SvDate |
No |
The starting date and time for the requested range of results. The query returns changes including the specified start time. The time date format must be provided in the following format: yyyy-MM-dd HH:mm:ss.SSS For example, a start time of 1:50 PM on January 28th, 2004 would be 2004-01-28 13:50:00.000 |
|
EndDate |
SvDateHolder |
No |
Ending date for the range of results. The query returns changes up to BUT NOT including the specified end time. The time date format must be provided as: yyyy-MM-dd HH:mm:ss.SSS |
|
Return Result |
SvGpsPosition[] |
No |
An array of SvGpsPosition instances. |
Expected behavior
- GPS positions are returned with a coverage status code. Valid GPS positions have a value of 0 for the status code. Invalid GPS position will have a non-0 status code value. The status code values indicate why the GPS acquisition failed (e.g., user indoors and cannot get GPS, battery too low, user turned off GPS permissions, etc.)
- If the status code value for a position is non-0 (invalid), the latitude and longitude will be 0.
- If the endDate is equal to or before the startDate, an exception is thrown.
- If either the start or end timedate parameters are null, an exception is thrown.
- If no new GPS points are detected for the division, an empty array is returned (i.e., Field Force Manager received no GPS information for the specified time range).
- The maximum date range that can be requested is 7 days. If the date range exceeds 7 days, a validation exception is thrown.
- The maximum number of GPS points returned is 500.
- If the difference between the GPS collection date (fix) on the mobile device and the date when the GPS point actually reached the Field Force Manager server, is more than 4 days, then that GPS point is not returned back in the web service response. This may happen if the GPS was collected on the mobile device (but not sent to Field Force Manager yet), and then the device was turned off and then turned on after 4 days.
GetGpsByWorker
Description
The getGpsByWorker (String, SvDate, SvDateHolder) service method provides the ability to retrieve GPS information for a specified worker over a specified time range. The worker must exist in Field Force Manager, otherwise, an exception is thrown. The intended usage of this service call is to provide a way to periodically synchronize an external System’s data with Field Force Manager. The external system is expected to call this service incrementally using adjacent time ranges such as:
Call 1: 2004-01-28 13:50:00.0000 to 2004-01-28 14:52:00.000
Call 2: 2004-01-28 14:52:00.0000 to 2004-01-28 15:49:07.000
Call 3: 2004-01-28 15:49:07.0000 to 2004-01-28 16:55:43.000
The external system must keep track of the last call’s endTime and should use the last endTime as the startTime for the next call. The results returned are inclusive on the startTime and exclusive on the endTime to prevent you from receiving overlapping results.
Method Signature
|
Ordinal |
DataType |
Can be Null? |
Description |
|---|---|---|---|
|
WorkerName |
String |
No |
The username for a valid user in the application |
|
StartDate |
SvDate |
No |
The starting date and time for the requested range of results. The query returns changes including the specified start time. The time date format must be provided in the following format: yyyy-MM-dd HH:mm:ss.SSS For example, a start time of 1:50 PM on January 28th, 2004 would be 2004-01-28 13:50:00.000 |
|
EndDate |
SvDateHolder |
No |
Ending date for the range of results. The query returns changes up to BUT NOT including the specified end time. The time date format must be provided as: yyyy-MM-dd HH:mm:ss.SSS |
|
Return Result |
SvGpsPositio n[] |
No |
An array of SvGpsPosition instances. |
Expected behavior
- The worker specified by the WorkerName parameter must exist, otherwise an exception is thrown.
- GPS positions are returned with a coverage status code. Valid GPS positions have a value of 0 for the status code. Invalid GPS position will have a non-0 status code value. The status code values indicate why the GPS acquisition failed (e.g., user indoors and cannot get GPS, battery too low, user turned off GPS permissions, etc.)
- If the status code value for a position is non-0 (invalid), the latitude and longitude will be 0.
- If the endDate is equal to or before the startData, an exception is thrown.
- If either the start or end timedate parameters are null, an exception is thrown.
- If no new GPS points are detected for the worker, an empty array is returned (i.e., Field Force Manager received no GPS information for the specified time range).
- The maximum date range that can be requested is 7 days. If the date range exceeds 7 days, a validation exception is thrown.
- The maximum number of GPS points returned is 500.
- If the difference between the GPS collection date (fix) on the mobile device and the date when the GPS point actually reached the Field Force Manager server, is more than 4 days, then that GPS point is not returned back in the web service response. This may happen if the GPS was collected on the mobile device (but not sent to Field Force Manager yet), and then device was turned off and then turned on after 4 days.
getStopsAndTravel
Description
The getStopsandTravel service method provides the ability to retrieve stop or travel segments for all workers for a specified time period. The method will return stop/travel segment where both the start and end datetime fall within the specified time range.
Method Signature
|
Ordinal |
DataType |
Can be Null? |
Description |
|---|---|---|---|
|
StartDate |
SvDate |
No |
The starting date and time for the requested range of results. The query returns changes including the specified start time. The time date format must be provided in the following format: yyyy-MM-dd HH:mm:ss.SSS For example, a start time of 1:50 PM on January 28th, 2004 would be 2004-01-28 13:50:00.000 |
|
EndDate |
SvDateHolder |
No |
Ending date for the range of results. The query returns changes up to BUT NOT including the specified end time. The time date format must be provided as: yyyy-MM-dd HH:mm:ss.SSS |
|
Return Result |
SvStopTravel |
No | An array of SvStopTravel. |
SvStopTravel
|
Field |
DataType |
Comments |
|---|---|---|
|
address |
SvAddress |
Address Object |
|
coordinate |
SvCoordinate |
Coordinate Object |
|
distance |
double |
The distance traveled in the segment. The distance is only valid for non-stopped segments |
|
endTime |
SvDate |
The date and time when the stop or travel segment ended |
|
jobReferenceNumber |
String |
The reference number of the corresponding job (if the stop occurred on a job) |
|
landmarkName |
String |
The name of the landmark if the stop occurred at a location |
|
startTime |
SvDate |
The date and time when the stop or travel segment started |
|
stoppedFlag |
Boolean |
Whether or not the segment was a stop. If true the segment is a stop, if false the segment is a travel segment. |
|
timecardName |
String |
The timecard status for a segment. The possible statuses are Logged Off, Logged In, On Duty, On Break |
|
workerName |
String |
The username of the worker who performed the stop or travel segment. |
getStopsAndTravelByWorker
Description
This service method returns stop and travel for the specified time range and specified worker. The method will return stop/travel segment where both the start and end datetime fall within the specified date time range.
Method Signature
|
Ordinal |
DataType |
Can be Null? |
Description |
|---|---|---|---|
|
StartDate |
SvDate |
No |
The starting date and time for the requested range of results. The query returns changes including the specified start time. The time date format must be provided in the following format: yyyy-MM-dd HH:mm:ss.SSS For example, a start time of 1:50 PM on January 28th, 2004 would be 2004-01-28 13:50:00.000 |
|
EndDate |
SvDateHolder |
No |
Ending date for the range of results. The query returns changes up to BUT NOT including the specified end time. The time date format must be provided as: yyyy-MM-dd HH:mm:ss.SSS |
|
WorkerName |
String |
No |
The username for a valid user in the application. |
|
Return Result |
SvStopTravel |
No |
An array of SvStopTravel. |
getStopsAndTravelByDivision
Description
This service method returns stops and travel for the specified time range and divisions(groups) The method will return stop/travel segment where both the start and end datetime fall within the specified date time range.
Method Signature
|
Ordinal |
DataType |
Can be Null? |
Description |
|---|---|---|---|
|
StartDate |
SvDate |
No |
The starting date and time for the requested range of results. The query returns changes including the specified start time. The time date format must be provided in the following format: yyyy-MM-dd HH:mm:ss.SSS For example, a start time of 1:50 PM on January 28th, 2004 would be 2004-01-28 13:50:00.000 |
|
EndDate |
SvDateHolder |
No |
Ending date for the range of results. The query returns changes up to BUT NOT including the specified end time. The time date format must be provided as: yyyy-MM-dd HH:mm:ss.SSS |
|
Divisions |
SvDivision[] |
Yes |
List of divisions for which the data will be retrieved. |
|
Return Result |
SvStopTravel |
No |
An array of SvStopTravel. |
getStops
Description
This method returns stops for the specified time range. The method will return stop segments where both the start and end datetime fall within the specified date time range.
Method Signature
|
Ordinal |
DataType |
Can be Null? |
Description |
|---|---|---|---|
|
StartDate |
SvDate |
No |
The starting date and time for the requested range of results. The query returns changes including the specified start time. The time date format must be provided in the following format: yyyy-MM-dd HH:mm:ss.SSS For example, a start time of 1:50 PM on January 28th, 2004 would be 2004-01-28 13:50:00.000 |
|
EndDate |
SvDateHolder |
No |
Ending date for the range of results. The query returns changes up to BUT NOT including the specified end time. The time date format must be provided as: yyyy-MM-dd HH:mm:ss.SSS |
|
Return Result |
SvStopTravel |
No | An array of SvStopTravel. |
getStopsByWorker
Description
This method returns stop for a specified time range for a specified worker. The method will return stop segments where both the start and end datetime fall within the specified date time range.
Method Signature
|
Ordinal |
DataType |
Can be Null? |
Description |
|---|---|---|---|
|
StartDate |
SvDate |
No |
The starting date and time for the requested range of results. The query returns changes including the specified start time. The time date format must be provided in the following format: yyyy-MM-dd HH:mm:ss.SSS For example, a start time of 1:50 PM on January 28th, 2004 would be 2004-01-28 13:50:00.000 |
|
EndDate |
SvDateHolder |
No |
Ending date for the range of results. The query returns changes up to BUT NOT including the specified end time. The time date format must be provided as: yyyy-MM-dd HH:mm:ss.SSS |
| WorkerName | String | No | The username for a valid user in the application. |
| Return Result | SvStopTravel | No | An array of SvStopTravel. |
getStopsByDivision
Description
This method returns stop for a specified time range and specified divisions (Groups). The method will return stop segments where both the start and end datetime fall within the specified date time range.
Method Signature
|
Ordinal |
DataType |
Can be Null? |
Description |
|---|---|---|---|
|
StartDate |
SvDate |
No |
The starting date and time for the requested range of results. The query returns changes including the specified start time. The time date format must be provided in the following format: yyyy-MM-dd HH:mm:ss.SSS For example, a start time of 1:50 PM on January 28th, 2004 would be 2004-01-28 13:50:00.000 |
|
EndDate |
SvDateHolder |
No |
Ending date for the range of results. The query returns changes up to BUT NOT including the specified end time. The time date format must be provided as: yyyy-MM-dd HH:mm:ss.SSS |
|
Divisions |
SvDivision[] |
Yes |
List of divisions for which the data will be retrieved. |
|
Return Result |
SvStopTravel |
No |
An array of SvStopTravel. |
getTravel
Description
This method returns travel points for a specified time range. The method will return travel segments where both the start and end datetime fall within the specified date time range.
Method Signature
|
Ordinal |
DataType |
Can be Null? |
Description |
|---|---|---|---|
|
StartDate |
SvDate |
No |
The starting date and time for the requested range of results. The query returns changes including the specified start time. The time date format must be provided in the following format: yyyy-MM-dd HH:mm:ss.SSS For example, a start time of 1:50 PM on January 28th, 2004 would be 2004-01-28 13:50:00.000 |
|
EndDate |
SvDateHolder |
No |
Ending date for the range of results. The query returns changes up to BUT NOT including the specified end time. The time date format must be provided as: yyyy-MM-dd HH:mm:ss.SSS |
|
Return Result |
SvStopTravel |
No |
An array of SvStopTravel. |
getTravelByWorker
Description
This method returns travel points for a specified time range for a specified worker. The method will return travel segments where both the start and end datetime fall within the specified date time range.
Method Signature
|
Ordinal |
DataType |
Can be Null? |
Description |
|---|---|---|---|
|
StartDate |
SvDate |
No |
The starting date and time for the requested range of results. The query returns changes including the specified start time. The time date format must be provided in the following format: yyyy-MM-dd HH:mm:ss.SSS For example, a start time of 1:50 PM on January 28th, 2004 would be 2004-01-28 13:50:00.000 |
|
EndDate |
SvDateHolder |
No |
Ending date for the range of results. The query returns changes up to BUT NOT including the specified end time. The time date format must be provided as: yyyy-MM-dd HH:mm:ss.SSS |
|
WorkerName |
String |
No |
The username for a valid user in the application. |
|
Return Result |
SvStopTravel |
No |
An array of SvStopTravel. |
getTravelByDivision
Description
This method returns travel points for a specified time range for specified divisions (Groups). The method will return travel segments where both the start and end datetime fall within the specified date time range.
Method Signature
|
Ordinal |
DataType |
Can be Null? |
Description |
|---|---|---|---|
|
StartDate |
SvDate |
No |
The starting date and time for the requested range of results. The query returns changes including the specified start time. The time date format must be provided in the following format: yyyy-MM-dd HH:mm:ss.SSS For example, a start time of 1:50 PM on January 28th, 2004 would be 2004-01-28 13:50:00.000 |
|
EndDate |
SvDateHolder |
No |
Ending date for the range of results. The query returns changes up to BUT NOT including the specified end time. The time date format must be provided as: yyyy-MM-dd HH:mm:ss.SSS |
|
Divisions |
SvDivision[] |
Yes |
List of divisions for which the data will be retrieved. |
|
Return Result |
SvStopTravel |
No |
An array of SvStopTravel. |
submitGps
(SvGpsPosition[] points)
Description
The submitGps method provides the ability to send gps points to the Field Force Manager system. Up to a maximum of 1000 gps points can be submitted in a single call. The points can belong to different users but all users must belong to the same company. In order for the gps points to be accepted for a user, that user must be linked to a device. The caller of the submitGps service must also call the submitUserAction web service and change the user status to logged in (this is required to create stop/travel segments for the submitted GPS points).
Method Signature
|
Ordinal |
DataType |
Can be Null? |
Description |
|---|---|---|---|
|
points |
SvGpsPosition[] |
No |
Set of gps points that will be added to Field Force Manager. |
|
Return Result |
SvResult |
No |
An array of SvResult result objects that indicate if the operation was successful. There is one SvResult object for each input SvGpsPosition object. |
Error Messages (on the SvResult object)
“The input array for gps points is null.” – thrown if input array is null.
“Only 1000 points can be processed in a single request. Additional points were ignored.” – Returned when more than 1000 points are submitted in a single call.
“A worker with the following username was not found: <workerName>” – Returned if the workerName in the SvGpsPosition object cannot be found.
“A device could not be found for the worker with username:: <workerName>” – Returned if the worker is not associated with a device in the Field Force Manager system.
“The worker name is required.” – Returned if the workerName in the SvGpsPosition object is empty.
“The timestamp when the gps point was collected must be supplied.” – Returned if the timestamp in the SvGpsPosition object is empty.
“The position coordinate must be either „DEGREES‟ or „RADIANS” – Returned if the positionCoordinateSystem field of the SvGpsPosition object is not set to an acceptable value. If nothing is specified, Radians is used.