⌘ K
Support

GeoNest - Location-Based Services

GeoNest

GeoNest lets you trigger campaigns based on real-world location — whether that's your mobile app using native device geofencing, or your website alerting visitors through the browser. Pick the tab that matches what you're integrating.

Overview

GeoNest for mobile apps is a REST API–based geofencing system. Your app talks to three GeoNest endpoints and uses your device's native Android/iOS geofencing to detect movement — GeoNest handles the campaign logic (dates, active hours, cooldown) once an event comes in.

To get your API key, open the GeoNest menu, click API & Integrations for your app, then switch to the App Push tab — your API key is shown there, ready to copy.

Base URL
https://www.leadnest.ai/api
Your API Key

This is unique for each app — don't reuse it on a different app.

vtyvjykjhoijlkjlfjwijlowebhwytryugi-example

To get your API key, open the GeoNest menu, click API & Integrations for your app, then switch to the App Push tab — your API key is shown there, ready to copy.

How It Works

Your App                          GeoNest
   │                                 │
   ├── POST /register ─────────────▶ │  (once, on app start)
   ├── GET  /geofences ────────────▶ │  (fetch active fences + rules)
   │                                 │
   │  Native OS geofencing detects
   │  ENTER / DWELL / EXIT
   │                                 │
   ├── POST /geofence/event ───────▶ │  Validates dates/hours/cooldown
                                     │  → Sends Email / SMS / App Push 

Step 1 — Register the Device

Call this once when the app starts, and again if the device's info changes.

Endpoint: POST /register

Request body
{
    "app_api_key": "YOUR_API_KEY",
    "device_id": "30b43ehjmed21a89970",
    "device_timezone": "Asia/Kolkata",
    "email": "user@example.com",
    "fcm_token": "FCM_DEVICE_TOKEN",
    "latitude": 17.4231737,
    "longitude": 78.4624177,
    "phone": "+911234567890",
    "platform": "android/ios"
}
FieldRequiredDescription
app_api_keyYesYour app's API key
device_idYesUnique device identifier
fcm_tokenYesPush notification token
platformYesandroid or ios
latitude / longitudeNoCurrent location
email / phoneNoUsed to match a known contact for campaigns
device_timezoneNoUsed for active-hours checks
Response
{ "success": true, "message": "Device registered successfully." }

Step 2 — Fetch Geofences

Call this after registering, and whenever the app wants a fresh copy of active fences — GeoNest only returns fences that are currently active.

Endpoint: GET /geofences?app_api_key=YOUR_API_KEY

Response
{
    "success": true,
    "count": 1,
    "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"
        }
    ]
}

Register every fence you receive directly with native geofencing (GeofencingClient on Android, CLCircularRegion on iOS). For a polygon fence, use lat/lng/radius_m as the OS wake-up region, then check polygon_geojson for the exact shape once the OS fires — the circle is only an approximation for the wake-up trigger.

Field reference
FieldMeaning
geofence_idSend this back when reporting an event
shapecircle or polygon
radius_mDirect radius for circle; wake-up radius for polygon
polygon_geojsonExact shape — only present when shape = polygon
event_typeenter, dwell, or exit
cooldown_minutesMinimum gap between repeat triggers for the same device

Step 3 — Report a Geofence Event

Call this when native geofencing detects an ENTER, DWELL, or EXIT.

Endpoint: POST /geofence/event

Request body
{
    "app_api_key": "YOUR_API_KEY",
    "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."
}
Field reference
FieldRequiredDescription
geofence_idYesID returned by /geofences
eventYesenter, dwell, or exit
occurred_atNoISO-8601 with timezone — recommended

Rules to Follow

  • Never hardcode geofences — always fetch fresh from /geofences so changes in the dashboard don't need an app release.
  • Reuse the same device_id everywhere for a given device.
  • Use the exact geofence_id from /geofences — don't generate your own.
  • Send a real occurred_at timestamp — GeoNest uses it for active-hours and date checks.
  • Queue failed events locally and retry once the device is back online.
GeoNest cannot detect location or trigger campaigns on its own — a campaign stays dormant until your app completes all three steps above: register, fetch, and report.

Frequently Asked Questions

Where do I get my API key?

It's shown above, in the box under "Your API Key" — it's unique to this app and already correct for every example on this page.

My geofence event isn't triggering a campaign — why?

Check these first, in order: is the campaign's status active, does today's date fall within its start/end range, is the current time within its active hours, and has the cooldown period already passed since the last send to this device?

Do I need to call /register every time the app opens?

Only when something changes — a new FCM token, a different device, or updated contact info. Calling it again with the same data is harmless, just unnecessary.

What happens if a geofence is a polygon?

Register the provided circle (lat/lng/radius_m) with native geofencing as the wake-up trigger, then check the device's position against polygon_geojson once that wake-up fires — the circle alone is only an approximation.

Can I test this without a real mobile app?

Yes — all three endpoints are plain REST APIs, so tools like Postman or curl work for testing the request/response shape before wiring up native code.

Is this the same as Web Push?

No — this tab is for a native iOS/Android app using device-level geofencing. If you want location alerts on your website instead, see the Web Push tab.

See It in Action

What is GeoNest Web Push?

GeoNest Web Push lets your website send a browser notification to visitors when they're near, inside, or spending time around a location you choose — a store, an event, a neighborhood. No app download needed. The visitor just needs to visit your site once and say yes to two quick prompts.

This is separate from the App Push tab. If you also have an iOS/Android app, that's its own setup — this tab is only for your website.

What You'll Need to Add to Your Site

Two small files, added once by whoever manages your website. No coding knowledge needed beyond pasting a snippet.

1. Download this file and upload it to your website

Upload it to the main folder of your site — not inside any subfolder.

geo-sw.js Download
2. Paste this snippet into your website's <head>
<script src="https://www.leadnest.ai/storage/geo.js" data-app-key="y" data-vapid-key="YOUR_VAPID_KEY"></script>

To get your snippet , Open the GeoNest menu, click API & Integrations for your app, then switch to the Web Push tab. The snippet shown there already has your API key and VAPID key filled in — just copy and paste it, no need to find either key separately.

That's it — once both are live on your site, GeoNest Web Push is ready. No further setup is needed per page; the same snippet works site-wide.

How It Works for Your Visitors

Visitor opens your website
            │
            ▼
A small banner appears: "Enable location alerts?"
            │
            ▼
Visitor clicks "Enable" (one time only)
            │
            ▼
Browser asks: Allow notifications? → Allow location?
            │
            ▼
Done — GeoNest now watches for nearby geofences
            │
            ▼
Visitor enters/stays near a location you set up
            │
            ▼
They receive a push notification in their browser

Returning visitors who already said yes won't see the banner again — it only appears once, the first time.

The visitor's browser tab needs to stay open for location alerts to work. This is a browser rule, the same for every website — not something specific to GeoNest.

Important: This Only Works While the Tab Is Open

Web Push geofencing relies on the visitor's browser checking their location — unlike a mobile app, a website has no way to keep running once the visitor navigates away or closes it. Set the right expectations with your team using these rules:

Visitor's situationWill they get notified?
Tab is open and active (they're browsing your site right now)Yes — this is when detection works
Tab is open but minimized, or they switched to another tabUsually yes — most browsers still check location in a background tab, just less frequently
Tab is closedNo — nothing runs once the tab is gone
Browser itself is closed, or the device is asleep/lockedNo — same reason as above
They visited yesterday, haven't been back sinceNo — only an open visit counts; there's no stored "last known location" that keeps triggering campaigns on its own
This is a browser platform rule, not a GeoNest limitation. No website — from any provider — can track a visitor's location after they've closed the tab. If you need alerts to keep working after someone leaves your site, that requires a native mobile app with GeoNest's App Push integration instead (see the App Push tab).

In practice, this makes Web Push best suited for "while they're actively on my site" moments — for example, someone browsing a store locator page who happens to be standing near one of your locations right then, or a visitor exploring an event map while the event is happening.

Setting Up a Campaign

Once the snippet is live, go to GeoNest → Geofence in your dashboard to draw an area on the map and choose what message to send. Under Channels & Followup, turn on Website Visitors (Web Push) and pick (or create) the notification to send.

Frequently Asked Questions

Why didn't the visitor see the notification?

Check a few common reasons first: they haven't clicked "Enable" yet, they closed the tab, or the geofence's active hours / start-end dates don't currently cover this moment.

Can I use this alongside my mobile app's GeoNest setup?

Yes — Web Push and the mobile app integration run independently. A visitor on your website and the same person using your app are treated as two separate devices.

Does this cost extra?

Web push notifications use their own credit allowance, separate from your other notification channels — check your plan's usage page for the current balance.

What if a visitor blocks the location prompt?

There's no way to ask again automatically — they'd need to re-enable location for your site in their own browser settings.

See It in Action

Watch a short walkthrough of setting up Web Push and creating your first location-based campaign.

Coming Soon Features

We're constantly working on new features to help you scale your communications. Here's what's currently in development:

AI Lead Scoring
Predictive Optimization
Multi-language Bots
Expanded CRM Sync

Need Help Getting Started?

Book a personalized demo with our team and discover how LeadNest can transform your communication strategy.

Contact Support