Intro

Assets - Reading

Get all assets

Syntax

GET /assets.xml

Input

Output

  <assets effective_at="[date]" delta_mode="[new|delta]">
    <asset>  
      <id>[integer]</id>
?     <deleted>true</deleted>
      <fleet_id>[string]</fleet_id>
      <asset_type>[string]</asset_type>
      <effective_at>[date]</effective_at>
      <reported_at>[date]</reported_at>
      [Name/Value Pairs]
    </asset>
    :
    :
    :
  </asset>

Get a particular asset by id

Syntax

GET /assets/[id integer].xml

Input

?fields=[comma-separated desired field names]

Output

  <asset>
    <id>[integer]</id>
?   <deleted>true</deleted>
    <fleet_id>[string]</fleet_id>
    <asset_type>[string]</asset_type>
    <effective_at>[date]</effective_at> [The latest actual message time]
    <reported_at>[date]</reported_at>   [The time that the message came in]
    [Name/Value Pairs]
  </asset>

Notes

• effective_at is the actual time from the tmu that the message represents.
• effective_at will always be less than the current server time, since future events cannot be considered to have happened yet.
• reported_at is the server time that the message was received

Errors

• If the asset cannot be found

Assets - Writing

Create or update an Asset

Syntax

POST /assets.xml

Input

  <asset>
    <fleet_id>[string]</fleet_id>
    <asset_type>[string]</asset_type>
    <effective_at>[date]</effective_at>
    [Name/Value Pairs]
  </asset>

Output

  <asset>
    <id>[integer]</id>
    <fleet_id>[string]</fleet_id>
    <asset_type>[string]</asset_type>
    <effective_at>[date]</effective_at>
    [Name/Value Pairs]
  </asset>

Notes

• <effective_at>[date]</effective_at> is optional in the input
• effective_at will default to the current time on the server when the request is made if it is not provided
• If the fleet_id is not known, then a new asset is created
• If the fleet_id is known already, then the asset’s details are updated.

Update an Asset by id

Syntax

PUT /assets/[id integer].xml

Input

  <asset>
    <id>[integer]</id>
    <fleet_id>[string]</fleet_id>
    <asset_type>[string]</asset_type>
    [Name/Value Pairs]
  </asset>

Output

  <asset>
    <id>[integer]</id>
    <fleet_id>[string]</fleet_id>
    <asset_type>[string]</asset_type>
    <effective_at>[date]</effective_at>
    [Name/Value Pairs]
  </asset>

Notes

• The input Name/Value pairs MAY include <effective_at>[date]</effective_at>
• effective_at will default to the current time on the server when the request is made
• Use this service to update an asset’s fleet_id or asset_type

Errors

• If a new fleet_id is included, and another asset already has that fleet_id
• If the asset’s id is included and does not match the id in the URL
• If the asset id in the URL is not found

Delete an Asset by id

Syntax

DELETE /assets/[id integer].xml

Input

n/a

Output

  <asset>
    <id>[integer]</id>
    <deleted>true</deleted>
    <fleet_id>[string]</fleet_id>
    <asset_type>[string]</asset_type>
    <effective_at>[date]</effective_at>
    [Name/Value Pairs]
  </asset>

Errors

• If the asset id in the URL is not found

Assets - History

Get a history of all assets

Syntax

GET /assets.xml?start_time=:date&end_time=:date

Input

?fields=[comma-separated desired field names]

Output

  <assets>
    <asset>  
      <id>[integer]</id>
      <fleet_id>[string]</fleet_id>
      <asset_type>[string]</asset_type>
      <effective_at>[date]</effective_at>
      <reported_at>[date]</reported_at>
      [Name/Value Pairs]
    </asset>
    :
  </asset>

Notes

• The output will be for all assets.
• The order will be asset_id, effective_at.
• The effective_at field for the first entry for each asset may be less than start_time

Errors

• If the start_time or end_time cannot be recognised as timestamps
• If the start_time > end_time

Get a history of a particular asset by id

Syntax

GET /assets/[id integer].xml?start_time=:date&end_time=:date

Input

?fields=[comma-separated desired field names]

Output

  <assets>
    <asset>  
      <id>[integer]</id>
      <fleet_id>[string]</fleet_id>
      <asset_type>[string]</asset_type>
      <effective_at>[date]</effective_at>
      <reported_at>[date]</reported_at>
      [Name/Value Pairs]
    </asset>
    :
  </asset>

Notes

• The output will be for a single asset.
• The order will be effective_at.
• The effective_at field for the first entry may be less than start_time

Errors

• If the asset matching the id in the URL cannot be found
• If the start_time or end_time cannot be recognised as timestamps
• If the start_time > end_time

Special RUC Additions

Read Asset

GET /assets.xml

GET /assets/:asset_id.xml

Returns the details of the asset(s) as at the most recent update timepoint (usually a beacon time).

There are several virtual fields for RUC that will be added to the standard asset xml if RUC is deployed:

• hubodometer_id - From the hubodometers table
• last_hubo_reading - From the hubodometer_readings table based on effective_at
• last_hubo_reading_odo - as above
• last_hubo_reading_time - as above
• virtual_hubo - Based on last_hubo_reading and an accumulated sum of gps_distance values for all beacons since last_hubo_reading_time that is capped to a maximum value if there is a subsequent hubo_reading.
• virtual_odo - as above
• ruc_licence - The licence_id from the ruc_licences table, based on the hubodometer_id and the start_km, end_km range that spans the virtual_hubo. If more than one licence fits that description, then the one with the highest start_km is chosen.
• ruc_licence_start_km - as above
• ruc_licence_end_km - as above
• ruc_licence_vehicle_type_number - as above
• ruc_licence_type - Either “distance” or “supplementary”, based on the value of end_km - start_km for the licence chosen above.
• ruc_licence_status - ALERT/WARN/OK based on how many kilometers after the virtual_hubo until a km range that is not covered by a known RUC Licence for the current Hubodometer. ALERT means there is no RUC licence for the current vurtual_hubo, and WARN means that there is a missing RUC licence for a hubo value between virtual_hubo and virtual_hubo+500
• ruc_licence_off_road_km - Hard to calculate. Some more thought required here.

The virtual hubo field for an asset is based on

• The Hubodometer that is/was assigned to the asset at the timepoint
• The most recent Hubodometer reading for the Hubo at the timepoint
• The amount of GPS distance travelled since that time, which is the sum of all the known “segment_length”s for the asset since the Hubo Reading.
• The value of the first Hubo Reading (if any) for the Hubodometer whose effective_at time is greater than the timepoint requested. The v.Hubo cannot exceed the known hubo value for a timepoint, so it will be capped at that value if required.

Asset History (playback or reports)

GET /assets.xml?start_time=:start_time&end_time=:end_time

GET /assets/:asset_id[,:asset_id,...].xml?start_time=:start_time&end_time=:end_time

Can be paginated, using &page_size=:page_size&page_number=:page_number

Returns the historical time series of the asset(s).

Calculates the virtual hubo field for the asset(s) between the start_time and end_time. The virtual hubo is calculated slightly differently in this case, since only the current “GPS Distance since last hubo reading” is cached.

Paths

You can use e.g. Google Earth to inspect RUC history of an asset using URLs like:

http://[customer-name].visfleet.com/cs/paths.kml?asset_id=1&start_time=2008-12-02T11:00:00Z&end_time=2008-12-03T11:00:00Z

Be careful not to set the start_time and end_time too far apart lest you overwhelm Google Earth (and the server) with data - typically a day's worth is fine, and a week's worth would be the maximum.