API Documentation

Base URL: https://api.ipconf.me · Format: application/json

IP lookup endpoints are free with no signup and CORS-enabled, so you can call them directly from a browser. Network-tool endpoints require an X-Client-Key header — the key exists for fair-use rate limiting only, not access control.

Quick start

# Your current IP
curl https://api.ipconf.me/api/ip

# Any IP, in Chinese
curl "https://api.ipconf.me/api/ip/8.8.8.8?lang=zh"

# A network tool (requires key)
curl -X POST https://api.ipconf.me/api/tools/dns \
  -H "Content-Type: application/json" \
  -H "X-Client-Key: YOUR_KEY" \
  -d '{"target": "google.com", "type": "A"}'

Authentication

IP endpoints (/api/ip, /api/ip/{ip}, /api/stats) need no auth. Tool endpoints (/api/tools/*) require a client key in the header:

X-Client-Key: <your key>

The key is visible to anyone who inspects the network tab of your frontend — that's expected. The real protection is per-IP rate limiting at the Cloudflare WAF layer. The key is here to identify a "client" (e.g., one website) for fair distribution of capacity, not to protect a secret. Email us via the About page for a key.

Rate limits

Endpoint group	Limit (per IP)	Notes
/api/ip	60 / min	Burstable to 80, then 429
/api/tools/dns	20 / min	Cached responses don't count toward limit
/api/tools/ping, traceroute	10 / min	Server-side process, hence stricter
/api/tools/* (other)	10 / min	SSL, WHOIS, headers, port scan, blacklist, ASN, CDN check
/api/ip/{ip}/report	10 / min	Per IP submitter

Hit a 429? Wait 60 seconds and try again. Need higher limits for production? Email us with your expected qps and we'll work out a plan.

Language parameter

All IP endpoints accept ?lang=zh for Chinese names (country/region/city/ISP). Default is en. The actual data is the same; only the localized strings differ.

IP lookup

GET /api/ip

Returns the caller's IP address with geolocation info. The server detects the caller IP from CF-Connecting-IP / X-Forwarded-For / Remote, so behind a proxy/CDN you get the real visitor IP.

Example

curl https://api.ipconf.me/api/ip
curl "https://api.ipconf.me/api/ip?lang=zh"

Response

{
  "ip": "1.2.3.4",
  "ipv4": "1.2.3.4",
  "ipv6": null,
  "country": "United States",
  "country_code": "US",
  "region": "California",
  "city": "Mountain View",
  "isp": "Google LLC",
  "asn": "AS15169",
  "timezone": "America/Los_Angeles",
  "is_china": false
}

GET /api/ip/{ip}

Returns geolocation info for a specific IPv4 or IPv6 address. Same response schema as /api/ip.

Example

curl https://api.ipconf.me/api/ip/8.8.8.8
curl "https://api.ipconf.me/api/ip/2001:4860:4860::8888?lang=zh"

Response

{
  "ip": "8.8.8.8",
  "country": "United States",
  "country_code": "US",
  "region": "California",
  "city": "Mountain View",
  "isp": "Google LLC",
  "asn": "AS15169",
  "timezone": "America/Los_Angeles",
  "is_china": false
}

POST /api/ip/{ip}/report

Submit a correction for an IP's geolocation. We review and apply within a few hours. Pass the new fields in the JSON body; omit fields you don't want to change.

Example

curl -X POST https://api.ipconf.me/api/ip/1.2.3.4/report \
  -H "Content-Type: application/json" \
  -d '{"country":"Japan","region":"Tokyo","city":"Shibuya","isp":"NTT"}'

Response

{ "ok": true, "task_id": 12345 }

Network tools

POST /api/tools/dns 🔑 X-Client-Key required

DNS lookup. Supports A, AAAA, MX, TXT, CNAME, NS records.

Example

curl -X POST https://api.ipconf.me/api/tools/dns \
  -H "Content-Type: application/json" \
  -H "X-Client-Key: YOUR_KEY" \
  -d '{"target": "google.com", "type": "A"}'

Response

{
  "target": "google.com",
  "type": "A",
  "records": ["142.250.185.46", "142.250.185.78"]
}

POST /api/tools/ping 🔑 X-Client-Key required

Run ping from our server (Linux ping, 4 packets). Returns the raw stdout.

Example

curl -X POST https://api.ipconf.me/api/tools/ping \
  -H "Content-Type: application/json" \
  -H "X-Client-Key: YOUR_KEY" \
  -d '{"target": "google.com"}'

Response

{
  "target": "google.com",
  "output": "PING google.com ... 4 packets transmitted, 4 received ..."
}

POST /api/tools/traceroute 🔑 X-Client-Key required

Run traceroute from our server. May take 10-30s depending on the destination.

Example

curl -X POST https://api.ipconf.me/api/tools/traceroute \
  -H "X-Client-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target": "github.com"}'

Response

{ "target": "github.com", "hops": [{"n":1,"ip":"...","rtt_ms":1.2}, ...] }

POST /api/tools/ssl 🔑 X-Client-Key required

Inspect SSL certificate on port 443: issuer, subject, validity window, SANs, chain, signature algorithm.

Example

curl -X POST https://api.ipconf.me/api/tools/ssl \
  -H "X-Client-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target": "github.com"}'

Response

{
  "target": "github.com",
  "issuer": { "CN": "Sectigo ECC Domain Validation Secure Server CA" },
  "subject": { "CN": "github.com" },
  "not_before": "2025-02-05T00:00:00Z",
  "not_after": "2026-02-05T23:59:59Z",
  "sans": ["github.com", "www.github.com"]
}

POST /api/tools/http-header 🔑 X-Client-Key required

Fetch HTTP response headers (HEAD request) for a URL.

Example

curl -X POST https://api.ipconf.me/api/tools/http-header \
  -H "X-Client-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target": "https://github.com"}'

Response

{ "status": 200, "headers": { "server": "github.com", "content-type": "text/html", ... } }

POST /api/tools/whois 🔑 X-Client-Key required

WHOIS lookup for a domain or IP.

Example

curl -X POST https://api.ipconf.me/api/tools/whois \
  -H "X-Client-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target": "example.com"}'

Response

{ "target": "example.com", "raw": "Domain Name: EXAMPLE.COM ..." }

POST /api/tools/asn 🔑 X-Client-Key required

Look up the ASN (autonomous system) for an IP. Returns AS number, AS name, country, and prefix.

Example

curl -X POST https://api.ipconf.me/api/tools/asn \
  -H "X-Client-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target": "8.8.8.8"}'

Response

{ "ip": "8.8.8.8", "asn": "AS15169", "name": "GOOGLE", "country": "US", "prefix": "8.8.8.0/24" }

POST /api/tools/blacklist 🔑 X-Client-Key required

Check an IP against common DNSBL blacklists (spam, abuse).

Example

curl -X POST https://api.ipconf.me/api/tools/blacklist \
  -H "X-Client-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target": "1.2.3.4"}'

Response

{ "ip": "1.2.3.4", "results": [{"list":"spamhaus","listed":false}, ...] }

POST /api/tools/portscan 🔑 X-Client-Key required

Probe a small set of common ports on a target. Limited to well-known ports for safety.

Example

curl -X POST https://api.ipconf.me/api/tools/portscan \
  -H "X-Client-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target": "example.com", "ports": [22, 80, 443]}'

Response

{ "target": "example.com", "results": [{"port":22,"open":false}, {"port":80,"open":true}, {"port":443,"open":true}] }

POST /api/tools/cdncheck 🔑 X-Client-Key required

Detect whether a hostname is behind a CDN (Cloudflare, Akamai, Fastly, ...) by matching nameservers, IP ranges, and CNAME patterns.

Example

curl -X POST https://api.ipconf.me/api/tools/cdncheck \
  -H "X-Client-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target": "cloudflare.com"}'

Response

{ "target": "cloudflare.com", "cdn": "Cloudflare", "evidence": "AS13335" }

Misc

GET /api/stats

Total requests served and today's count. Used by the homepage badge.

Example

curl https://api.ipconf.me/api/stats

Response

{ "total": 1234567, "today": 8901 }

Error responses

Errors return a JSON body with an error field and an HTTP status.

Status	Meaning	When you'll see it
400	Bad Request	Invalid IP, missing required field, malformed JSON
401	Unauthorized	Missing or invalid X-Client-Key on a tool endpoint
404	Not Found	Unknown endpoint or unknown DNS record
429	Too Many Requests	Rate limit exceeded — back off and retry
5xx	Server Error	Transient — retry with exponential backoff

{ "error": "Invalid IP address" }

Code samples

Minimal "fetch my IP" in a few popular stacks. All endpoints are HTTP + JSON; use any HTTP client.

JavaScript (browser or Node 18+)

const res = await fetch("https://api.ipconf.me/api/ip");
const data = await res.json();
console.log(data.country, data.city);

Python (requests)

import requests
r = requests.get("https://api.ipconf.me/api/ip", timeout=5)
r.raise_for_status()
print(r.json()["country"])

Go (net/http)

package main

import (
  "encoding/json"
  "fmt"
  "net/http"
)

func main() {
  r, _ := http.Get("https://api.ipconf.me/api/ip")
  defer r.Body.Close()
  var data map[string]any
  json.NewDecoder(r.Body).Decode(&data)
  fmt.Println(data["country"])
}

Shell (bash + jq)

MY_IP=$(curl -s https://api.ipconf.me/api/ip | jq -r .ip)
echo "Public IP is: $MY_IP"

Best practices

Cache on your side. IP-to-location is stable on minutes-to-hours timescales. A simple in-process LRU with a 30-minute TTL covers most use cases and dramatically reduces your request count.
Set a timeout. Network calls can hang. Set a 2-5 second timeout and treat timeouts as "no geolocation" rather than blocking your request flow.
Handle 429 gracefully. If you see 429, back off (e.g., wait 60s) and reduce your request rate. Don't retry instantly in a tight loop.
Behind a CDN, pass the real visitor IP. If your server is behind Cloudflare, read CF-Connecting-IP; behind Nginx, X-Forwarded-For. Then call /api/ip/{real_ip}. Otherwise every lookup will be your origin IP.
Treat geolocation as a hint. City-level accuracy is best-effort and unreliable for mobile carriers, corporate networks, and cloud IPs. Never use it as a security control or identity proof.

CORS

IP lookup endpoints respond with Access-Control-Allow-Origin: *, so you can call them directly from any browser. Tool endpoints have a narrower CORS policy and are intended for server-to-server use or for sites that have been issued a client key.

Need a client key, higher limits, or a custom integration? Reach out via the About page. We respond within a few business days.