Free IP Geolocation API (No Key Required)

Copy-paste examples

7 of the 10 endpoints on this page have a curl, JavaScript (fetch) and Python (requests) example with a copy button: /api/ip, /api/lookup, /api/score, /api/dns, /api/whois, /api/rdns and /api/blacklist. Pick a language once and every example switches. We ran each example against the live API on 2026-10-25 and show the response it returned; /api/ip and /api/score show your own connection instead.

GET /api/ip

Returns the requesting client's IP address and geolocation data.

Example Request

curl https://hackmyip.com/api/ip

fetch('https://hackmyip.com/api/ip')
  .then(r => r.json())
  .then(res => console.log(res.data.ip, res.data.location.country, res.data.network.isp));

import requests

res = requests.get('https://hackmyip.com/api/ip', timeout=10).json()
print(res['data']['ip'], res['data']['location']['country'], res['data']['network']['isp'])

Example Response

{
  "success": true,
  "data": {
    "ip": "2a06:98c0:3600::103",
    "location": {
      "city": "Columbus",
      "region": "Ohio",
      "country": "US",
      "country_name": "US",
      "continent": "NA",
      "latitude": "39.96118",
      "longitude": "-82.99879",
      "timezone": "America/New_York",
      "postal_code": "43215"
    },
    "network": {
      "asn": 13335,
      "isp": "Cloudflare, Inc.",
      "connection_type": "HTTP/2",
      "tls_version": "TLSv1.3"
    },
    "privacy": {
      "type": "datacenter",
      "score": 80,
      "grade": "A",
      "is_vpn": false,
      "is_datacenter": true,
      "is_residential": false,
      "hosting": false,
      "proxy": false
    },
    "is_eu": false,
    "ipv6": true
  }
}

Full response, built from your own connection as our edge sees it. When the upstream network lookup answers, location.country_name is the full country name and city, region, isp, privacy.hosting and privacy.proxy come from that lookup. Field list in the OpenAPI spec.

Response Fields

GET /api/lookup

Look up geolocation data for a specific IP address.

Parameters

Example Request

curl "https://hackmyip.com/api/lookup?ip=8.8.8.8"

fetch('https://hackmyip.com/api/lookup?ip=8.8.8.8')
  .then(r => r.json())
  .then(res => console.log(res.data.location.country_name, res.data.network.isp, res.data.privacy.hosting));

import requests

res = requests.get('https://hackmyip.com/api/lookup', params={'ip': '8.8.8.8'}, timeout=10).json()
print(res['data']['location']['country_name'], res['data']['network']['isp'], res['data']['privacy']['hosting'])

Example Response

{
  "success": true,
  "data": {
    "ip": "8.8.8.8",
    "location": {
      "city": "Ashburn",
      "region": "Virginia",
      "country": "US",
      "country_name": "United States",
      "latitude": 39.03,
      "longitude": -77.5,
      "timezone": "America/New_York",
      "postal_code": "20149"
    },
    "network": {
      "asn": 15169,
      "isp": "Google LLC",
      "org": "Google Public DNS"
    },
    "privacy": {
      "hosting": true,
      "proxy": true,
      "mobile": false
    }
  }
}

Real response for 8.8.8.8 (2026-10-25). Results are cacheable for an hour. If the upstream lookup is briefly unavailable you get HTTP 503 with "success": false and an error message, so retry after a few seconds.

Usage Notes

This API is free for personal and commercial use. Please keep it under 100 requests per minute, the limit our response headers advertise (X-RateLimit-Limit: 100, X-RateLimit-Window: 60). The /api/v1/ endpoints are capped at 60 requests per minute. The API is powered by Cloudflare Workers and served from edge locations worldwide for minimal latency.

For high-volume usage or dedicated support, please reach out.

README Badge

Using the API in a project? Add the badge to your README so your users know where the IP data comes from. It renders fine through GitHub's image proxy:

Markdown

HTML

GET /api/breach

Check if an email address has been exposed in data breaches. Scans known breach databases (XposedOrNot).

Parameters

Example Request

Example Response

Sample response: the fields match the live endpoint, but the values are illustrative, not a real lookup. When the breach database cannot be reached the endpoint answers "status": "unavailable" instead of a false clean result.

GET /api/score

Get your IP's privacy and cleanliness score. Detects VPN, datacenter, or residential IP.

Example Request

curl https://hackmyip.com/api/score

fetch('https://hackmyip.com/api/score')
  .then(r => r.json())
  .then(res => console.log(res.data.privacy.type, res.data.privacy.score, res.data.privacy.grade));

import requests

res = requests.get('https://hackmyip.com/api/score', timeout=10).json()
print(res['data']['privacy']['type'], res['data']['privacy']['score'], res['data']['privacy']['grade'])

Example Response

{
  "success": true,
  "data": {
    "ip": "2a06:98c0:3600::103",
    "location": {
      "city": "Columbus",
      "country": "US",
      "timezone": "America/New_York"
    },
    "network": {
      "isp": "Cloudflare, Inc.",
      "asn": 13335,
      "tls_version": "TLSv1.3"
    },
    "privacy": {
      "type": "datacenter",
      "score": 80,
      "grade": "A",
      "label": "Clean",
      "flags": [
        "Hosting/datacenter IP - your real IP is hidden",
        "IPv6 address"
      ],
      "is_vpn": false,
      "is_datacenter": true,
      "is_residential": false
    },
    "ipv6": true
  }
}

Your own result: this is exactly what /api/score returns for your connection right now.

GET /api/dns

DNS record lookup for any domain. Supports A, AAAA, MX, NS, TXT, CNAME, CAA, SOA.

Example Request

curl "https://hackmyip.com/api/dns?domain=github.com&type=MX"

fetch('https://hackmyip.com/api/dns?domain=github.com&type=MX')
  .then(r => r.json())
  .then(res => res.data.records.forEach(rec => console.log(rec.data, rec.TTL)));

import requests

res = requests.get('https://hackmyip.com/api/dns', params={'domain': 'github.com', 'type': 'MX'}, timeout=10).json()
for rec in res['data']['records']:
    print(rec['data'], rec['TTL'])

Example Response

{
  "success": true,
  "data": {
    "domain": "github.com",
    "type": "MX",
    "status": 0,
    "records": [
      {
        "name": "github.com",
        "type": 15,
        "TTL": 177,
        "data": "0 github-com.mail.protection.outlook.com."
      }
    ],
    "authority": []
  }
}

Real response (2026-10-25). status is the DNS response code (0 = no error, 3 = domain does not exist) and type inside each record is the numeric record type (15 = MX).

GET /api/whois

WHOIS / RDAP registration data for a domain: registrar, creation date, expiration, name servers.

Example Request

curl "https://hackmyip.com/api/whois?domain=github.com"

fetch('https://hackmyip.com/api/whois?domain=github.com')
  .then(r => r.json())
  .then(res => console.log(res.data.registrar, res.data.creation_date, res.data.expiration_date));

import requests

res = requests.get('https://hackmyip.com/api/whois', params={'domain': 'github.com'}, timeout=10).json()
print(res['data']['registrar'], res['data']['creation_date'], res['data']['expiration_date'])

Example Response

{
  "success": true,
  "data": {
    "domain": "GITHUB.COM",
    "registrar": "MarkMonitor Inc.",
    "creation_date": "2007-10-09T18:20:50Z",
    "expiration_date": "2028-10-09T18:20:50Z",
    "last_updated": "2026-09-07T09:22:52Z",
    "name_servers": [
      "DNS1.P08.NSONE.NET",
      "DNS2.P08.NSONE.NET",
      "DNS3.P08.NSONE.NET",
      "DNS4.P08.NSONE.NET",
      "NS-1283.AWSDNS-32.ORG",
      "NS-1707.AWSDNS-21.CO.UK",
      "NS-421.AWSDNS-52.COM",
      "NS-520.AWSDNS-01.NET"
    ],
    "status": [
      "client delete prohibited",
      "client transfer prohibited",
      "client update prohibited"
    ],
    "rdap_link": "https://rdap.verisign.com/com/v1/domain/github.com"
  }
}

Real response (2026-10-25).

GET /api/rdns

Reverse DNS — resolves an IP address to its PTR hostname.

Example Request

curl "https://hackmyip.com/api/rdns?ip=8.8.8.8"

fetch('https://hackmyip.com/api/rdns?ip=8.8.8.8')
  .then(r => r.json())
  .then(res => console.log(res.data.hostname));

import requests

res = requests.get('https://hackmyip.com/api/rdns', params={'ip': '8.8.8.8'}, timeout=10).json()
print(res['data']['hostname'])

Example Response

{
  "success": true,
  "data": {
    "ip": "8.8.8.8",
    "hostname": "dns.google",
    "ptr_record": "8.8.8.8.in-addr.arpa"
  }
}

Real response (2026-10-25).

GET /api/blacklist

Check an IPv4 against 12 spam / abuse DNSBLs (Spamhaus ZEN, Barracuda, SpamCop, UCEPROTECT, and more).

Example Request

curl "https://hackmyip.com/api/blacklist?ip=8.8.8.8"

fetch('https://hackmyip.com/api/blacklist?ip=8.8.8.8')
  .then(r => r.json())
  .then(res => console.log(res.data.status, res.data.listed_count, res.data.total_checked));

import requests

res = requests.get('https://hackmyip.com/api/blacklist', params={'ip': '8.8.8.8'}, timeout=20).json()
print(res['data']['status'], res['data']['listed_count'], res['data']['total_checked'])

Example Response

{
  "success": true,
  "data": {
    "ip": "8.8.8.8",
    "total_lists": 12,
    "total_checked": 8,
    "unavailable_count": 4,
    "listed_count": 0,
    "clean": true,
    "status": "CLEAN",
    "results": [
      {
        "name": "Spamhaus ZEN",
        "zone": "zen.spamhaus.org",
        "desc": "Combined spam/exploit/policy blocklist",
        "listed": false,
        "status": "unavailable",
        "response": null
      },
      {
        "name": "Barracuda",
        "zone": "b.barracudacentral.org",
        "desc": "Barracuda reputation block list",
        "listed": false,
        "status": "not_listed",
        "response": null
      }
    ]
  }
}

Real response (2026-10-25), results trimmed to 2 of its 12 entries. A list that does not answer is counted in unavailable_count, never as listed.

GET /api/down

Is a website up or down. Returns HTTP status code and response time in ms.

Example Request

Example Response

Real response from hackmyip.com (2026-10-25).

POST /api/bulk

Batch lookup up to 50 IPs in a single POST request. Faster than sequential /api/lookup calls.

Example Request

Example Response

npm Package

Use our official JavaScript client for easy integration:

GitHub: github.com/Hackmyip/hackmyip-js

Using the API? Add a badge

Show off that your project runs on the free HackMyIP API with an embeddable SVG badge. Drop it in your README or site — one line of Markdown:

Browse all badges & trust seals →