Non- Powered Assets Update REST

Asset Update API enables integrated users to poll GPS location-based information of the Non-Powered Assets within the Reveal account

Important concepts to understand prior to utilizing any of the available integration methods:

·        Asset Update API is offered as a RESTful web service

·       Standard REST verbs are applied: GET, POST

·       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 Update 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 Summary Details

API Name

Non -powered Assets update REST API

Endpoint

Non- powered Assets update REST 

Operation

GET, POST

GET Methods

The following methods enable integrated users to extract an asset’s location or information from REVEAL. 

Get Location By Asset Number 

Get Location by Asset Number extracts last recorded location of a specified asset or assets. 

GET Location by Asset Number  API Request Header

Operation and Path

GET https://fim.api.us.fleetmatics.com/AST/v1/assets/{assetnumber}/location

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.

 

GET GPS Location by Asset Number sample response

  {

    "GeofenceName": "VZC",

    "Address": {

        "AddressLine1": "2 Victoria Street, Christchurch Central City, Christchurch 8013, New Zealand",

        "AddressLine2": "",

        "Locality": "Christchurch",

        "AdministrativeArea": "Canterbury",

        "PostalCode": "8013",

        "Country": "NZL"

    },

    "DeviceTimeZoneOffset": 12,

    "DeviceTimeZoneUseDST": false,

    "Latitude": -41.000000,

    "Longitude": 162.000000,

    "UpdateUTC": "2020-05-07T19:56:06"

 

}

 

Field

JSON Formatted Sample

Field Notes and Default Values

Address

{

“Address”:{

“AddressLine1”:” 2 Victoria Street, Christchurch Central City, Christchurch 8013, New Zealand”

“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-05-07T19:56:06”

The date time that the last location was reported to reveal

 

POST METHODS

The POST Locations by Asset Numbers enables the integrated user to return location information for up to 50 assets within one call.

 Get Locations By Asset Number 

Operation and Path

POST https://fim.api.us.fleetmatics.com/AST/v1/assets/locations

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.

 

POST Locations by Asset Number sample request 

POST /v1/assets/locations

[

    "A10001",

    "A10002",

    "X99999"

]

 

POST Locations by Asset Number sample response 


    {

"Asset Number": "A10001",

"ContentResource": {

"Value": {

"GeofenceName": "VZC",

"Address": {

"AddressLine1": "2 Victoria Street, Christchurch Central City, Christchurch 8013, New Zealand",

"AddressLine2": "",

"Locality": "Christchurch",

"AdministrativeArea": "Canterbury",

"PostalCode": "8013",

"Country": "NZL"

},

"DeviceTimeZoneOffset": 12,

"DeviceTimeZoneUseDST": false,

"Latitude": -41.000000,

"Longitude": 162.000000,

"UpdateUTC": "2020-05-07T19:56:06"

},

"Status": 200

},

"Status": 200

},

{

"Asset Number": "A10002",

"ContentResource": {

"Value": null,

"Status": 404

}

"Status": 200

},

{

"Asset Number": "X99999",

"ContentResource": null,

"Status": 404

}

]

 

POST Locations by Asset Number Response Field Breakdown

Field

JSON Formatted Sample

Field Notes and Default Values

Asset Number

[

{

"Asset Number": " A10001",

The Vehicle Number called in the request will be returned within the response.

Status

"StatusCode": 200,

The POST Locations enables integrated users to call a list of up to 50 vehicles within one request.  Therefore, the response may include individual statuses per vehicle.

·       400

·       500

·       404

·       200

The Status Code at the top of the response indicates if the Vehicle Number provided can be found.

ContentResource.Value

“null”

This is a data transfer object wrapper used to distinguish an Asset resource from that Asset's Location resource

Geofence Name

“VZC”

Geofence is a place configured within a REVEAL account to easily identify particular locations.

The value will default to NULL if the GPS plot referenced does not occur within a Geofence.

Address

Address": {

"AddressLine1": "2 Victoria Street, Christchurch Central City, Christchurch 8013, New Zealand",

"AddressLine2": "",

"Locality": "Christchurch",

"AdministrativeArea": "Canterbury",

"PostalCode": "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,,

 

Longitude

"Latitude": 162.00000,

 

Update UTC

UpdateUTC”:”2020-05-07T19:56:06

}

The date and time stamp when the GPS plot was received.

Format: xxxx-xx-xxTxx:xx:xx

YEAR-MONTH-DAY T HOURS-MINUTES-SECONDS

ContentResource.Status

“200"

 

The status code of the Location

·       200 indicates a last location was successfully found for the respective Asset

·       404 indicates that no last location was found (within the account Data Plan) for the respective Asset

·       500 indicates that something else went wrong while fetching the last location of the Asset