Circular geofence check

It calculates the great-circle distance with the haversine formula, compares that distance with the radius in meters, and returns a signed margin that shows how much room remains. A positive margin means the point is inside, zero marks the boundary, and a negative margin reports how far outside the point lies. The calculation is deterministic and needs no map service, device lookup, or network request.

Define the point, center, and radius clearly

A circular geofence has three essential parts: a center latitude, a center longitude, and a non-negative radius measured in meters. The separate point latitude and point longitude identify the location you want to test. Supply every coordinate in decimal degrees using the familiar WGS84 geographic ranges: latitude from minus ninety to ninety and longitude from minus one hundred eighty to one hundred eighty. Do not send projected map coordinates, degree-minute-second strings, or a radius in kilometers without converting it first. For example, a delivery area with a five-kilometer reach needs a radius_m value of 5000. The checker accepts zero as a useful radius; in that case only a point at precisely the same coordinates as the center is inside. It rejects missing values, non-finite numbers, coordinates outside their legal ranges, and negative radii instead of silently correcting a likely integration error. Longitudes on opposite sides of the antimeridian work without special client logic because the trigonometric distance formula naturally uses the shortest spherical separation.

Interpret membership, distance, and signed margin

The response contains four compact fields. The inside boolean is true when the computed distance is less than or equal to the radius, so a point exactly on the boundary belongs to the geofence. The distance_m field is the great-circle distance between the center and point on a mean-Earth sphere with radius 6,371,000 meters. The radius_m field echoes the validated fence radius, while margin_m subtracts distance from radius. That signed margin is often more useful than a boolean alone: a value of 240 means the point is inside with about 240 meters to spare, a value of zero means it is on the edge, and a value of minus 85 means it is about 85 meters outside. Output distances are rounded to six decimal places for stable serialization, but the inside decision uses the full unrounded calculation. This avoids a displayed rounded value changing the true comparison. For routing or billing policies, choose any operational buffer before calling or compare the returned margin with your own safety threshold.

Use the result safely in real geofence workflows

Circular checks are a practical fit for arrival detection, delivery eligibility, nearby equipment alerts, and coarse access zones. They are not legal property boundaries and they do not account for roads, walls, elevation, building floors, or GPS uncertainty. A phone location can wander by several meters or more, so production applications commonly require repeated readings, an accuracy limit, or hysteresis before triggering an irreversible action. For example, an arrival workflow might enter only when margin_m exceeds twenty meters and exit only when it falls below minus twenty meters, preventing rapid state changes near the edge. The spherical haversine model is consistent and fast across the globe, including near the poles and antimeridian, but it is an approximation rather than an ellipsoidal survey calculation. Run the same inputs again and the output is identical because the solver uses no network, current time, random number, or external map database. Browser execution is available for interactive checks, while automated API requests cost $0.002 each. Store the original coordinates alongside the result if later audits must explain which reading produced a decision.