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: To return
information on Non-powered assets please call for the methods specified in
Non-Powered Assets API
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 atmosphere_app_id=fleetmatics-p-us-[ Verizon Connect App ID ], Bearer [Authorization 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 atmosphere_app_id=fleetmatics-p-us-[ Verizon Connect App ID ], Bearer [Authorization 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. |