The TimeInZone method returns the "Total Time in a Zone (Geofence or Radius)" for Devices available to your account. Unlike many of the other methods in this API, TimeInZoneReport does not directly access database objects. Instead, it builds and returns datasets of other database objects.
The optional 'Interpolate' parameter is TRUE by default. When true, the API will look at data just prior to and after the specificd window to give larger Time In Zone windows. If FALSE, Time in Zone is reported by device pings.
'Interpolate' Example: A vehicle has been parked in ZoneID 1 for the last 4 hours and is sending GPS data every 30 min (since it's parked Á ignition is off). Running a TimeInZone Report for the last hour with Interpolate=false may return TimeInZone of less than 1 hour, as it will look at the 1st device ping after FROM and 1st device ping prior to TO date. Using Interpolate=true will show a 1 hour time in zone.
The following datatype will be JSONified and returned for methods which retrieve values.
| public | UInt64 | AccountId; | // The AccountId associated with the Device |
| public | UInt64 | DeviceId; | // The DeviceId (Serial#) associated with the Device |
| public | String | DeviceName; | // The Device Name matched with the DeviceID |
| public | UInt64 | AlertId; | // The AlertID associated with the Geofence/Radius Zone |
| public | String | AlertName; | // The name of the Alert that defines the Geofence/Radius Zone |
| public | DateTime | Entered; | // The time the Device ENTERED the Geofence/Radius Zone |
| public | DateTime? | Exited; | // The time the Device EXITED the Geofence/Radius Zone. NOTE: If the device has not yet exited the ZONE at time of report, this will return NULL but TOTAL TIME will reflect time 'up to the END DATE PARAMETER of the report' |
| public | UInt64 | TotalSeconds; | // The total SECONDS in zone. |
The following list provides a reference for all valid /TimeInZone HTTP requests.
Summary: Retrieve a report that is run immediately and returned as soon as possible. These reports are typically limited to a small range or timespan.
Returns:
Parameters:
- id: The AccountId associated with API caller (FromUri)
- from: The DateTime to begin report. If no FROM/TO dates passed in, default is last 24 hours. (FromUri)
- to: The DateTime to end report. If no FROM/TO dates passed in, default is last 24 hours. (FromUri)
- devices: A comma-separated list of DeviceIds to lookup for a report. If this is not specified, reports will run for all devices visible to the account. (FromUri)
- UTCoffset: (Optional) UTC offset to return results in. Default is CENTRAL TIME. (see https://24timezones.com/time-zones for example strings: "UTC-6" for minus 6 or "UTC%2b6" for plus 6) (FromUri)
- alerts: A comma-separated list of AlertIds (aka ZoneIDs) to lookup for a report. If this is not specified, reports will run for all Geofence/Radius Alerts visible to the account. (FromUri)
- interpolate: (Optional, true by default) This option 'interpolates' time in zone by looking at data before and after the specified windows. (FromUri)
- CompletedResultSets: (Optional) When TRUE, only records whose ENTERED/EXIT times fall within the API's START and END times are returned. Default is FALSE. (FromUri)
- account: (Optional) If this parameter is included, the method will be run on behalf of the specified child Account (if valid). (FromUri)
- fobBased: (Optional) If this bool parameter is set to TRUE, the method will return some additional result elements: Driver, Driver EIN and FOB. This option is for FOB drivers only. (FromUri)