The Real-time Aggregated Data – Segments API is available to enable integrated users to poll segment level information for a vehicle’s journeys and stops for a particular day.
Important concepts to understand prior to utilizing any of the available integration methods:
· Vehicle Segments API is offered as a RESTful web service
· Standard REST verbs are applied: GET
· Throughout this document, we will reference the unique identifier to be invoked for each of the main objects available. The unique identifiers used within this API method set include:
o Vehicle Number
o Driver Number
Note: The current version of the
Vehicle Segment Data API does not support devices tracking Non-Powered
Assets. No information will return regarding Non-Powered Assets within
any of the following API methods.
The returned response will be
restricted to the Reveal account's data plan. If the information being queried
is outside of the data plan, a "400 Bad Request error "response will
be returned.
For more details on your account's
data plan please reach out to Verizon Connect Customer Support
|
API Name |
Vehicle
– Segments API |
|
Endpoint |
https://fim.api.us.fleetmatics.com/rad |
|
Operation |
GET |
The GET Segment by Vehicle Number method is available for integrated users to retrieve only start and stop level information that a vehicle made for a particular day. This allows an integrated user to have information related to the journey and stop level information that would align with details shown in REVEAL reports.
Note:
· Vehicle Start is defined by an Ignition On event.
· Vehicle End is defined by an Ignition Off event.
The user must provide a valid Vehicle Number along with a Start Date and Time. The response will include the segments for a 24 hour period starting with the date and time value entered. The Start Date and Time must be within 365 days of the current date of the request being made.
It is possible that a segment start and end can cross the 24 hour period being called. In the event that the Segment is partially outside of the 24 hour window being queried the following will happen:
· If an ending segment event occurs within the 24 hour period queried, the related start segment event will appear within the response although it precedes the start time entered.
· If a starting segment event occurs within the 24 hour period queried, the start information will be displayed but there will be no ending segment details as it falls outside of the time window. In this case, the IsComplete flag will be set to false.
It is recommended that integrated users regularly calling the GET Segment by Vehicle Number periodically call the Customer Meta Data – Vehicle API for GET ALL VEHICLES to return a set of active Vehicle Numbers for the REVEAL account. Coding dynamically against the GET ALL VEHICLES method will ensure that all vehicles within an account are being requested and that vehicle numbers that do not exist in the REVEAL account do not accidentally get processed creating a 400 errors.
|
Operation
and Path |
GET
https://fim.api.us.fleetmatics.com/rad/v1/vehicles/<VehicleNumber>/segments?startdateutc=<0000-00-00T00:00:00>
HTTP/1.1 Notes regarding the Start Date and Time value: Start Date cannot be more than 365 days prior to the current date |
|
HOST |
fim.api.us.fleetmatics.com |
|
Accept |
application/json |
|
Authorization |
Atmosphere realm=http://atmosphere,atmosphere_app_id=<Integration Manager App ID>, Bearer <token>
Note: The Token API must be called in order to retrieve a valid token to provide to all subsequent calls. |
[
{
"Driver": {
"Number": "204",
"FirstName": "Cameron",
"LastName": "Potvin"
},
"Vehicle": {
"Number": "95000",
"Name": "FD 0095"
},
"Segments": [
{
"StartDateUtc": "2017-05-31T20:31:59",
"StartLocation": {
"Latitude": 33.008785,
"Longitude": -97.35084,
"AddressLine1": null,
"AddressLine2": null,
"Locality": null,
"AdministrativeArea": null,
"PostalCode": null,
"Country": "USA"
},
"StartLocationIsPrivate": false,
"EndLocation": {
"Latitude": 33.025673,
"Longitude": -97.271193,
"AddressLine1": "13200 Raceway Dr",
"AddressLine2": "",
"Locality": "Roanoke",
"AdministrativeArea": "TX",
"PostalCode": "76262",
"Country": "USA"
},
"EndDateUtc": "2017-06-01T00:42:38",
"EndLocationIsPrivate": false,
"IsComplete": true,
"DistanceKilometers": 25
},
]
The GET Segment by Driver Number method is available for integrated users to retrieve only start and stop level information that a vehicle made for a particular day. This allows an integrated user to have information related to the journey and stop level information that would align with details shown in REVEAL reports.
Note:
· Vehicle Start is defined by an Ignition On event
· Vehicle End is defined by an Ignition Off event
The user must provide a valid Driver Number along with a Start Date and Time. The response will include the segments for a 24 hour period starting with the date and time value entered. The Start Date and Time must be within 365 days of the current date of the request being made.
It is possible that a segment start and end can cross the 24 hour period being called. In the event that the Segment is partially outside of the 24 hour window being queried the following will happen:
· If an ending segment event occurs within the 24 hour period queried, the related start segment event will appear within the response although it precedes the start time entered.
· If a starting segment event occurs within the 24 hour period queried, the start information will be displayed but there will be no ending segment details as it falls outside of the time window. In this case, the IsComplete flag will be set to false.
The Driver Number selected must be assigned to a vehicle within REVEAL for the date selected in order to return segment data.
It is recommended that integrated users regularly calling the GET Segment by Driver Number periodically call the Customer Meta Data – Driver API for GET ALL DRIVERS to return a set of active Driver Numbers for the REVEAL account. Coding dynamically against the GET ALL DRIVERS method will ensure that all drivers within an account are being requested and that driver numbers that do not exist in the REVEAL account do not accidentally get processed creating a 400 errors.
|
Operation
and Path |
GET https://fim.api.us.fleetmatics.com/rad/v1/drivers/<DriverNumber>/segments?startdateutc=<0000-00-00T00:00:00>
HTTP/1.1 Notes regarding the Start Date and Time value: Start Date cannot be more than 365 days prior to the current date |
|
HOST |
fim.api.us.fleetmatics.com |
|
Accept |
application/json |
|
Authorization |
Atmosphere realm=http://atmosphere,atmosphere_app_id=<Integration Manager App ID>, Bearer <token>
Note: The Token API must be called in order to retrieve a valid token to provide to all subsequent calls. |
[
{
"Driver": {
"Number": "204",
"FirstName": "Cameron",
"LastName": "Potvin"
},
"Vehicle": {
"Number": "95000",
"Name": "FD 0095"
},
"Segments": [
{
"StartDateUtc": "2017-05-31T20:31:59",
"StartLocation": {
"Latitude": 33.008785,
"Longitude": -97.35084,
"AddressLine1": null,
"AddressLine2": null,
"Locality": null,
"AdministrativeArea": null,
"PostalCode": null,
"Country": "USA"
},
"StartLocationIsPrivate": false,
"EndLocation": {
"Latitude": 33.025673,
"Longitude": -97.271193,
"AddressLine1": "13200 Raceway Dr",
"AddressLine2": "",
"Locality": "Roanoke",
"AdministrativeArea": "TX",
"PostalCode": "76262",
"Country": "USA"
},
"EndDateUtc": "2017-06-01T00:42:38",
"EndLocationIsPrivate": false,
"IsComplete": true,
"DistanceKilometers": 25
},
{
"StartDateUtc": "2017-06-01T00:52:35",
"StartLocation": {
"Latitude": 33.025694,
"Longitude": -97.271129,
"AddressLine1": "13200 Raceway Dr",
"AddressLine2": "",
"Locality": "Roanoke",
"AdministrativeArea": "TX",
"PostalCode": "76262",
"Country": "USA"
},
"StartLocationIsPrivate": false,
"EndLocation": {
"Latitude": 33.012342,
"Longitude": -97.235008,
"AddressLine1": "860 TX-114 BUS",
"AddressLine2": "",
"Locality": "Roanoke",
"AdministrativeArea": "TX",
"PostalCode": "76262",
"Country": "USA"
},
"EndDateUtc": "2017-06-01T00:57:56",
"EndLocationIsPrivate": false,
"IsComplete": true,
"DistanceKilometers": 4
},
]
|
Field |
JSON Formatted Sample |
Field Notes and Default
Values |
|
Driver
Number |
"DriverNumber":
"218", |
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. |
|
First
Name |
"FirstName":
"Tim", |
The first name of the driver. |
|
Last Name |
"LastName":
"Daurch", |
The last name of the driver. |
|
Vehicle
Number |
[ { "Vehicle": { "Number":
"204", |
The Vehicle Number called in the
request will be returned within the response. |
|
Vehicle
Name |
"VehicleName":
"FD 0109", |
The Vehicle Name as displayed
within the REVEAL account. |
|
Segments |
"Segments": [ { |
The segments for a selected driver/vehicle
will be broken down within the segments section of the call. Each Segment will include the following
details: ·
Start Date UTC ·
Start Location o Latitude o Longitude o Address
Line 1 o Address
Line 2 o Locality o Administrative
Area o Postal
Code o Country o Start
Location Is Private flag ·
End Date UTC ·
End Location o Latitude o Longitude o Address
Line 1 o Address
Line 2 o Locality o Administrative
Area o Postal
Code o Country o Start
Location Is Private flag ·
Is Complete flag ·
Distance in Kilometers for the segment |
|
Start Date
UTC |
{ "StartDateUtc":
"2017-05-31T20:31:59", |
The date and time stamp when the
Ignition On start event occurred for the segment. Format: xxxx-xx-xxTxx:xx:xx YEAR-MONTH-DAY T
HOURS-MINUTES-SECONDS |
|
Start
Location |
"StartLocation":
{ "Latitude":
33.008785, "Longitude":
-97.35084, "AddressLine1":
null, "AddressLine2":
null, "Locality":
null, "AdministrativeArea":
null, "PostalCode":
null, "Country":
"USA" }, |
The location elements are
included for the start location: ·
Latitude ·
Longitude 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 |
|
Start
Location Is Private |
"StartLocationIsPrivate":
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.
|
|
End
Location |
"EndLocation":
{ "Latitude":
33.025673, "Longitude":
-97.271193, "AddressLine1":
"13200 Raceway Dr", "AddressLine2":
"", "Locality":
"Roanoke", "AdministrativeArea":
"TX", "PostalCode":
"76262", "Country":
"USA" }, |
The location elements are
included for the start location: ·
Latitude ·
Longitude 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 |
|
End Date
UTC |
"EndDateUtc":
"2017-06-01T00:42:38", |
The date and time stamp when the
Ignition Off end
event occurred for the segment. Format: xxxx-xx-xxTxx:xx:xx YEAR-MONTH-DAY T HOURS-MINUTES-SECONDS |
|
End
Location Is Private |
"EndLocationIsPrivate":
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.
|
|
Is
Complete |
"IsComplete":
true, |
It is possible that a segment start and end can cross the 24 hour period being
called. In the event that the Segment
is partially outside of the 24 hour window being
queried the following will happen: ·
If an ending segment event occurs within the 24 hour period queried, the related start segment event
will appear within the response although it precedes the start time entered. ·
If a starting segment event occurs within the 24 hour period queried, the start information will be
displayed but there will be no ending segment details as it falls outside of
the time window. In this case, the IsComplete flag will be set to false. |
|
DistanceKilometers |
"DistanceKilometers":
25
}, |
The
number of kilometers traveled between the Start and End Location segment
shown. |