IP Lens HTTP API

Get the current IP

GET /api/ip

curl "/api/ip"

Returns the address that reached the server, IP version, protocol and HTTPS status. Add ?enrich=1 to request approximate network metadata.

Look up an IP address

GET /api/ip-lookup?ip=8.8.8.8

Accepts public IPv4 or IPv6 addresses only, validates input and limits each caller to 30 requests per minute.

Review network signals

GET /api/network-risk

Returns cached network metadata and conservative VPN, proxy or hosting signals. The result includes a confidence level and must not be treated as proof.

Health and Internet Speed Test

GET /api/health verifies database and storage. GET /api/ping supports latency and jitter sampling.

GET /api/speed?bytes=N returns binary application/octet-stream with an exact Content-Length. Numeric values are converted to integers and clamped to 64 KB–8 MB (65,536–8,388,608 bytes); missing or nonnumeric values default to 262,144 bytes. The limit is 60 requests per rolling 10-minute window. A fast full test can consume up to three download samples.

POST /api/speed-upload accepts only application/octet-stream, up to 4 MB (4,194,304 bytes), reads bounded chunks and returns JSON {"ok":true,"bytes":N}. The limit is 10 requests per rolling 10-minute window. Downloads and uploads use separate HMAC keys derived from the caller's IP.

A wrong method returns HTTP 405, an unsupported upload content type returns 415, an oversized upload returns 413 and an exceeded limit returns 429. Responses use Cache-Control: private, no-store, max-age=0 and X-Content-Type-Options: nosniff.

Each user-started adaptive run transfers at most approximately 15.25 MiB, excluding headers and ping responses. Results measure the route to the IP Lens server, may be below the ISP's advertised speed and do not certify a plan's speed. Payloads are processed transiently; the application does not persist payloads or results in its database, analytics, cache or application-controlled logs. Only expiring HMAC request-limit records are stored for abuse prevention.

Private aggregate statistics

GET /api/stats/summary?days=30

Use HTTP Basic Auth with the admin username and password from config.php. Results contain total views, human visitor-days, pages viewed, bot views and rates, bot families/categories, and daily and per-URL human/bot statistics. Top countries, browsers, operating systems, devices, locales and referrers describe human traffic only. Recent activity is limited to masked visitor/device or normalized bot identity fields and never includes its page path, a full IP, full User-Agent or visitor key.

Approximate weather

GET /api/weather?lang=en

Returns current conditions for the approximate IP location when WeatherAPI.com is enabled and configured server-side.

JavaScript example

fetch('/api/ip-lookup?ip=8.8.8.8')
  .then(function (response) { return response.json(); })
  .then(function (data) { console.log(data.ip, data.network); });