Voltswitch API

The Voltswitch JSON API is a way for our customers to query for their location data in a machine-processable format. You can access realtime data, historical positions of your vehicles or even data preprocessed as trips with corresponding metadata.

The API is accessible at https://api.voltswitchgps.com/api/v1

The login credentials are the same as those for the platform. Basic authentication over HTTPS is used.

Demo account
Login: api_voltswitch
Password: apipass

The following endpoints are available:

1) Get list of available groups

List of groups to which you have permissions.

[{"Code":"VOLT","Name":"Voltswitch GPS"}]

2) Get list of all vehicles in specific group

https://api.voltswitchgps.com/api/v1/vehicles/group/<group code>

i.e. https://api.voltswitchgps.com/api/v1/vehicles/group/VOLT

Returns a list of vehicles, their name, registration plate, battery status (0 if the battery is not in use), current speed, GPS position and last response time (UTC).

[
   {
      "Code":"ASEBOFURAD",
      "GroupCode":"VOLT",
      "Name":"352544073975253",
      "SPZ":"",
      "BatteryPercentage":0,
      "Speed":1.0,
      "LastPosition":{
         "Latitude":"25.767524",
         "Longitude":"-80.193646"
      },
      "LastPositionTimestamp":"2018-03-23T00:48:14"
   },
   {
      "Code":"NALICOSAPA",
      "GroupCode":"VOLT",
      "Name":"Freightliner",
      "SPZ":"",
      "BatteryPercentage":0,
      "Speed":0.0,
      "LastPosition":{
         "Latitude":"27.873273",
         "Longitude":"-81.020683"
      },
      "LastPositionTimestamp":"2018-04-05T21:32:04Z"
   },
   ...
]

3) Get realtime information of specific vehicle

https://api.voltswitchgps.com/api/v1/vehicle/<vehicle code>

i.e. https://api.voltswitchgps.com/api/v1/vehicle/NALICOSAPA

Returns the realtime information about a vehicle.

{
 "Code": "NALICOSAPA",
 "GroupCode": "VOLT",
 "Name": "Freightliner",
 "SPZ": "",
 "BatteryPercentage": 10,
 "Speed": 4,
 "LastPosition": {
      "Latitude":"27.873273",
      "Longitude":"-81.020683"
 },
 "LastPositionTimestamp": "2018-02-09T15:27:51Z"
}

4) Get history of positions of specific vehicle

https://api.voltswitchgps.com/api/v1/vehicles/history/<coma separated vehicle codes>?from=<date+time from>&to=<date+time to>

eg. https://api.voltswitchgps.com/api/v1/vehicles/history/NALICOSAPA,ASEBOFURAD?from=2017-07-20T00:00&to=2017-07-21T00:00

Returns list of historical positions in specified time interval for selected vehicles.

[
   {
      "Name":"Freightliner",
      "VehicleCode":"NALICOSAPA",
      "From":"2017-07-19T22:00:00Z",
      "To":"2017-07-20T22:00:00Z",
      "Positions":[
         {
            "Lat":"28.321751",
            "Lng":"-80.715108",
            "Time":"2017-07-19T22:00:13Z",
            "Speed":82.0
         },
         {
            "Lat":"28.321395",
            "Lng":"-80.714849",
            "Time":"2017-07-19T22:00:16Z",
            "Speed":53.0
         },
         {
            "Lat":"28.321023",
            "Lng":"-80.714532",
            "Time":"2017-07-19T22:00:20Z",
            "Speed":53.0
         },
      ...
      ]
   }
]

5) Get history of trips

https://api.voltswitchgps.com/api/v1/vehicle/<vehicle code>/trips?from=<date+time from>&to=<date+time to>

i.e. https://api.voltswitchgps.com/api/v1/vehicle/NALICOSAPA/trips?from=2017-07-20T00:00&to=2017-07-21T00:00

Returns history of trips with metadata for selected vehicle with start time between from/to dates.

[
   {
      "AverageSpeed":63.0,
      "MaxSpeed":99.0,
      "TripType":false,
      "StartTime":"2017-07-19T23:40:55",
      "FinishTime":"2017-07-20T01:45:42",
      "StartPosition":{
         "Latitude":"28.05401",
         "Longitude":"-80.589111"
      },
      "FinishPosition":{
         "Latitude":"27.0705",
         "Longitude":"-80.482134"
      },
      "StartAddress":"I-95, Cocoa, FL 32926, US",
      "FinishAddress":"I-95, St. Augustine, FL 32084, US",
      "TripLength":"02:04",
      "TripWaitingTime":"00:00",
      "TotalDistance":131.159
   },
   {
      "AverageSpeed":66.0,
      "MaxSpeed":99.0,
      "TripType":false,
      "StartTime":"2017-07-20T02:04:49",
      "FinishTime":"2017-07-20T04:40:16",
      "StartPosition":{
         "Latitude":"27.0705",
         "Longitude":"-80.482134"
      },
      "FinishPosition":{
         "Latitude":"25.769416",
         "Longitude":"-80.239058"
      },
      "StartAddress":"Florida's Turnpike, Lake Worth, FL 33467, US",
      "FinishAddress":"Ronald Reagan Turnpike, Miami, FL 33182, US",
      "TripLength":"02:35",
      "TripWaitingTime":"00:00",
      "TotalDistance":170.498
   },
   ...
]

6) Get engine relay state

https://api.voltswitchgps.com/api/v1/vehicle//getEngineRelayState

i.e. https://api.voltswitchgps.com/api/v1/vehicle/IJIZAPESUJ/getEngineRelayState

Returns current engine relay state.

{
     "RelayState": 0,
     "LastEventTimestamp": "2018-04-23T16:17:31.0621104+02:00"
}

RelayState values:

0 - initial state
1 - lock engine request sent to device, not confirmed
2 - lock engine request sent to device, confirmed by system
3 - unlock engine request sent to device, unconfirmed
4 - unlock engine request sent to device and confirmed by system
5 - unable to lock engine, request denied or delayed by the device

7) Set engine relay state

https://api.voltswitchgps.com/api/v1/vehicle//setEngineRelayState/

i.e. https://api.voltswitchgps.com/api/v1/vehicle/IJIZAPESUJ/setEngineRelayState/off sends lock engine message to the device

or

https://api.voltswitchgps.com/api/v1/vehicle/IJIZAPESUJ/setEngineRelayState/on sends unlock engine message to the device

Returns current engine relay state.

{
     "RelayState": 1,
     "LastEventTimestamp": "2018-04-23T16:17:31.0621104+02:00"
}

Note: use getEnginerRelayState to check if lock or unlock message was received by the device

8) Reset engine relay state

https://api.voltswitchgps.com/api/v1/vehicle//resetEngineRelayState

i.e. https://api.voltswitchgps.com/api/v1/vehicle/IJIZAPESUJ/resetEngineRelayState - resets vehicle state on the platform to initial state, no command is sent to the device

Caution: May cause discrepancy between the state shown on platform and the actual state of the vehicle! Use only if you are sure that engine is unlocked but engine relay state is incorrect.

Returns current engine relay state.

{
     "RelayState": 0,
     "LastEventTimestamp": "2018-04-23T16:17:31.0621104+02:00"
}