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:
·
Real-time
Aggregated Data – 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
|
API
Name |
Real-time
Aggregated Data – Segments API |
|
Endpoint |
https://fim.api.eu.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 error.
|
Operation
and Path |
GET https://fim.api.eu.fleetmatics.com/rad/v1/vehicles/<VehicleNumber>/segments?startdateutc=<0000-00-00T00:00:00> HTTP/1.1
Notes regarding the Start Date
and Time value 1. Start Date
cannot be more than 365 days prior to the current date |
|
HOST |
fim.api.eu.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 error.
|
Operation
and Path |
GET https://fim.api.eu.fleetmatics.com/rad/v1/drivers/<DriverNumber>/segments?startdateutc=<0000-00-00T00:00:00> HTTP/1.1
Notes regarding the Start Date
and Time value 2. Start Date
cannot be more than 365 days prior to the current date |
|
HOST |
fim.api.eu.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: v Latitude v Longitude Address contains the global standards for address components: v Address
Line 1 – location specific identification such as a house number v Address
Line 2 – additional information to identify location such as an apartment
number v Locality
– city, town, etc. v Administrative
Area – state, province, etc. v Postal
Code v 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: v Latitude v Longitude Address contains the global standards for address components: v Address
Line 1 – location specific identification such as a house number v Address
Line 2 – additional information to identify location such as an apartment
number v Locality
– city, town, etc. v Administrative
Area – state, province, etc. v Postal
Code v 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. |