The Asset – GPS History API is available to
enable integrated users to poll GPS location-based information for a
specified period of time.
Important concepts to understand prior to
utilizing any of the available integration methods:
·
Asset – GPS History 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 to be created or
deleted. The unique identifiers used within this API method set
include:
o
Asset Number
·
This API only interacts with your Non-Powered Asset. Any
Powered Asset trackers you have will need to be queried using the Vehicle GPS
History API
Note : 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 |
Non- Powered Asset GPS
History |
|
Endpoint |
Non- Powered Assets
GPS history REST |
|
Operation |
GET |
The
following methods enable integrated users to extract an asset’s location or
information from REVEAL. These methods can be called for one asset or all
assets at a time within REVEAL
GET GPS history by asset number extracts
location of an asset for specified period of time. Easy request can query up to 30 days of data
|
Operation and Path |
GET /v1/assets/{assetnumber}/status/history?startdatetimeutc=yyyy-MM-ddTHH:mm:ss&enddatetimeutc=yyyy-MM-ddTHH:mm:ss Notes regarding the Start and End Date and Time
values used: 1. Start date and end date must be
within the accounts data plan 2. Start and End date must be less
than 30 days apart 3. Start and End date and time
values are required |
|
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. |
"GeofenceName": "VZC",
"Address": {
"AddressLine1": "2
Victoria Street",
"AddressLine2": "",
"Locality": "Christchurch",
"AdministrativeArea": "Canterbury",
"PostalCode": "8013",
"Country": "NZL"
},
"DeviceTimeZoneOffset":
12,
"DeviceTimeZoneUseDST": false,
"Latitude": -41.000000,
"Longitude": 163.000000,
"UpdateUTC": "2020-05-01T00:56:06"
},{
"GeofenceName": "VZC",
"Address": {
"AddressLine1": "57
Bealey Avenue",
"AddressLine2": "",
"Locality": "Christchurch",
"AdministrativeArea": "Canterbury",
"PostalCode": "8013",
"Country": "NZL"
},
"DeviceTimeZoneOffset":
12,
"DeviceTimeZoneUseDST": false,
"Latitude": -41.000000,
"Longitude": 162.000000,
"UpdateUTC": "2020-04-29T22:06:37"
}]
|
Field |
JSON Formatted Sample |
Field Notes and Default Values |
|
Address |
{ “Address”:{ “AddressLine1”
57 Bealey Avenue “AddressLine2”:”” “Locality”:”
"Christchurch",” “Administrative Area”:” Canterbury” “Postal Code”:”
8013” “Country”:NZL”” }, |
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 |
|
Device Time Zone Offset |
“DeviceTimeZoneOffset:”12” |
Device Time Zone Offset is the GPS device’s
current time zone compared to UTC. |
|
Device Time Zone Use DST |
“DeviceTimeZoneUseDST”:false, |
If the REVEAL account is set to acknowledge
Daylight Savings Time then this value will return as TRUE. REVEAL accounts in the United States are automatically
defaulted to True. |
|
Latitude |
“Latitude": -41.000000”, |
The latitude
of the last location |
|
Longitude |
“Longitude””162.000000,” |
The
longitude of the last location |
|
UpdateUTC |
“2020-04-29T22:06:37"” |
The date
time that the last location was reported to reveal |
The Status will be:
· 200 if the Asset Number was found for the account and the Asset has
Gps location history
· 204 if no last location history found (within the account Data
Plan) for the Asset Number
· 400 if the Asset Number was invalid or the startdatetimeutc
or enddatetimeutc parameters were invalid
· 404 if the Asset Number was not found for the account
· 500 if something else went wrong
A Bad Request (400) status will be
returned if any of the following conditions are not met:
· The Asset Number is a string that is not null or empty
and must be no more than 96 characters long.
· The startdatetimeutc and enddatetimeutc parameters are both required and should have
the format yyyy-MM-ddTHH:mm:ss.
· The enddatetimeutc DateTime
cannot be before startdatetimeutc.
· The startdatetimeutc and enddatetimeutc must be within 30 days of each other.
· The enddatetimeutc Date Time cannot be after
the Date Time that the request was made.
· The startdatetimeutc Date Time cannot be
before the Data Plan of the requesting Account.
GPS location history may be not found
(Status 204) if the Asset has not yet reported a location, or if it has but the
last time it reported was outside the data plan of the account