Skip to content

Geofences

These endpoints create and manage your project’s geofences from your backend. A geofence is a circle or polygon. The server checks every device’s uploaded locations against it and records geofence.enter, geofence.exit and geofence.dwell events; devices receive the fences automatically. For the SDK side, see Geofencing.

Scope: geofences:write · Creates a geofence.

Terminal window
curl -s -X POST https://api.in1.getbeekon.com/v1/geofences \
-H "Authorization: Bearer $BEEKON_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "HQ",
"geometry": {
"type": "circle",
"center": {"latitude": 12.9716, "longitude": 77.5946},
"radius_meters": 150
},
"notify_on_entry": true,
"notify_on_exit": false
}'

Body

MemberTypeRequiredRule
namestringyes1 to 200 bytes, not only whitespace, no control characters.
geometryobjectyesSee Geometry.
notify_on_entrybooleanyes
notify_on_exitbooleanyes
notificationobjectnoSee Notifications. null is the same as leaving it out.
pass_throughstringnooff or on; absent or null is off. See Fence policies.
on_unreachablestringnonone or exit; absent or null is none. See Fence policies.

No other member is accepted. Response 201: {"geofence":{…}}, identical to what a following GET returns.

Scope: geofences:read · Lists the project’s geofences, paged, ordered by id.

Terminal window
curl -s -G https://api.in1.getbeekon.com/v1/geofences \
-H "Authorization: Bearer $BEEKON_TOKEN" \
--data-urlencode "limit=100"
ParameterRequiredMeaning
limitno1–500, default 100.
cursornoThe previous page’s next_cursor (prefix gf1_).

Response 200: {"geofences":[{…}],"next_cursor":null}.

Scope: geofences:read

Terminal window
curl -s \
https://api.in1.getbeekon.com/v1/geofences/0199b2c5-7d10-7a3e-9c44-1e2f3a4b5c6d \
-H "Authorization: Bearer $BEEKON_TOKEN"

Response 200: {"geofence":{…}}.

Scope: geofences:write · Replaces the geofence: the body is the same as for POST, and every member is set from it. Leaving notification out removes the fence’s notification, and leaving pass_through or on_unreachable out resets it to off or none.

Terminal window
curl -s -X PUT \
https://api.in1.getbeekon.com/v1/geofences/0199b2c5-7d10-7a3e-9c44-1e2f3a4b5c6d \
-H "Authorization: Bearer $BEEKON_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "HQ (north gate)",
"geometry": {
"type": "circle",
"center": {"latitude": 12.9721, "longitude": 77.5946},
"radius_meters": 200
},
"notify_on_entry": true,
"notify_on_exit": true
}'

Response 200: {"geofence":{…}}. The body is validated before the id is looked up, so a bad body is a 400 even for an unknown id.

Scope: geofences:write · Deletes the geofence. Devices drop it when they next receive geofence updates.

Terminal window
curl -s -X DELETE \
https://api.in1.getbeekon.com/v1/geofences/0199b2c5-7d10-7a3e-9c44-1e2f3a4b5c6d \
-H "Authorization: Bearer $BEEKON_TOKEN"

Response 204, no body. Deleting it again is 404 not found.

{
"id": "0199b2c5-7d10-7a3e-9c44-1e2f3a4b5c6d",
"created_at": "2026-10-07T06:30:00.000Z",
"geometry": {
"type": "circle",
"center": {"latitude": 12.9716, "longitude": 77.5946},
"radius_meters": 150
},
"name": "HQ",
"notification": {
"delivery": "local",
"on_enter": {"body": "Welcome to HQ.", "title": "Arrived"}
},
"notify_on_entry": true,
"notify_on_exit": false,
"on_unreachable": "none",
"pass_through": "off",
"updated_at": "2026-10-07T06:30:00.000Z"
}
MemberTypePresenceMeaning
idstringalwaysThe geofence id, a UUID. Events name the fence by this id.
namestringalwaysYour label.
geometryobjectalwaysThe area, in its stored form (see Geometry).
notify_on_entrybooleanalwaysWhether devices notify on entering.
notify_on_exitbooleanalwaysWhether devices notify on leaving.
notificationobjectwhen setThe notification devices show on a crossing (see Notifications).
pass_throughstringalwaysoff or on. Whether a device that passes through the fence between two locations produces an enter and an exit. See Fence policies.
on_unreachablestringalwaysnone or exit. What happens when a device inside the fence becomes unreachable. See Fence policies.
created_atstringalwaysWhen it was created.
updated_atstringalwaysWhen it was last replaced.

Only live geofences are served. A deleted geofence is gone from every endpoint (404), but past events keep its id.

Send one of three shapes. Coordinates are WGS 84 degrees.

{
"type": "circle",
"center": {"latitude": 12.9716, "longitude": 77.5946},
"radius_meters": 150
}
{
"type": "polygon",
"coordinates": [
[
[77.5940, 12.9710],
[77.5952, 12.9710],
[77.5952, 12.9722],
[77.5940, 12.9722],
[77.5940, 12.9710]
]
]
}
{
"type": "multipolygon",
"coordinates": [
[
[
[77.5940, 12.9710],
[77.5952, 12.9710],
[77.5952, 12.9722],
[77.5940, 12.9710]
]
]
]
}
  • polygon and multipolygon use GeoJSON coordinates: [longitude, latitude] order, an outer ring first, then any holes.
  • radius_meters is a number greater than 0.

The server stores a normalised form and returns it from then on. It makes only these changes: a polygon becomes a one-part multipolygon; an unclosed ring is closed; consecutive duplicate vertices are collapsed; rings are rewound so outer rings run counter-clockwise and holes clockwise. Coordinate values are never rounded or moved. A circle is returned as sent.

Invalid geometry is refused, never repaired:

error (400)When
shape_unknowntype is not circle, polygon or multipolygon.
coordinate_out_of_rangeA latitude outside −90…90 or a longitude outside −180…180, or a circle without a usable centre.
radius_not_positiveA circle’s radius_meters is 0, negative or not a finite number.
ring_too_few_verticesA ring has fewer than 3 distinct vertices.
self_intersectionA ring crosses itself, rings of one polygon cross each other, or two parts of a multipolygon overlap.
hole_outside_shellA hole is not inside its outer ring.
antimeridian_spanThe geometry’s longitudes span more than 180°. Split it into fences on each side of the antimeridian.
invalid_geometrygeometry is not a geometry document at all (for example, a string, or coordinates that are not arrays of numbers).

A geofence may carry a notification that the SDK shows as a native OS notification at the crossing, even offline or with the app closed.

{
"delivery": "local",
"on_enter": {
"title": "Arrived",
"body": "Welcome to HQ.",
"importance": "high",
"deep_link": "myapp://site/hq",
"data": {"site": "hq"}
}
}
MemberRequiredRule
deliveryyeslocal (the device shows it) or cloud (reserved; the device shows nothing).
on_enterone of the twoContent for entering. Needs notify_on_entry: true.
on_exitone of the twoContent for leaving. Needs notify_on_exit: true.
….titleyesA string of at most 100 characters.
….bodyyesA string of at most 500 characters.
….importancenohigh or default. Left out, devices treat it as high.
….deep_linknoA string of at most 2048 characters, handed to your app on tap.
….datanoA flat object of string values: at most 10 entries and 2048 bytes of keys and values.

Anything that breaks these rules is 400 invalid_notification. Send null or leave notification out for no notification.

Two members set how the server judges a fence in the two cases where a device’s locations alone can’t show a crossing. Both are optional on input and always present on output.

MemberValuesDefaultWhat it does
pass_throughoff, onoffWith on, a device that crosses the fence between two locations, with neither location inside, still produces a geofence.enter and a geofence.exit, both with evidence: interpolated. Use it for small fences on roads, where a vehicle can be inside for less time than between two locations.
on_unreachablenone, exitnoneWhat happens when a device confirmed inside the fence becomes unreachable. none: nothing is sent, and the device’s visit becomes unverified. exit: Beekon sends a geofence.exit with evidence: unreachable, no location, and occurred_after set to the device’s last location inside.

Absent or null means the default. On a PUT, leaving one out resets it to the default. Any other value is 400 invalid_body. The fence’s policies stay on the server: devices never receive them.

A device’s state in a fence is outside, inside or unverified, the same words the console uses. Under on_unreachable: none, a visit becomes unverified when the device becomes unreachable, and stays unverified until the device’s next location: it is still counted as inside, but no dwell is sent for it, and it does not count as something in progress for presence events. The device’s next location settles it. A location clearly inside sends nothing, and the visit continues. A location clearly outside is judged as an exit by the usual rules. A device.reachable alone does not settle it, because it carries no location. After an unreachable exit, the device’s next confirmed inside location starts a new visit with a new geofence.enter.

A fence that keeps both defaults never produces interpolated or unreachable events, so every event for it has a location.

Each plan sets three geofence limits for a project:

error (409)When
quota_fencesA create would exceed the plan’s number of geofences per project. Deleting a geofence frees a slot.
quota_verticesThe geometry has more distinct vertices (all rings of all parts, after normalisation) than the plan allows.
quota_areaThe geometry’s area (holes subtracted; a circle is πr²) is larger than the plan allows.

A PUT is checked against the vertex and area limits, never the count.

The values depend on your plan. The default vertex limit is 1,000.

The vertex limit is checked before the self-intersection and hole checks, which are the expensive part of validation. A geometry over the limit is 409 quota_vertices even if it also crosses itself; the cheaper checks (shape, coordinate range, ring size, antimeridian) still come first and answer 400. On a PUT to an unknown id, 404 not found still comes before quota_vertices.

The server is the only judge of a crossing. It reads each device’s admitted locations in recorded order, per geofence, and needs clear evidence before it says the device crossed. Gated locations (mock, inaccurate or impossible) are never evaluated.

Which side a location is on. A location counts only when it is clearly on one side: its distance from the fence’s boundary must be at least 20 m or its own reported accuracy, whichever is larger (the location’s required distance). A location closer to the boundary than that is ignored for this fence: it neither enters, exits, nor cancels anything. A location with no accuracy needs the 20 m alone.

When a crossing is confirmed.

RuleWhat it means
A moving device confirms on one location.A location is moving when the device reports a moving activity (walking, running, cycling or driving), or when each of the device’s last two steps covered at least 25 m (or twice the larger accuracy of its two locations, if that is more) at 1 m/s or faster. An enter confirms on the first clear inside location that is moving. An exit is stricter: it confirms on a moving location at least twice its required distance outside (40 m with the 20 m floor).
Otherwise, a second location 10 seconds later.The first clear location on the new side starts the crossing; the next clear location on the same side, recorded at least 10 seconds after it, confirms it. A clear location back on the old side in the meantime cancels it. The 10 seconds only rule out a repeated location; there is no other wait.
The device’s own report can confirm at once.When the SDK reports a crossing in the same upload, an admitted location within 120 seconds of it (on the device’s clock) that does not contradict it confirms the crossing there, with evidence: corroborated. For an enter, that is the earliest such location not clearly outside, and only if no later one in the window is clearly outside; for an exit, the latest location in the window, and only if it is not clearly inside. A device report never confirms anything alone, never overrides a location clearly on the other side, and never makes a gated location count.
A device starts outside every fence.Its first confirmed inside is a geofence.enter, even when the device was already inside when it began sending locations.

A confirmed enter or exit has evidence: track (or corroborated), its occurred_at is the confirming location’s recorded time, and that location is the event’s location.

Pass-through (pass_through: on only). When two consecutive locations at most 60 seconds apart are both clearly outside, and the straight line between them runs through the fence at least 10 m deeper than the larger of their two required distances, the server sends a geofence.enter and a geofence.exit with evidence: interpolated. Their occurred_at values are the instants the line goes in and comes out (sampled every 100 ms), and both carry the second location as location.

Lost contact. When a device confirmed inside becomes unreachable, the fence’s on_unreachable decides: an unverified visit and no event (none), or a geofence.exit with evidence: unreachable (exit). See Fence policies.

Dwell. A dwell fires once per visit, 5 minutes after the confirmed enter, while the device is still inside (dwell_seconds: 300): on the device’s next location after that time, or within about a minute without one, so a device that went quiet inside a fence still dwells. It does not fire by itself for a visit that is unverified, or for a device that became unreachable before the 5 minutes were up.

Late locations. A location recorded before the newest one already evaluated for the device never changes its current state. Late locations up to 72 hours behind can still produce a complete visit, sent with late: true. See late locations.

Every source is evaluated alike. Locations from the SDK and locations uploaded through POST /v1/ingest are evaluated the same way. Lost contact applies only to devices running the SDK, because only they have presence.

How soon an event arrives. The server evaluates each upload right after accepting it, so in the in1 region the event follows the upload that carries the confirming location within seconds. In other regions the evaluation can wait until the region next handles traffic. Beekon’s target for a healthy device, tracking and online, is under 2 minutes from the crossing to the event. SDK 0.6.0 and later upload at once when a location crosses a fence or comes near one, and when the OS raises a geofence alert (see Near a fence). With SDK 0.5.0 only the OS alert does that; otherwise the event follows the crossing by up to the upload interval: 5 minutes by default (sync.interval_seconds: 300, never shorter than 60 seconds), on screen or in the background. Set sync.sync_threshold to upload sooner. Each event’s detected_at shows when the server produced it.

Known limits.

  • A dead or force-stopped phone can’t be located. No design can say where a phone is once it stops sending. The server’s answer is that the device is unreachable, once its deadline passes (minutes for a moving device on SDK 0.6.0 or later, 12 hours by default otherwise), and the fence’s on_unreachable decides what you hear.
  • An iOS app the user force-quits may send nothing. iOS does not relaunch it for a fence, so there may be no location to judge, and the decision falls to presence as above.
  • A faked location on a rooted or jailbroken device can pass the mock-location gate and is judged like any other track. evidence: track says what the server concluded from the locations it received, not that they are genuine. A location’s trust_tier says whether it came from an install that passed device attestation, and Require attestation refuses uploads from installs that haven’t, rooted Android phones among them.

These values are the same for every project today, and may be tuned. A test drive that wants an event should go well inside the fence (more than the required distance past the boundary), and a slow one should record two locations at least 10 seconds apart on each side.

StatuserrorWhen
400invalid_bodyNot one JSON object; a required member missing or null; a member of the wrong type; an unknown member; a repeated key; a pass_through or on_unreachable value that is not one of its tokens; or a body over 1 MiB.
400invalid_namename empty, only whitespace, over 200 bytes, or containing a control character.
400invalid_geometry, a geometry reason aboveBad geometry.
400invalid_notificationA notification that breaks the rules above.
400limit must be an integer in [1, 500] · invalid_cursorBad paging on the list.
401missing bearer token · invalid session tokenNo valid session.
403server credentials requiredThe token was minted from an SDK key.
403insufficient scopeThe key lacks geofences:read (reads) or geofences:write (writes).
404not foundUnknown, deleted, foreign or malformed id.
409quota_fences · quota_vertices · quota_areaA plan limit.
500internal errorA failure on our side.