WhoIR API Documentation

Lightweight Geo IP API. All endpoints have a rate limit of 60 RPM.

Base Endpoints

/json — Get general info in JSON
/xml — Get general info in XML
/text — Plain text response
/yaml — YAML format

IP Lookup

Replace {IP} with IPv4/IPv6 or {domian} name:

/json/{IP} or /json/{domain}
/xml/{IP} or /xml/{domain}
/text/{IP} or /text/{domain}
/yaml/{IP} or /yaml/{domain}

Example Requests

curl whoir.com

curl whoir.com/google.com

curl https://whoir.com/json/8.8.8.8

curl https://whoir.com/json/google.com

curl https://whoir.com/xml/2001:4860:4860::8888

curl https://whoir.com/xml/ipv6.google.com

curl https://whoir.com/text/1.1.1.1

curl https://whoir.com/text/one.one.one.one

curl https://whoir.com/yaml/2606:4700:4700::1111

curl https://whoir.com/yaml/one.one.one.one

Response Example (JSON)

{
  "service": "WhoIR (whoir.com)",
  "status": "success",
  "query": "8.8.8.8",
  "country": "United States",
  "countryCode": "US",
  "lat": 37.751,
  "lon": -97.822,
  "timezone": "America/Chicago",
  "isp": "Google LLC"
}

Stats API

Get service metrics: latency, requests, runtime, uptime and version.

curl https://whoir.com/api/stats


  {
    "latency": {"avg_ms":0.1,"p50_ms":0,"p95_ms":0,"p99_ms":0},
    "requests": {"by_country":{},"by_endpoint":{},"in_flight":1,"rps":0.41,"total":0},
    "runtime": {"goroutines":13,"heap_mb":1.13,"rss_mb":0},
    "uptime_seconds":42,
    "version":"1.0.0"
  }

Live API

Real-time service data: average latency, RPS, and in-flight requests.

curl https://whoir.com/api/live


  data: {"avg_latency_ms":0.07316983807442994,"in_flight":0,"rps":0.6449910942951639} 
  data: {"avg_latency_ms":0.06985322065647066,"in_flight":0,"rps":0.5260456362046302}
  data: {"avg_latency_ms":0.8192236976506639,"in_flight":0,"rps":0.21}
  data: {"avg_latency_ms":0.8197342185903983,"in_flight":0,"rps":0.10289999999999999}
  data: {"avg_latency_ms":0.8199843738508681,"in_flight":0,"rps":0.05042099999999999}
  data: {"avg_latency_ms":0.8201069499284983,"in_flight":0,"rps":0.024706289999999992}
  data: {"avg_latency_ms":0.8201670122065371,"in_flight":0,"rps":0.012106082099999995}

Rate Limits

All endpoints are limited to 60 requests per minute. Excessive requests will return HTTP 429.

Try it live

Insert IP/Domain or leave blank for your own:

Result will appear here...