Geofences

Geofences are user defined areas on the map that can be used together with triggers and tasks for a more personalized experience, for example to let you know when a vehicle reaches a particular location on the map. Geofences are also available when you request the reversegeo information so it's included in the address response.

Geofences can be grouped into geofence_types (also referred to as geofence collections)

The geofence API is based on the geojson spec, for more information on geojson visit geojson.org

Please note that this api is paginated.

🚧

Geofence limit

Please note that there is a limit of 32,000 geofences on each Pegasus gateway site. If you attempt to create more you'll receive an HTTP response 400.

View

In order to view geofences you have to have the scope geofences assigned to your user.

All geofences are encoded using a lossy compression algorithm.

All geofences will also have a bbox, or bounding box.

Create

When creating a geofence you have to specify the Geometry type you want to create, the API supports Polygon of 3 or more coordinates (up to 200 coordinates in an array, or 600 in an encoded path), Circle, or LineString types.

📘

Circle Type

Note that the geojson spec does not officially handle Geometry Objects of type: Circle. Pegasus made it up according to proposals.

Coordinates

Polygon

geometry.coordinates = [[[lon1,lat1],[lon2,lat2],[lon3,lat3],[lon1,lat1]]]

Note that for Polygons the first and last pair of coordinates need to be the same: [[lon1,lat1],...,[lon1,lat1]]

Circle

geometry.coordinates = [lon,lat]

LineString

geometry.coordinates = [[lon1,lat1],[lon2,lat2]]

👍

Creating geofences with more than 200 points

You can create a geofence with an encoded polyline path using the Polyline Algorithm Format. These geofences can be up to 600 points.

POST /api/geofences

JSON

{
    "type": "Feature",
    "geometry": {
        "type": "Polygon",
        "coordinates": null
    },
    "properties": {
        "name": "polygon from encoding",
        "visibility": "private",
        "description": "sample geofence from encoded polyline",
        "resolution": "name",
        "types": [],
        "groups": [],
        "custom": {}
    },
    "encoding": "atu{BrxvuQj`Mf_Gj|EreDxnAzlMxqDta@f_LgdAxiBynQraRqrG|nPbyGlqWpdQn|FvwCjs`@ewT|EoUiJbjEcy@ryDucBvwCglAvxDrwBz|B~zAzuA|cKfgRreD~bh@fXz`Jm_Bwe@_|XqaM}eNjcN{jDlbFgzBl`RrGpuGtvAt~FnzF`aG{k@xtFyyIjiBynL_tDgaCkd@cxF~Z}}DtpCmkAx}CmIjwGr}Hvl[ffBziC|rM|lGt{GtdC|iNz`Ogr@b~Ec{MvkDadEnnBk{DtmIozD|pDo{Ey`@ylFmfCudC_t@mwD|Ea|FrzE_wDtaG~l@psKbKpiDahBvuD}zHtiI}aIh`J{{AhaDgJjuAydZgbAydS|Es_Sasl@o~HyqPq~BxwA_jDzt@mfC_F_sNcoCwzF_jDykAksFufIswFkxWafG}bCbnBiuDoUeiH_yKroDcxHrU}dEmdHor`@q`T`NguCwbF}_@chC?gbDtbA{sCzlFq{BplDso@b}D_qLr[c~EqxF{id@azDiM_bJrb@igC_t@{gH}`H_hBwlE[}fAz|BglD|kFgbAbjEzYniGxhAj{D{z@|cDauBtjJggJb`AurDisBmkGouF_tBiyAqjIzjZouXzfGbwAxwYxfNrbHfvLs}ArhGfmBpsKreRxiUjpCkFzdAisBeKmcGe^{wDnc^`jSjfJhiFz|X{sNv{@q_Dkq@w}B_~LkeTaxT_fRa`HiqG}nI}wLe|@urDr`B}uI~pD{`@dfIjJzpCpNhtGn{AhmKftH"
}

The visibility of the geofences are as follow:

If you set the visibility to "groups" you'll have to specify in an array called: groups the group IDs you'd like this geofence to belong to.

Custom Properties

When creating geofences you can specify custom properties using the custom key in the properties. This accepts any JSON object value.

👍

Point of Interest in Geofences

There is a special custom boolean property called: $checkpoint that is added with value true when the geofence is a point of interest. This property should only be used on circular type geofences with a radius of 50 m.

👍

Speed Limits in Geofences

There is a special custom property called: speed_limit which can be assigned to a geofence. It represents a speed limit in mph, once set it's used in some reports and other parts of Pegasus-app. Note that this field accepts decimals too.

Create a circular fence of 105 meter radius around 24.78238, -82.28900

Assign a speed limit of 40km/h (24.8548mph) to this geofence

POST /geofences

{
    "type": "Feature",
    "geometry": {
        "type": "Circle",
        "radius": 50,
        "coordinates": [
            -82.289,
            24.78238
        ]
    },
    "properties": {
        "name": "warehouse 234",
        "visibility": "groups",
        "groups": [
            500
        ],
        "custom": {
            "foo": "bar",
            "speed_limit": 24.8548,
            "$checkpoint": true
        },
        "types": [],
        "description": "this is a sample description"
    }
}

Create a square polygon geofence

Associated to geofence_type 55

POST /geofences

{
    "type": "Feature",
    "geometry": {
        "type": "Polygon",
        "coordinates": [
            [
                [
                    -81.07642,
                    26.38707
                ],
                [
                    -80.96106,
                    26.27383
                ],
                [
                    -81.11487,
                    26.21471
                ],
                [
                    -81.23023,
                    26.29353
                ],
                [
                    -81.07642,
                    26.38707
                ]
            ]
        ]
    },
    "properties": {
        "name": "Square Polygon",
        "visibility": "all",
        "types": [
            55
        ],
        "description": "Warehouse with small packages"
    }
}

Updating Geofences

When updating a geofence using the API, pass the geometry and properties object.

Update name, radius, and add a custom property

PUT /geofences/:id

{
    "type": "Feature",
    "geometry": {
        "type": "Circle",
        "radius": 52,
        "coordinates": [
            -80.289000061596184,
            25.78238262858029
        ]
    },
    "properties": {
        "name": "Warehouse 3",
        "custom": {
            "contact": "John Smith",
            "amount": 123
        }
    }
}

Deleting Geofences

Delete a fence

DELETE /geofences/:id

204 NO CONTENT

❗️

Careful with deletion

Note that when you delete a geofence this affects any alerts or reports that were previously made that depended on the geofence

Geofence Types (Collections)

Geofence types are collections of geofences, a geofence can belong to one or many types.
These collections are useful for quickly generating reports and scheduling them too.

For example, let's say that you have a fleet of delivery trucks that make daily deliveries to specific locations. These locations can be saved as a geofence_type called: Clients. Thus when generating a trigger for Vehicle Inside Geofence and Idling for example, you want to create a single trigger that encompasses the Clients geofence type we created, rather than individual fences. Note that any future geofences you add to the Client type automatically gets updated.

Create

When creating a geofence type the important parameters are the name, visibility and geofences

You can optionally set a HEX color code for the geofences under the color parameter.
Also you can set an icon using the material icon library

"icon": "material:location_city"

or a custom URL

"icon": "url:<https://goo.gl/bQFcW5">

Create a geofence type

{
  "name": "Clients",
  "color": "#ff0404",
  "visibility": "groups",
  "groups": [5],
  "geofences": [
    25,
    1042,
    1044,
    1045,
    1414,
    1415,
    1416
  ],
  "icon": "material:location_city"
}