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 StreetSmart. 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

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., StreetSmart 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 StreetSmart 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 StreetSmart yet), and then 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 StreetSmart, 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 StreetSmart. 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

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., StreetSmart 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 StreetSmart 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 StreetSmart yet), and then 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 StreetSmart, 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 StreetSmart. 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

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., StreetSmart 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 StreetSmart 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 StreetSmart 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

SvStopTravel

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

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

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

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

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

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

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

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

submitGps

(SvGpsPosition[] points)

Description

The submitGps method provides the ability to send gps points to the StreetSmart 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

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 StreetSmart 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.

Back to top