Real-Time XML Data Feed

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

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.

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.

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.

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

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:

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

Step 2: Send an acknowledgement

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

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:

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.

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

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