GeoPulse API Documentation

Welcome to GeoPulse – the simplest way to add IP geolocation and traffic intelligence to your applications. This documentation covers everything from embedding our tracking script to using the REST API.

Overview

GeoPulse provides two main services:

Tracking script – lightweight JavaScript snippet that records visitor data (location, device, referrer, UTM) to your dashboard.
REST API – programmatic IP geolocation (country, city, ISP, ASN, coordinates) with rate limiting and monthly quotas.

All data is privacy‑friendly: IP addresses are hashed before storage, and you own your data completely.

Quick start

Create a free account (no credit card required).
Add your first site – enter your domain (e.g., example.com).
Copy the tracking script from the site details page and paste it into your website’s <head>.
Visit your dashboard to see real‑time data.

💡 Tip: You can also use the API immediately – generate an API key from the API Keys page.

Tracking script

Add this script to every page you want to track (replace YOUR_SITE_KEY with your actual site key):

<script src="https://skrslinks.site/geopulse/tracker.js" data-site="YOUR_SITE_KEY" defer></script>

The script automatically captures:

Page URL and referrer
Device type (mobile/tablet/desktop)
Browser and operating system
UTM parameters (source, medium, campaign)
Geolocation (country, city, ISP, ASN) via IP

No extra configuration – just drop the script and go. The script loads asynchronously and won’t slow down your site.

API introduction

Our REST API returns geolocation data for any public IPv4 address. It’s designed to be simple, fast, and secure.

Base URL: https://skrslinks.site/geopulse/api/geo.php

Authentication

All API requests require a valid API key. Pass it as a query parameter:

GET /geo.php?api_key=YOUR_API_KEY&ip=8.8.8.8

You can create and manage API keys from your API Keys page. Keep your key secret – if compromised, regenerate it immediately.

Endpoints

Method	Endpoint	Description
GET	`/geo.php?api_key=KEY&ip=IP`	Returns geolocation for the given IP address.

Required parameters:

api_key – your valid API key.
ip – a public IPv4 address (e.g., 8.8.8.8).

Response format

All responses are in JSON. A successful lookup returns:

{
  "ip": "122.162.149.4",
  "country": "India",
  "city": "New Delhi",
  "latitude": 28.6327,
  "longitude": 77.2198,
  "isp": "Bharti Airtel Ltd., Telemedia Services",
  "asn": 24560
}

If the IP cannot be geolocated (e.g., private IP or missing database entry), fields may be empty or zero.

Error codes

HTTP Code	Meaning
400	Missing or invalid parameters (e.g., missing IP)
403	Invalid or inactive API key
405	Method not allowed (use GET only)
429	Rate limit exceeded (per‑second or monthly)
500	Internal server error (e.g., GeoIP database unavailable)

Error responses always include an error field with a description.

Rate limits

Two types of limits apply:

Per‑second limit: 5 requests per second per IP address. Exceeding returns 429.
Monthly limit: Depends on your plan (Free: 1,000, Pro: 10,000, Business: 100,000).

Check your current usage in the API Analytics page. Limits reset on the first day of each month.

cURL example

curl "https://skrslinks.site/geopulse/api/geo.php?api_key=YOUR_API_KEY&ip=8.8.8.8"

JavaScript (fetch)

fetch('https://skrslinks.site/geopulse/api/geo.php?api_key=YOUR_API_KEY&ip=8.8.8.8')
  .then(res => res.json())
  .then(data => console.log(data))
  .catch(err => console.error(err));

Python

import requests
response = requests.get('https://skrslinks.site/geopulse/api/geo.php', params={
    'api_key': 'YOUR_API_KEY',
    'ip': '8.8.8.8'
})
print(response.json())

PHP

$data = file_get_contents('https://skrslinks.site/geopulse/api/geo.php?api_key=YOUR_API_KEY&ip=8.8.8.8');
$result = json_decode($data, true);
print_r($result);

Webhooks

GeoPulse can send real‑time notifications for specific events (e.g., new visit, bot detection). Configure webhooks from your dashboard. Each webhook must include a secret for signature verification.

Example payload for a new visit:

{
  "event": "visit.created",
  "site_id": 123,
  "data": {
    "country": "India",
    "city": "Mumbai",
    "device": "mobile"
  }
}

Batch API

For high‑volume lookups, use our batch endpoint (contact support to enable). Send up to 100 IPs per request:

POST /api/v1/geo/batch
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "ips": ["8.8.8.8", "1.1.1.1", "122.162.149.4"]
}

Best practices

Cache responses – IP geolocation rarely changes. Cache results for at least 24 hours to reduce API calls.
Handle errors gracefully – Always implement fallback logic when the API returns 4xx/5xx.
Rotate API keys – Regenerate keys periodically and never hardcode them in client‑side code.
Monitor usage – Use the analytics dashboard to avoid hitting monthly limits unexpectedly.

Dashboard features

The main dashboard gives you an aggregated view of all your sites:

Total visits and unique visitors
Visits over time (interactive line chart)
Device breakdown (mobile, desktop, tablet)
Interactive world map with clustered visitor locations
Traffic Quality Score (0‑100) based on hosting traffic, repeat visitors, and bot percentage

Sites management

Each site you add gets its own detail page where you can view:

Top pages (with popularity progress bars)
Traffic sources (referrers and direct traffic)
UTM campaign performance
Top countries (with flag emojis and percentage bars)
Recent visits (with country, city, browser, OS, referrer)

Analytics & exports

You can export visit data as CSV from each site’s detail page (coming soon). For programmatic access, use the REST API or contact support for custom exports.

Frequently asked questions

How accurate is the geolocation?

We use MaxMind GeoLite2 databases. City‑level accuracy is typically 80‑90%, country‑level >99%.

Does the tracking script set cookies?

Only for session tracking (to identify unique visitors). No third‑party cookies.

What happens if I exceed my monthly limit?

API requests will return 429. Dashboard tracking continues but may be aggregated. Upgrade your plan to increase limits.

Can I use GeoPulse for commercial projects?

Yes, our Pro and Business plans are designed for commercial use. The Free plan is for small projects and testing.

How do I delete my data?

You can delete individual sites (and all associated visits) from the site details page. For account deletion, contact support.

Need help?

Our support team is available Monday–Friday, 9am–6pm IST. Reach out via:

Email: support@geopulse.io
Live chat (bottom right corner)
Contact form

✨ Pro tip: Check the system status page for real‑time uptime and maintenance schedules.