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
{
"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"
}
| Field | Required | Description |
|---|---|---|
app_api_key | Yes | Your app's API key |
device_id | Yes | Unique device identifier |
fcm_token | Yes | Push notification token |
platform | Yes | android or ios |
latitude / longitude | No | Current location |
email / phone | No | Used to match a known contact for campaigns |
device_timezone | No | Used for active-hours checks |
{ "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
{
"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
| Field | Meaning |
|---|---|
geofence_id | Send this back when reporting an event |
shape | circle or polygon |
radius_m | Direct radius for circle; wake-up radius for polygon |
polygon_geojson | Exact shape — only present when shape = polygon |
event_type | enter, dwell, or exit |
cooldown_minutes | Minimum 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
{
"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"
}
{
"success": true,
"message": "Geofence event processed successfully."
}
Field reference
| Field | Required | Description |
|---|---|---|
geofence_id | Yes | ID returned by /geofences |
event | Yes | enter, dwell, or exit |
occurred_at | No | ISO-8601 with timezone — recommended |
Rules to Follow
- Never hardcode geofences — always fetch fresh from
/geofencesso changes in the dashboard don't need an app release. - Reuse the same
device_ideverywhere for a given device. - Use the exact
geofence_idfrom/geofences— don't generate your own. - Send a real
occurred_attimestamp — GeoNest uses it for active-hours and date checks. - Queue failed events locally and retry once the device is back online.
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.
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.
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 situation | Will 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 tab | Usually yes — most browsers still check location in a background tab, just less frequently |
| Tab is closed | No — nothing runs once the tab is gone |
| Browser itself is closed, or the device is asleep/locked | No — same reason as above |
| They visited yesterday, haven't been back since | No — only an open visit counts; there's no stored "last known location" that keeps triggering campaigns on its own |
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:
Need Help Getting Started?
Book a personalized demo with our team and discover how LeadNest can transform your communication strategy.