Developers
IP geolocation API
Location cross-checked across multiple databases with a confidence score, ASN and provider, VPN / proxy / Tor / data-center flags and batch lookups — in one fast JSON call.
Plans
Free
Free
- 30,000 requests / month
- 30 requests / minute
- Batch up to 25 IPs
- Location, ASN, VPN / Tor / hosting flags
- IP-change monitor
Pro
Coming soon
- 500,000 requests / month
- 300 requests / minute
- Batch up to 100 IPs
- Location, ASN, VPN / Tor / hosting flags
- IP-change monitor
Business
Coming soon
- 3,000,000 requests / month
- 1,200 requests / minute
- Batch up to 100 IPs
- Location, ASN, VPN / Tor / hosting flags
- IP-change monitor
Authentication
Send your key in the Authorization: Bearer <key> header. Keys are never accepted in the URL, because URLs end up in logs and browser history.
Endpoints
| Request | Returns | Key |
|---|---|---|
GET / (curl, wget) | Your IP as plain text | No |
GET /json | Your full record | No |
GET /v1/{ip} | Full record for any IPv4 or IPv6 address | Yes |
GET /v1/{ip}/{field} | One field as plain text: country, city, region, asn, org, timezone, vpn, tor, hosting | Yes |
GET /v1/me | Your own record, counted against your key | Yes |
GET /v1/asn/{asn} | Registry details for an AS number | Yes |
POST /v1/batch | Up to your plan's batch size; body {"ips": [...]} | Yes |
GET /v1/usage | Quota used this month | Yes |
POST /v1/checkin | IP-change monitor (see below) | Yes |
Response
{
"ip": "8.8.8.8",
"version": 4,
"reserved": null,
"location": {
"city": "Mountain View", "region": "California",
"country": "US", "country_name": "United States", "continent": "North America",
"lat": 37.42, "lon": -122.08, "timezone": "America/Los_Angeles", "postal": "94043",
"confidence": 0.85, "sources_agree": 2, "sources_total": 2
},
"network": { "asn": 15169, "org": "Google LLC", "prefix": "8.8.8.0/24" },
"privacy": { "vpn": false, "proxy": null, "tor": false, "hosting": false },
"meta": { "cached": true, "db_build": "1a2b3c4d5e" }
}
confidence is 0–1: how closely independent databases agree on the location. vpn / proxy are null when we have no data rather than a confident "no". Field names never change within /v1.
IP-change monitor
Run this from a computer or router on the network you want to watch — every 5 minutes with cron, for example. We email you when the public IP changes.
curl -X POST -H "Authorization: Bearer ipc_xxxxxx_…" \
-d "label=Home office" https://v4.ipclarify.com/v1/checkin
Errors and limits
Errors always look like {"error": {"code": "invalid_ip", "message": "…"}}. Every response includes RateLimit-Limit, RateLimit-Remaining and X-Quota-Remaining. Going over the per-minute limit returns 429 with Retry-After.
| Status | Code | Meaning |
|---|---|---|
| 401 | missing_key / invalid_key | No key, or a revoked one |
| 422 | invalid_ip | Not a valid IPv4 or IPv6 address |
| 404 | unknown_field | Field name not recognized |
| 429 | rate_limited / quota_exceeded | Slow down, or wait for the monthly reset |