Real-Time XML Data Feed

Understanding Our Near Real-Time Data Feeds That Track Data Received From Mobile Devices


Data Feed Overview

Verizon Connect provides near real-time data feeds for tracking data received from mobile devices.

Each customer has a secure HTTP data feed for their own assets, from which each authorized user can access the appropriate data. Think of these data feeds as streams of live data that you can pull down as XML or JSON using the HTTP protocol (secured with SSL).

We process incoming data and queue it to a live feed in near real-time. The user of such a feed can repeatedly call the HTTP endpoint and request the data in a sequential stream that reflects the order in which Verizon Connect received it.

Receiving Data From the Queue

Upon requesting data from the feed, the most recent messages from the queue are returned as either an XML document or as JSON, with an upper limit of 1000 messages returned per request. If more messages are available in the queue, the next request returns them (again, up to 1000).

Slow Readers

If the queue is not retrieved from for some time, or if it is not consumed quickly enough, the queue grows on the Verizon Connect side and is subject to throttling by the system.

Note that if the queue grows too large, it must be truncated. Truncated data is unrecoverable. If your queue is truncated, no additional data is stored until you reconnect your consumer.

Message Format

When you retrieve messages, by default the response is returned as XML. However, you can also retrieve messages as JSON. Both options are described below.

Default XML Message Format

The default form of the XML response for a unit message is as follows:



<?xml version="1.0" encoding="UTF-8"?>
<DataFeedReport>
<UnitMessage Latitude="30.401656" Longitude="-97.721615" SpeedMph="15"
IgnitionOn="true" VehicleTag="ABC1234" Time="2014-09-15T13:31:40" Heading="47"
RSSI="1" StreetNo="3110" StreetName="Esperanza Crossing" City="Austin"
Region="Texas" PostCode="78758" UnitId="35784" SpeedLimitMph="20"
OdometerMiles="25003" SerialNumber="1:TSBB02001521" />
<UnitMessage ... />
<UnitMessage ... />
</DataFeedReport>


Each message attribute represents a single datapoint from a single vehicle. Each unit reports multiple datapoints over time. A single HTTPS response might have multiple messages from multiple vehicles.

Verizon Connect sends messages in the XML document in the same order that it receives them from vehicles. This means that messages in the XML document might not be in strict chronological order, as vehicles being out of coverage can delay messages.

The fields within a single message are configurable per feed. Configuration of a feed is accomplished in conjunction with Verizon Connect to customize your feed as appropriate.

JSON Message Format

Optionally, you can retrieve messages as JSON by appending mode=json to the query string. In response, you receive a results array that contains JSON objects that represent individual messages in the feed. The fields within a single message are configurable per feed. Contact your account manager for assistance.

Example request:


https://integration.telogis.com/XmlDataFeed/reports.aspx?
token=5390e277-46ef-6b62-259e-897eed04dca7
&feed=topic-customer_feed
&mode=json

Example response:

{

    "results": [

        {

            "DriverName": "Steve MacDougal",

            "Latitude": 42.81539293023306,

            "Longitude": -83.09957433340396,

            "Time": "2016-06-03T20:09:31"

        },

        {

            "DriverName": "",

            "Latitude": 32.54256531849893,

            "Longitude": -92.62446523454578,

            "Time": "2016-06-03T20:09:31"

        },

        {

            "DriverName": "Booth Jones",

            "Latitude": 35.15036330523273,

            "Longitude": -80.9680066089634,

            "Time": "2016-06-03T20:09:31"

        },

        {

            "DriverName": "Jeremy Smith",

            "Latitude": 42.25457651940445,

            "Longitude": -84.48970702229184,

            "Time": "2016-06-03T20:09:30"

        },

        {

            "DriverName": "Bryan James",

            "Latitude": 29.71659777859435,

            "Longitude": -98.10341928025599,

            "Time": "2016-06-03T20:09:30"

        }

    ]

}

 

Authentication

To sign in to a data feed server, the client must retrieve an authentication token from the server. To achieve this, perform an HTTPS POST request to the following URL with a JSON body:

URL:

https://.api.telogis.com/rest/login/

Body:

{

    "username": "<customer>:<user>",

    "password": "<password>"

}

 

Example request:

To authenticate as 'acme:main' with password 'secret', you would make the following request to https://acme.api.telogis.com/rest/login/:

Request body:

{

    "username": "acme:main",

    "password": "secret"

}

 

Example response:

The response to this request is a JSON string:

Response body:

{

    "token":"00112233445566778899aabbccddeeff",

    "customerName":"acme",

    "username":"main"

}

 

The value of the token field is an authentication token, which is then used in the actual report request, as explained in the next section.

Client Report Request

Once the handshake process has been completed, you can begin requesting reports from the DataFeed server. Requests can be made in one of two modes:

  • Acknowledgement Mode (recommended): In acknowledgement mode, when you send a report request to the DataFeed server, it responds with a report containing the requested messages. The report then remains on the server until it receives an acknowledgement that the last sent report was successfully received. Until then, the same report is sent for all subsequent report requests. Once an acknowledgement is received, the next report request contains the next set of messages.
  • Classic Mode: In classic mode, when you send a report request to the DataFeed server, it also responds with a report containing the requested messages. However, the report is then removed from the DataFeed server. The next time you make a request, a new report is sent that contains the next set of messages. Note that if the report is somehow lost in transit from the DataFeed server, there is no way to recover it. If this is a concern, then we recommend using acknowledgement mode instead.

The process for requesting reports depends on the mode you select. If you are not sure which mode best fits your needs, contact Verizon Connect for assistance.

Note that when requesting reports, you cannot use both modes simultaneously. You must select one mode or the other.

Acknowledgement Mode

The report fetch process in acknowledgement mode requires the following steps:

  1. Send a report request to ackreports.aspx.
  2. After receiving the report, send an acknowledgement to ack.aspx to verify the report has been received.
  3. Repeat steps 1 and 2 to continue the report fetch process.

Note that if you are fetching in acknowledgement mode and plan to switch your message format from XML to JSON or vice versa, make sure that you have sent the last acknowledgement (step 2) before changing message formats.

Step 1: Send a report request

Send a report request to ackreports.aspx with the following arguments:

  • token=[Authentication Token]
  • &feed=[Name of desired feed]

Example request:


https://integration.telogis.com/XmlDataFeed/ackreports.aspx?
token=5390e277-46ef-6b62-259e-897eed04dca7
&feed=topic-customer_feed


Example response:

This call returns a single report containing multiple messages in the message format you have selected (XML or JSON).

  • If any messages exist on the feed, then the root node of the XML report contains an ID attribute (a GUID). This value is used in a later step to acknowledge that the report was received. Note that if you request the message as JSON, the ID is included as an object in the response.
  • If no messages exist on the feed, then the report is empty. In this case, the ID of the root node in the report is set to noresults.
  • If fewer than 1000 messages exist on the feed, then the report includes all of those messages.
  • If more than 1000 messages exist on the feed, then the report only includes approximately 1000 messages.

Step 2: Send an acknowledgeemnt

After receiving the report, send an acknowledgement to ack.aspx to verify the report has been received. The request should include the following arguments:

  • id=[ID from the root node of the last report received]
  • token=[Authentication Token]
  • &feed=[Name of desired feed]

Example request:


https://integration.telogis.com/XmlDataFeed/ack.aspx?
id=eb8fab4e-ae8b-4634-932f5c0e71e1
&token=5390e277-46ef-6b62-259e-897eed04dca7
&feed=topic-customer_feed


Note that sending an acknowledgement to ack.aspx is not required if the last report you received was empty. The ID of empty reports is set to noresults instead of a GUID.

Example response:

This call returns an HTTP 200 response if the DataFeed server successfully receives the request. The body of the response contains a set of attributes that indicate whether the acknowledgement was successfully processed, or if there was a problem:

Attribute Value Description
acked
  • true
  • false
If set to true, then the acknowledgement was successfully processed. If set to false, then there was a problem processing the request.
message
  • ACK succeeded
  • No data available to ACK
  • ACK [GUID] does not match
  • expectedId
Describes the status of the acknowledgement.
statusCode
  • 0
  • 1
  • 2
A code that indicates the status of the acknowledgement:
  • 0 - The acknowledgement was successfully processed. The next report request sent to ackreports.aspx results in a new set of messages.
  • 1 - There is not a report on the server waiting for an acknowledgement.
  • 2 - The acknowledgement ID submitted in the request does not match the ID from the root node of the last report sent. In this case, the expectedId is returned in the response.
expectedId
  • GUID
The ID of the report that still requires an acknowledgement. Only returned if statusCode equals 2.


Response body examples in XML for each statusCode:


<Result
acked="true"
message="ACK Succeeded"
statusCode="0"
/>


<Result
acked="false"
message="No data available to ACK"
statusCode="1"
/>


<Result
acked="false"
message="ACK abcdef10-1234-567a-bcde-f10123456789 does not match expectedId"
statusCode="2"
expectedId="eb8fab4e-ae8b-4634-932f5c0e71e1"
/>

Step 3: Repeat steps 1 and 2

Repeat steps 1 and 2 to continue the process of requesting and acknowledging the receipt of reports.

Classic Mode

In classic mode the report fetch process requires that you send requests to reports.aspx with the following arguments:

  • token=[Authentication Token]
  • &feed=[Name of desired feed]

Example request:


https://integration.telogis.com/XmlDataFeed/reports.aspx?
token=5390e277-46ef-6b62-259e-897eed04dca7
&feed=topic-customer_feed


Example response:

This call returns a single report containing multiple messages in the message format you have configured (XML or JSON).

  • If fewer than 1000 messages exist on the feed, then the report includes all of those messages.
  • If more than 1000 messages exist on the feed, then the report only includes approximately 1000 messages.
  • If no messages exist on the feed, then the report is empty.

Request Configuration via Query String

You can configure your report request with the following optional query string parameters. You can add multiple parameters to a request if needed. Note that these configuration options do not apply if you request your message as JSON.

Example 1: Store XML data in child elements instead of attributes

The default message format of the XML document stores data within attributes. You can configure the format to store data in child elements instead by passing the element_mode=true parameter via the request query string as shown below.


https://integration.telogis.com/XmlDataFeed/reports.aspx?
token=5390e277-46ef-6b62-259e-897eed04dca7
&feed=topic-customer_feed
&element_mode=true

Example 1 response:

This call returns an XML document with message data stored in child elements instead of attributes:



<DataFeedReport>
<UnitMessage>
<Latitude>30.401656</Latitude>
<Longitude>-97.721615</Longitude>
<SpeedMph>15</SpeedMph>
<IgnitionOn>true</IgnitionOn>
<VehicleTag>ABC1234</VehicleTag>
<Time>2014-09-15T13:31:40</Time>
<Heading>47</Heading>
<RSSI>1</RSSI>
<StreetNo>3110</StreetNo>
<StreetName>Esperanza Crossing</StreetName>
<City>Austin</City>
<Region>Texas</Region>
<PostCode>78758</PostCode>
<UnitId>35784</UnitId>
<SpeedLimitMph>20</SpeedLimitMph>
<OdometerMiles>25003</OdometerMiles>
<SerialNumber>1:TSBB02001521</SerialNumber>
</UnitMessage>
<UnitMessage>
...
</UnitMessage>
</DataFeedReport>



Example 2: Change the default message tag name

You can configure the default tag name of the XML messages by passing the message_path=value parameter via the request query string as shown below.


https://integration.telogis.com/XmlDataFeed/reports.aspx?
token=5390e277-46ef-6b62-259e-897eed04dca7
&feed=topic-customer_feed
&message_path=CustomMessageName


Example 2 response:

This call returns an XML document in which the default message tag is renamed CustomMessageName:



<DataFeedReport>
<CustomMessageName Latitude="30.401656" Longitude="-97.721615" SpeedMph="15"
IgnitionOn="true" VehicleTag="ABC1234" Time="2014-09-15T13:31:40" Heading="47"
RSSI="1" StreetNo="3110" StreetName="Esperanza Crossing" City="Austin"
Region="Texas" PostCode="78758" UnitId="35784" SpeedLimitMph="20"
OdometerMiles="25003" SerialNumber="1:TSBB02001521" />
<CustomMessageName ... />
<CustomMessageName ... />
</DataFeedReport>



Example 3: Add an XML namespace

You can add an XML namespace to the root DataFeedReport element by passing the namespace=value parameter via the request query string as shown below.


https://integration.telogis.com/XmlDataFeed/reports.aspx?
token=5390e277-46ef-6b62-259e-897eed04dca7
&feed=topic-customer_feed
&namespace=MyNamespace


Example 3 response:

This call returns an XML document in which the DataFeedReport tag includes an xmlns attribute, which defines your namespace:



<DataFeedReport xmlns="MyNamespace">
<UnitMessage ... />
<UnitMessage ... />
</DataFeedReport>
 

Example 4: Assign a prefix and define an XML namespace

You can assign a prefix and define an XML namespace by passing the namespace=NamespaceValue_prefix=PrefixValue parameter via the request query string as shown below.


https://integration.telogis.com/XmlDataFeed/reports.aspx?
token=5390e277-46ef-6b62-259e-897eed04dca7
&feed=topic-customer_feed
&namespace=MyNamespace_prefix=MyPrefix


Example 4 response:

This call returns an XML document in which the DataFeedReport tag includes an xmlns attribute and prefix, and the prefix is added to each element:



<MyPrefix:DataFeedReport xmlns:MyPrefix="MyNamespace">
<MyPrefix:UnitMessage Latitude="30.401656" Longitude="-97.721615" SpeedMph="15"
IgnitionOn="true" VehicleTag="ABC1234" Time="2014-09-15T13:31:40" Heading="47"
RSSI="1" StreetNo="3110" StreetName="Esperanza Crossing" City="Austin"
Region="Texas" PostCode="78758" UnitId="35784" SpeedLimitMph="20"
OdometerMiles="25003" SerialNumber="1:TSBB02001521" />
<MyPrefix:UnitMessage ... />
<MyPrefix:UnitMessage ... />
</DataFeedReport>


Example 5: Change the default root element name

You can change the default name of the root DataFeedReport element by passing the root_element=value parameter via the request query string as shown below.


https://integration.telogis.com/XmlDataFeed/reports.aspx?
token=5390e277-46ef-6b62-259e-897eed04dca7
&feed=topic-customer_feed
&root_element=MyRootElement


Example 5 response:

This call returns an XML document in which the DataFeedReport tag is renamed MyRootElement.



<MyRootElement>
<UnitMessage ... />
<UnitMessage ... />
</MyRootElement>



Data Feed Message Types

The data feed has the following message types available:

  • Unit Message - Unit messages include data and diagnostics reported directly from individual vehicles.
  • Insight Alert Message - InSight Alerts™ notify you, in real time, when a vehicle does something special or unexpected.
  • Jobs Form Updated Message - Jobs Form Updated messages notify you, in real time, the moment that a jobs form is created or updated, so that you can process it as soon as possible.
  • Driver Status Change Message - Driver Status Change messages notify you of changes made to the driver's status, such as going on and off duty.

Contact your account manager to find out which message fields your account can access using the Real-Time Data Feed.