GeoNest - Location-Based Services

Overview

GeoNest is a REST API–based geofencing system. The mobile app talks to three GeoNest APIs and uses the device's native Android/iOS location and geofencing capabilities to detect movement.

Base URL

API Key Example-

To get your API key, go to All Apps from the menu, find your app, and copy the API Key shown in the app list.

Integration Flow

Mobile App
    │
    ├── 1. Register Device        → POST /register
    ├── 2. Get Geofences          → GET  /geofences
    │
    ▼
Native Android/iOS Geofencing
    │
    │  detects ENTER / DWELL / EXIT
    ▼
3. Send Geofence Event           → POST /geofence/event
    │
    ▼
GeoNest Backend → Campaign Processing → Email / SMS / Push / WhatsApp

API 1 — Register Device

Registers the device with GeoNest. Call this on app start / when device info changes.

Endpoint: POST /register

Request Body

{
    "app_api_key": "gnk_live_7f3a9c2e1b8d4f6a",
    "device_id": "30b43ehjmed21a89970",
    "device_timezone": "Asia/Kolkata",
    "email": "user@example.com",
    "fcm_token": "FCM_DEVICE_TOKEN",
    "latitude": 17.4231737,
    "longitude": 78.4624177,
    "phone": "",
    "platform": "android/ios"
}

Response

{ "success": true, "message": "Device registered successfully." }

API 2 — Get Geofences

Fetches all geofences and campaign rules configured for the app.

Endpoint: GET /geofences?app_api_key=gnk_live_7f3a9c2e1b8d4f6a

Response

{
    "success": true,
    "count": 2,
    "data": [
        {
            "campaign_id": 1,
            "geofence_id": 1,
            "name": "Madhapur Store",
            "shape": "circle",
            "lat": 17.4483,
            "lng": 78.3915,
            "radius_m": 200,
            "polygon_geojson": null,
            "event_type": "dwell",
            "dwell_minutes": 5,
            "cooldown_minutes": 720,
            "start_date": "2026-07-28",
            "end_date": "2026-08-06",
            "active_hours_start": "09:00:00",
            "active_hours_end": "21:00:00",
            "timezone": null,
            "updated_at": "2026-07-28 09:43:10"
        },
        {
            "campaign_id": 2,
            "geofence_id": 5,
            "name": "Bizonic tech",
            "shape": "polygon",
            "lat": 17.4202825,
            "lng": 78.4596698,
            "radius_m": 105,
            "polygon_geojson": [
                { "lat": 17.420617722, "lng": 78.459492729 },
                { "lat": 17.41996257, "lng": 78.458843635 },
                { "lat": 17.419737361, "lng": 78.45985751 },
                { "lat": 17.420146832, "lng": 78.460495875 },
                { "lat": 17.420827575, "lng": 78.460211561 }
            ],
            "event_type": "enter",
            "dwell_minutes": 0,
            "cooldown_minutes": 360,
            "start_date": "2026-07-28",
            "end_date": "2026-08-06",
            "active_hours_start": "09:00:00",
            "active_hours_end": "02:00:00",
            "timezone": null,
            "updated_at": "2026-07-28 09:45:52"
        }
    ]
}

For a circle fence, lat/lng is the center and radius_m is the monitoring radius — use these directly with native geofencing.

For a polygon fence, lat/lng/radius_m is the auto-computed bounding circle (used to register the OS-level wake-up region), and polygon_geojson is the precise shape — use it for an in-app point-in-polygon check once the OS wake-up fires, since the circle is only an approximation.

Key Fields

The API only returns fences that are currently active, so the app can register everything it receives directly with the native geofencing APIs (GeofencingClient on Android, CLLocationManager/CLCircularRegion on iOS) — the backend still re-validates status when an event comes in.

API 3 — Send Geofence Event

Call this when the native OS detects an ENTER, DWELL, or EXIT event.

Endpoint: POST /geofence/event

Request Body

{
    "app_api_key": "gnk_live_7f3a9c2e1b8d4f6a",
    "device_id": "30b43ehjmed21a89970",
    "geofence_id": 1,
    "event": "dwell",
    "latitude": 17.4230194,
    "longitude": 78.462362,
    "occurred_at": "2026-08-01T10:30:00+05:30"
}

Response

{
    "success": true,
    "message": "Geofence event processed successfully.",
    "data": { "event_id": 1, "campaign_id": 1 }
}

Supported Events

• enter — device enters the geofence
• dwell — device stays inside for the configured dwell_minutes
• exit — device leaves the geofence

Recommended Mobile App Flow

App Start
   │
   ▼
Request Location Permission
   │
   ▼
POST /register
   │
   ▼
GET /geofences
   │
   ▼
Register active fences with native
Android/iOS geofencing
   │
   ▼
Wait for ENTER / EXIT / DWELL
   │
   ▼
POST /geofence/event
   │
   ▼
GeoNest processes campaign

Backend processing on event received:

Validate API key → Validate device → Validate geofence
   → Check campaign status → Check date/active hours
   → Check cooldown → Dispatch channel (Email/SMS/Push/WhatsApp)

Implementation Rules

1. Never hardcode geofences. Always fetch from GET /geofences so fences can be updated from the dashboard without an app release.
2. Reuse the same device_id from registration when sending events.
3. Use the exact geofence_id returned by /geofences — don't generate your own.
4. Only register active fences (status = active, geofence_status = active). The backend re-validates on event receipt regardless.
5. Send the real event timestamp in occurred_at (ISO-8601, with timezone).
6. Retry failed events. If the device is offline when an event fires, queue it locally and retry once connectivity returns.

API Summary

Base URL

Architecture

┌─────────────────────────────┐
│     Android / iOS App       │
│  Native Location/Geofencing │
└──────────────┬───────────────┘
               │ REST API
               ▼
┌─────────────────────────────┐
│      GeoNest API Layer      │
│  POST /register             │
│  GET  /geofences             │
│  POST /geofence/event        │
└──────────────┬───────────────┘
               ▼
┌─────────────────────────────┐
│    GeoNest Campaign Engine   │
│  Campaign · Geofence · Event │
│  Cooldown · Active Hours     │
└──────────────┬───────────────┘
               ▼
      Email / SMS / Push / WhatsApp

See GeoNest in Action

Once your app is integrated, head over to GeoNest in your dashboard to create your first geofence and campaign. Watch the walkthrough below to see the full setup and how it works end to end.