Document toolboxDocument toolbox

Update Travel Status SOAP API

Owned by Jason Andrew
Sept 17, 2024
2 min read

On This Page:

Related Pages:

The sp:EmpChangeTravelStatus2Request API method can be used to update the travel status of an operative.

Description

An operative can have a travel status with values:

Moving

The vehicle has its engine running and is in a different location between move events.

Stationary

The vehicle has its engine running but it isn’t moving, i.e. it’s at the same location for two or more events.

Stopped

The vehicle’s engine isn’t running, and it’s location isn’t changing. Additional information in the form of a location type - the type of location that the vehicle is stopped near (e.g. a parts depot) - may also be available.

Cancelled

Returns Job Cancelled status 

Unknown

The vehicle was expected to send a new event because the sample time has elapsed since the previous move (or stationary) event but one hasn’t been received. (This could be because the vehicle is ‘out of range’.)

The travel status is set by calling the sp:EmpChangeTravelStatus2Request API method.

When the travel status is Stopped, additional information in the form of a location type - the type of location that the vehicle is stopped near (GeoFenceLocType) - can be supplied:

By default, ServiceGPS is configured to send one of the following two character strings for the location type (GeoFenceLocType), but they are configurable:

“HO”     Home

“VD”     Vehicle Depot

“PL”     Parts Location

“TO”     Team Office

“CO”     Company Office

“CS”     Customer Site

“NG”     No Go

A location name can also be supplied if one has been defined in ServiceGPS for the location (geofence).

This can used for different purposes, depending the value of the type. Where the location type (GeoFenceLocType, above) is Parts Location, for example, the location name could be the name of the building where the parts are located, e.g. “Stockport Depot”.

#define SP_LatitudeMin      -90.0       /* 90°S                        */

#define SP_LatitudeMax      +90.0       /* 90°N                        */

#define SP_LongitudeMin     -180.0      /* 180°W                       */

#define SP_LongitudeMax     +180.0      /* 180°E                       */

Definition

The definition of this API is:

 Click here to expand...

Web Service

Type

Description

Req?

Val?

<sp:EmpChangeTravelStatus2Request>






<empID>?</empID>

EmpID

The operative’s ID

Yes

Yes


<newTravelStatus>?</newTravelStatus>






<timeStamp>?</timeStamp>






<latitude>?</latitude>


Latitude (see 2.5) of the current position of the operative




<longitude>?</longitude>


Longitude (see 2.5) of the current position of the operative




<address>







<address1>?</address1>







<address2>?</address2>







<address3>?</address3>







<address4>?</address4>







<country>?</country>







<postcode>?</postcode>

Postcode



Yes


</address>






<geoFence>







<type>?</type>







<name>?</name>






</geoFence>






<disStatus>?</disStatus>DisStatus

An optional parameter that represents the dispatch status associated with the operative when the travel change request is made.

NoYes

</sp:EmpChangeTravelStatus2Request>





The Timestamp field is the timestamp from the GPS device in the vehicle itself and can be operative-local or UTC, according to the setting of EmpChangeTravelStatus: Time Zone Type (tz_opts ).

Return Structure

The API returns the standard return structure.

Return Codes

In addition to the Standard Return Codes, the possible Return Codes from this API are:

 Click here to expand...
  • SP_OK (0)
  • SP_EMPID_INVALID (5)
  • SP_STATUS_NO_CHANGE (86)
  • SP_EMPID_NOT_SUPPLIED (215)
  • SP_DATETIME_INVALID (538)
  • SP_EMP_TRAVEL_STATUS_INVALID (568)
  • SP_OK_EMP_TRAVEL_STATUS_OFF (569)
  • SP_LATITUDE_INVALID (608)
  • SP_LONGITUDE_INVALID (609)
  • SP_LOCADD1_INVALID (610)
  • SP_LOCADD2_INVALID (611)
  • SP_LOCADD3_INVALID (612)
  • SP_LOCADD4_INVALID (613)
  • SP_LOCPOSTCODE_INVALID (614)
  • SP_COUNTRY_INVALID (615)
  • SP_GEOFENCELOCTYPE_INVALID (616)
  • SP_GEOFENCELOCTYPE_NOT_SUPPLIED (617)
  • SP_GEOFENCELOCNAME_INVALID (618)
  • SP_GEOFENCE_DOES_NOT_EXIST (619)
  • SP_DATETIME_NOT_SUPPLIED (620)