Geofence

What IS a Geofence?

A geofence is an arbitrary area defined around a trailer, or other asset. Geofences are always rectangular, with a specified height and width. The dimensions can be specified when setting a trailer's geofence.

Each trailer can have its own geofence definition. Geofences are not defined outside of a trailer context, that is, there are no standalone geofence definitions, they are always associated with a trailer.

Geofences are typically used to establish a "region" into which the trailer should or should not cross. Users can establish a geofence around a trailer, and then be notified when the trailer moves outside the geofence region. For example, an asset is dropped in a yard. A geofence is established, roughly the size of the yard. If the trailer leaves the geofence (ie: leaves the yard), a user may wish to be notified.

Geofence Object

Information about a geofence is implemented in the Geofence object. The attributes of the Geofence object are:

Attribute	Description
desc	A string of maximum length 40 that contains a description of the geofence.
centerPref	Indicates the center option for the geofence. A self-centered geofence uses the trailer's position, as of the geofence start date, as its centerpoint. A lat/long-centered geofence uses a specified latitude and longitude as its centerpoint. Possible values are: 1 Self-centered 2 Lat/long-centered
centerLat	A floating point (double) value containing the latitude of the geofence centerpoint in decimal degrees. A positive value indicates the northern hemisphere. A negative value indicates the southern hemisphere.
centerLon	A floating point (double) value containing the longitude of the geofence centerpoint in decimal degrees. A positive value indicates the eastern hemisphere. A negative value indicates the western hemisphere.
nsLength	A floating point (double) value containing the north/south length (height) of the geofence. U.S. and Imperial valid range is .32 - 620.0 miles. Metric valid range is .5 - 1000.0 kilometers.
ewLength	A floating point (double) value containing the east/west length (width) of the geofence. U.S. and Imperial valid range is .32 - 620.0 miles. Metric valid range is .5 - 1000.0 kilometers.
startDate	A string containing a timestamp in the form YYYY-MM-DDTHH:MM:SSZ indicating the activation time in GMT of the geofence. Geofences are only considered "active" if the current time is between the geofence start and stop dates. Only active geofences will generate geofence alerts.
stopDate	A string containing a timestamp in the form YYYY-MM-DDTHH:MM:SSZ indicating the deactivation time in GMT of the geofence. Geofences are only considered "active" if the current time is between the geofence start and stop dates. Only active geofences will generate geofence alerts.
active	A string indicating whether or not the geofence is active. Possible values are: Y The geofence is active N The geofence is not active When setting this value to 'N' to disable the geofence, the following elements must also be set accordingly: ongoing - N startDate - blank stopDate - blank
ongoing	A string indicating whether or not the geofence is ongoing. If a geofence is ongoing, the value in the stop date will be ignored. Possible values are: Y The geofence is ongoing N The geofence is not ongoing
checkInt	A string in the form +DDDDDHHMMSS indicating the interval the terminal will check its geofence position status when not under external power. Possible values are: +00000000000 Never +00000000500 5 mins +00000001500 15 mins +00000003000 30 mins +00000010000 1 hr +00000020000 2 hrs +00000030000 3 hrs +00000040000 4 hrs +00000060000 6 hrs +00000080000 8 hrs +00000120000 12 hrs +00001000000 1 day
entryAction	A string indicating the action taken by the terminal when a trailer enters the geofence. Possible values are: 000 Ignore completely (the terminal should take no action when it detects that the trailer enters the geofence) 001 Send event with next scheduled message (the terminal should send the message the next time it sends a scheduled message) 002 Send event immediately (the terminal should send the message as soon as it detects that the trailer enters the geofence) 003 Send event immediately and stay awake (the terminal should send the message as soon as soon as it detects that the trailer enters the geofence and stay powered up (awake) until the stay awake interval is reached)
exitAction	A string indicating the action taken by the terminal when a trailer exits the geofence. Possible values are: 000 Ignore completely (the terminal should take no action when it detects that the trailer exits the geofence) 001 Send event with next scheduled message (the terminal should send the message the next time it sends a scheduled message) 002 Send event immediately (the terminal should send the message as soon as it detects that the trailer exits the geofence) 003 Send event immediately and stay awake (the terminal should send the message as soon as soon as it detects that the trailer exits the geofence and stay powered up (awake) until the stay awake interval is reached)

WSDL Definition

The WSDL defines a Geofence structure in this manner:

<complexType name="Geofence">

<sequence>

<element name="desc" nillable="true" type="xsd:string"/>

<element name="centerPref" nillable="true" type="xsd:string"/>

<element name="centerLat" type="xsd:double"/>

<element name="centerLon" type="xsd:double"/>

<element name="nsLength" type="xsd:double"/>

<element name="ewLength" type="xsd:double"/>

<element name="startDate" nillable="true" type="xsd:string"/>

<element name="stopDate" nillable="true" type="xsd:string"/>

<element name="active" nillable="true" type="xsd:string"/>

<element name="ongoing" nillable="true" type="xsd:string"/>

<element name="checkInt" nillable="true" type="xsd:string"/>

<element name="entryAction" nillable="true" type="xsd:string"/>

<element name="exitAction" nillable="true" type="xsd:string"/>

</sequence>

</complexType>

Example XML

An example of a Geofence structure contained within an XML request or response:

<geofence>

<desc />

<centerPref>2</centerPref>

<nsLength>1.0</nsLength>

<ewLength>2.0</ewLength>

<startDate>2006-05-17T19:01:00Z</startDate>

<stopDate xsi:nil="true" />

<active>Y</active>

<ongoing xsi:nil="true" />

<checkInt>+00001000000</checkInt>

<entryAction>002</entryAction>

<exitAction>002</exitAction>

<centerLat>27.853055555555557</centerLat>

<centerLon>-82.80777777777777</centerLon>

</geofence>