--- updatedAt: 2025-11-11T22:54:58.000Z agentTools: projectIndex: https://pegasus.digitalcomtech.com/llms.txt --- # 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](reverse-geocoding) information so it's included in the address response. Geofences can be grouped into [geofence\_types](#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](http://geojson.org/) Please note that this api is [paginated](getting-started#pagination). > 🚧 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](authentication#scopes) `geofences` assigned to your user. All geofences are encoded using a [lossy compression algorithm](https://developers.google.com/maps/documentation/utilities/polylinealgorithm). All geofences will also have a `bbox`, or [bounding box](http://geojson.org/geojson-spec#bounding-boxes). ## 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](https://developers.google.com/maps/documentation/utilities/polylinealgorithm). These geofences can be up to 600 points. > > *Warning: Be sure to escape`\` characters with a second backslash `\\` in the encoded string.* > > **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: | visibility | description | | ---------- | -------------------------------------------------------------------------- | | all | anyone with scope to see `geofences` has access to see them | | groups | only people within the group you belong to have access to see the geofence | | private | only your user has access to see the geofence | 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](https://api.pegasusgateway.com/geofences) ```json { "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](https://api.pegasusgateway.com/geofences) ```json { "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](https://api.pegasusgateway.com/geofences/12) ```json { "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](https://api.pegasusgateway.com/geofences/12) > > 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](https://material.io/icons/) `"icon": "material:location_city"` or a custom URL
`"icon": "url: > Create a geofence type ```json { "name": "Clients", "color": "#ff0404", "visibility": "groups", "groups": [5], "geofences": [ 25, 1042, 1044, 1045, 1414, 1415, 1416 ], "icon": "material:location_city" } ```