GPS Push Service

The GPS Push Service enables customers and partners to receive GPS data in near real-time when a new plot is reported to Reveal from the vehicle tracking unit.

Note: The current version of the GPS Push service does not support devices tracking Non-Powered Assets.  No information will return regarding Non-Powered Assets within the push method.

GPS Push Service Configuration Requirements

To configure an account with the GPS Push Service, the following information would be required to be shared with Verizon Connect’s Customer Support team to create the pushed data connection.

Endpoint

An exposed endpoint URL from the customer or 3rd party where the pushed data would be sent by Reveal.

     The URL must be HTTPS compliant as we require an SSL secure socket layer endpoint.

     Reveal will not allow for certificate warning.

     Endpoints should be hosted on Port 443.

Authentication

The endpoint will need to support Basic authentication.

A username and password will be provided to Verizon Connect to use when accessing the endpoint.

 

Content - Type

The endpoint must accept an application/JSON

POST request.

Reveal Credentials

No, Reveal REST integration credentials or an Integration Manager APP is required to use the GPS Push Service.

 

 

GPS Push Service Message Delivery Configuration and Retrial

The following are the details of the message delivery, retrial configuration, and circuit breaking information which is vital for any subscriber to set up a web API integration to receive post and troubleshoot the system.

Message Delivery Configuration

When a message is sent and is not received by the endpoint, the GPS push service will attempt to retry the same message for maximum 2 retries in an interval of 1 minute each, before the message is discarded by GPS Push service.  

Acceptable Response

 

The only successful response is a 200.

 

The response should be received within 3 - 5 seconds.

 

All other response codes will be treated as a failed delivery and eventually be discarded if the failures continue per the “message delivery configuration” above.

Circuit Breaking

If the user’s endpoint becomes unavailable and we receive 20 consecutive failures, we will suspend pushing more GPS plots for 15 minutes.

After 15 minutes, we will reconnect the service and begin sending GPS message again. If we receive 20 consecutive failures again we will repeat the suspension.

 

GPS Push Service Message

The GPS Push Service provides the following JSON message for each unique plot that is generated:

  "SequenceID": 234446,

  "UpdateUTC": "1588957835000,",

  "DeviceTimeZoneOffset": 2,

  "DeviceTimeZoneUseDST": true,

  "DisplayState": "Idle",

  "IsPrivate": false,

  "SpeedKmph": 85,

  "DirectionDegrees": 280,

  "Heading": "North",

  "DeltaDistanceKm": 0.354,

  "OdometerKm": 120045,

  "TotalEngineMinutes": 1380,

  "IdleTimeMinutes": 4,

  "DeltaTimeInSec": 251,

  "Latitude": -6.3752626,

  "Longitude": 53.2979679,

  "SensorBits": 65,

  "SensorValues": ["Boom Stow 1-ON","Boom Stow 2-OFF","Boom Stow 3-OFF","Boom Stow 4-OFF"]

{

  "Vehicle": {

             "Number": "V242342",

            "Name": "Truck2324",

            "VIN": "Z232SD43FAS",

            "ESN": 342434234

},

  "Address": {

           "AddressLine1": "Atrium Building, Blackthorn Road",

           "AddressLine2": "Sandyford Business Park",

           "Locality": "Dublin",

          "PostalCode": "D18 F5X2",

          "AdministrativeArea": "Dublin",

          "Country": "IRL"

          },

"Driver": {

    "DriverKeyFobID": 234423678,

    "DriverNumber": "D234",

    "DriverFirstName": "Tim",

    "DriverLastName": "Daruch"

               },

 

}

Message Fields

All GPS messages will include the following fields that will be either established within the Reveal account or dynamically driven based on the accumulated GPS data.

Field

 JSON Formatted Sample

Field Notes and Default Values

Vehicle

 Number

{  

"Vehicle": {                    

 "Number": "V242342",

The Vehicle Number called in the request will be returned within the response.

Vehicle Name

 "Name": "Truck2324",

The Vehicle Name as displayed within the Reveal account.

 

VIN

 "VIN": "1GCVKNEC2JZ305979", 

The VIN as displayed within the Reveal account.

 

ESN

 “ESN": 342434234,

   },  

ESN is used to uniquely identify a vehicle from another. It is a mandatory field for vehicle creation in Reveal.

Sequence ID

  "SequenceID" : 234446

The sequence identifier for individual plots.

In an occasion of temporary errors due to an outage of service, there is a possibility of receiving a duplicate plot in an attempt of retries. In which case, Sequence ID can be used as a unique identifier.

Note: This should be referenced to determine the order of plots and duplication, if any.

 

Update UTC

 "UpdateUTC": "2016-07-14T15:52:04",

The date and time stamp when the GPS plot were received.

Format: xxxx-xx-xxTxx:xx:xx

YEAR-MONTH-DAY T HOURS-MINUTES-SECONDS

Device Time Zone Offset

 "DeviceTimeZoneOffset": 2,

Device Time Zone Offset is the GPS device’s current time zone compared to UTC.

Device Time Zone Use DST

"DeviceTimeZoneUseDST": true,

If the Reveal account is set to acknowledge Daylight Savings Time, then this value will return as TRUE. 

Reveal accounts in the United States are automatically defaulted to True.

Display State

"DisplayState": "Idle",

Display State is the value used to describe the vehicle’s display state.  The following values will return to describe the state of the vehicle:

0: Coverage

1: Moving

2: Stop

3: Towing

4: Idle

5: Panic

6: Privacy

Is Private

"IsPrivate": false,

If the Reveal account is using the Privacy feature to enable drivers with the ability to not disclose their current location during non-business hours, the location information will not be returned within the vehicle’s response to the API and this flag will be set to TRUE. 


Note: When IsPrivate is TRUE neither the address nor coordinate details or speed details will be displayed to the subscriber.

Speed

"SpeedInKM": 85,

Values will be returned in kilometres per hour.

Direction

"DirectionDegrees": 280,

The direction is the degrees of the compass direction.

Heading

"Heading": "North",

The heading will include the following values to describe the vehicle’s current direction:

North

North East

East

South East

South

South West

West

North West

Unknown

Delta Distance

  "DeltaDistanceKm": 0.354,

 

Delta Distance is the distance accumulated between the previous GPS plot and the current referenced plot.

Defaults to “0” if no delta distance accumulated for the most recent GPS plot referenced.

OdometerKM

 "OdometerKm": 120045,

Odometer is the accumulated reading in kilometers for the associated vehicle provided in the plot.  This reading will reflect the current amount of logged kilometers relative to the requested UTC time stamp.

Total Engine Minutes

 "TotalEngineMinutes": 1380,     

Engine Minutes is accumulated across the lifetime of the device within the vehicle every time the vehicle has Ignition On plots.

Idle Time Minutes

 "IdleTimeMinutes": 4,

The total amount of time (in minutes) that the vehicle has been continuously idling.

Delta Time InSec

 "DeltaTimeInSec": 251,

Delta Time is the time between the previous GPS plot and the current referenced plot.

Defaults to NULL if no time accumulated for the most recent GPS plot referenced.

Address Components

"Address": {

 "AddressLine1":"AtriumBuilding, Blackthorn Road",

 "AddressLine2": "Sandyford Business Park",

 "Locality": "Dublin",

 "PostalCode": "D18 F5X2",

 "AdministrativeArea": "Dublin",

 "Country": "IRL"

 },

Address contains the global standards for address components:

Address Line 1 – location specific identification such as a house number

Address Line 2 – additional information to identify location such as an apartment number

Locality – city, town, etc.

Administrative Area – state, province, etc.

Postal Code

Country

Latitude

"Latitude": -6.3752626,

The Latitude coordinate associated with the GPS plot.

Longitude

"Longitude": 53.2979679,

The Longitude coordinate associated with the GPS plot.

Driver Key Fob ID

"Driver": {

   "KeyFobID": 234423678,

The Driver Key Fob ID is the hexadecimal value associated with the driver’s current key fob.  This value is supplied by the user within Reveal. 

Driver Number  

"DriverNumber": "D234",

Driver Number is the unique identifier for Drivers created within Reveal.

The value will default to NULL if no Driver is Assigned to the Vehicle at the time of the GPS plot that is referenced.  NULL will also be returned if the Driver record assigned at the time of the plot does not have a Driver Number associated with the record in Reveal. .

Driver First Name

"FirstName": "Tim",

The driver first name as shown within Reveal.

If there is no driver assignment within Reveal for the plot being returned then this field will be NULL.

Driver Last Name

"LastName": "Daruch"

           },

The driver last name as shown within Reveal.

If there is no driver assignment within Reveal for the plot being returned then this field will be NULL.

Sensor Bits

"SensorBits": 65,

A combined decimal value for all the sensor flags.

Sensor Values

"SensorValues": ["Boom Stow 1-ON","Boom Stow 2-OFF"]

}

Vehicles that have sensors will display the Sensor’s name if the GPS plot referenced has an active sensor ON.