IP Lens HTTP API

Get the current IP

GET /api/ip

curl "https://iplens.me/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 or domain

GET /api/ip-lookup?ip=example.com

Accepts public IPv4, IPv6 or a domain. Domains are resolved server-side, private/local answers are discarded, and public IPv4 is preferred before IPv6. Each caller is limited 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 120 requests per rolling 10-minute window. A full test runs about 8 seconds per direction with 4 parallel streams and stops early at 100 MiB download / 50 MiB upload.

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 120 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 150 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 traffic statistics

GET /api/stats/summary?days=30

Use HTTP Basic Auth with the admin username and password from config.php. Results contain aggregate traffic plus up to 20 distinct human identities and 20 bot-name/IP identities. Exact IPs are returned only when encrypted identity storage is enabled and the request is authenticated. Identity rows never include visited URLs, a full User-Agent, encryption keys or ciphertext.

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); });