Geofencing

Asset Distance and Search Radius

For each polygon geofence that covers the asset position or is close to it, the Fleet Telematics Geofencing returns the geofence geometry together with the asset's distance to this geometry.

The asset distance can be influenced by the following factors:

• The asset is outside of the geofence – the distance is the straight line to the closest border of the geofence. This is always the case for line and point geofences.
• The asset is inside the geofence – the distance is the straight line to the closest border of the polygon, with a negative sign.
• The asset is outside of the search radius – the geofence is not listed in the response.
• The asset is inside the polygon but further away from the border of the search radius – a special value indicating "far inside" is returned.

In your application, you can use the asset distance to generate events with different severity levels based on specific distance thresholds. You can also suppress superfluous events if the asset is moving along the geofence border, such as, entering or leaving the geofence frequently without a significant change in the asset distance.

For performance reasons, the asset distances are only straight-line distances, not equivalent to driving distances or driving times. Asset distances are limited to approximately 20 kilometers, so a distance can be one of the following:

• within the polygon 250m from the closest border
• within the polygon more than 20km from the closest border
• outside the geofence 333m from the closest border
• outside the geofence more than 20km from the closest border (this value applies to all non-listed geofences, when the asset is outside of the search radius)

Events such as entering, leaving, flickering along the border of the geofence, or re-entering the geofence do not receive an explicit response; only the asset distances. The same applies to a sequence of events, such as the asset entering the geofence for the third time or leaving for the second time on the same day.

Frequency of Requests

There is no restriction on how frequently you can query the Fleet Telematics Geofencing for geofences around an asset's position. To manage the load efficiently on the device, network, and service, your applications should use the distances returned by the API and suppress unnecessary calls. This is particularly the case when it is clear that the asset's geofencing status could not have changed much since the last query. For example, if the closest geometry distance was 3.5 km and the car has since moved 100 meters and could not have left or entered a geofence, it is sufficient to query the API less frequently.

Retrieve Geofence Geometry

Fleet Telematics Geofencing operates on the assumption that your application knows the geometry itself, to display or modify it. Hence, queries only return the ID of each geometry instead of the full geofence geometries, to reduce network traffic and increase the speed of the device and service.

To support a simple display in devices and asset manager centers, the API can optionally return the relevant fragments of the geometry – the part that is within the search radius. However, this may cause excessive load. To manage load efficiently, applications should cache the geometry piece of recently displayed geometries and only resend a query requesting for geometry fragments if:

• a non-cached geometry ID is returned
• the asset has moved around a lot since the last cached geometry fragment

Using Layers and Working with Polygons

Each geofence polygon, point, or polyline is assigned to exactly one layer. You can create multiple layers. A layer can only contain geometries of one type – either polygons, points, or polylines. This allows you to group the geofences by fence types or topics, or by asset groups.

If possible, submit or update all polygons of a layer in a single batch. The Fleet Telematics Geofencing supports adding or modifying of individual polygons, but only for storage type "updatable", not for "readonly".

Each customer can create multiple layers with many geometries per layer. For maximum values, see the Fleet Telematics Custom Locations resource serviceconfiguration.json. If you need to extend the limits, contact Technical Customer Support.

How to distribute the Geofences across map layers? While it seems obvious to create separate geofence layer per user/device/car, it is not efficient for the service. Usually, geofences of the same type (spatial extent, update frequency, coordinate resolution) should go together into a single layer. Each geofence should contain an attribute (or several ones) describing to which assets they apply (and some conditions, like timeframes), so customer’s application can filter which fences apply to the car/user. Being a backend service, Fleet Telematics Geofencing is usually not called by the users/devices directly, so it is not a privacy concern to return geofences of different cars/users to customer’s application. Also, different geometry types (circles vs polygons) should be stored in separate layers.

Polygon Identifier and Attribution

While the Fleet Telematics Geofencing is not intended for use as general storage for data, the API must have access to geo-shapes to respond to requests. Each of these geo-shapes must be associated with a unique identifier. The Fleet Telematics Geofencing also includes these IDs in the responses.

One common method for assigning these IDs uses straightforward geometry identifiers as follows:

• polygon ID for polygonal fences
• link ID for road, railway, river, or other linear fences
• point ID or store ID for point fences

In the following example, the column ID uniquely identifies the polygons near various famous locations.

ID  NAME  ABBR  WKT
1  AlexanderPlatz  DEU  POLYGON((13.41252 52.52228,13.41426 52.5221,13.41522 52.52113,13.41227 52.51981,13.41252 52.52228))
2  BrandenburgGate  DEU  POLYGON((13.38021 52.51668,13.37987 52.51678,13.37984 52.5163,13.37984 52.5163,13.38021 52.51668))
3  RoyalObservatory  UK  POLYGON((-0.00156 51.47778,-0.00142 51.47796,-0.00114 51.47776,-0.00172 51.4777,-0.00156 51.47778))

When you use the resource search/proximity to see whether a geo-coordinate is within a specified radius of a geo-shape loaded to a layer, use the request parameter key_attributes to define how you wish to group the geo-shapes in the response. For example, if you load the example above to a layer and specify key_attributes=NAME in your request, then the geo-shapes within the radius are listed separately in the response as each value in the NAME column is unique. In this case, the response looks as follows:

{
  "geometries": [
    {
      "attributes": {
        "ID": "2",
        "GEOMETRY_ID": "1",
        "NAME": "BrandenburgGate",
        "ABBR": "DEU"
      },
      "distance": 640.79,
      "nearestLat": 52.51668,
      "nearestLon": 13.38021,
      "geometry": "MULTIPOLYGON(((13.38021 52.51668,13.37984 52.5163,13.37987 52.51678,13.38021 52.51668)))"
    },
    {
      "attributes": {
        "ID": "1",
        "GEOMETRY_ID": "0",
        "NAME": "AlexanderPlatz",
        "ABBR": "DEU"
      },
      "distance": 1641.35,
      "nearestLat": 52.51981,
      "nearestLon": 13.41227,
      "geometry": "MULTIPOLYGON(((13.41252 52.52228,13.41426 52.5221,13.41522 52.52113,13.41227 52.51981,13.41252 52.52228)))"
    }
  ],
  "response_code": "200 OK"
}

However, if you specify key_attributes=ABBR in the same situation, the response groups the results that match the request for those lines that match the specified ABBR value. In other words, if you specify ABBR=DEU, the results include lines 1 and 2 if the geo-coordinate you are checking are within range of both. In this case, the response looks as follows:

{
  "geometries": [{
    "attributes": {
      "ID": "1",
      "GEOMETRY_ID": "0",
      "NAME": "AlexanderPlatz",
      "ABBR": "DEU"
    },
    "distance": 640.79,
    "nearestLat": 52.51668,
    "nearestLon": 13.38021,
    "geometry": "MULTIPOLYGON(((13.38021 52.51668,13.37984 52.5163,13.37987 52.51678,13.38021 52.51668)),((13.41252 52.52228,13.41426 52.5221,13.41522 52.52113,13.41227 52.51981,13.41252 52.52228)))"
  }],
  "response_code": "200 OK"
}

When you add line 4 to the geo-shapes as follows:

4  Reichstag  BER  POLYGON((13.37494 52.51885,13.37485 52.51948,13.3755 52.51817,13.3744 52.51757,13.37494 52.51885))

the API includes this geo-shape in the response if the geo-coordinate is within range, but in a separate group because the values were separate. In this case, the response looks as follows:

{
  "geometries": [
    {
      "attributes": {
        "ID": "1",
        "GEOMETRY_ID": "0",
        "NAME": "AlexanderPlatz",
        "ABBR": "DEU"
      },
      "distance": 640.79,
      "nearestLat": 52.51668,
      "nearestLon": 13.38021,
      "geometry": "MULTIPOLYGON(((13.38021 52.51668,13.37984 52.5163,13.37987 52.51678,13.38021 52.51668)),((13.41252 52.52228,13.41426 52.5221,13.41522 52.52113,13.41227 52.51981,13.41252 52.52228)))"
    },
    {
      "attributes": {
        "ID": "4",
        "GEOMETRY_ID": "3",
        "NAME": "Reichstag",
        "ABBR": "BER"
      },
      "distance": 871.25,
      "nearestLat": 52.51817,
      "nearestLon": 13.3755,
      "geometry": "MULTIPOLYGON(((13.37494 52.51885,13.37485 52.51948,13.3755 52.51817,13.3744 52.51757,13.37494 52.51885)))"
    }
  ],
  "response_code": "200 OK"
}

In short, you can use these column values in the same manner as the group-by function of SQL.

You may also associate arbitrary attributes with geo-shapes for use with your application. The API includes any values associated with a geo-shape in the response. These custom attributes should be restricted only to those that the application needs. Examples include information that devices or management centers do not store locally but need to retrieve from queries, such as a display name or the priority of the fence geometry.

If you need to store a large amount of data along with the geometries, meaning the size of your geometries in Bytes are equal to or more than the size of your additional data, contact Technical Customer Support.

Map Layers as Geofences

Geofences can be custom defined objects, but Fleet Telematics Geofencing also allows you to geofence on all map content. Examples:

• Check whether the asset is in a woodland, builtup area, lake, ocean, park, hospital, beach, or airfield. Therefore geofence against the corresponding Fleet Telematics API cartographic polygon layers.
• Check whether the asset is close to a restaurant, hotel, train station, or fuel station. Therefore geofence against the corresponding Fleet Telematics API Point of Interest (POI) layers.
• Check whether the asset is on or close to a railway line, small river line, or country border line. Therefore geofence against the corresponding Fleet Telematics API cartographic line layers.
• Check whether the asset is on a motorway, federal road, small road, or pedestrian path. Therefore geofence against the corresponding Fleet Telematics API road geometry layers, and join Fleet Telematics API road information layers.

Refer to the Fleet Telematics API Developer Guide for available layers. Geofencing on maps uses the same resources as geofencing on custom polygons, but a different service endpoint.