{
  "openapi": "3.1.0",
  "info": {
    "title": "CheckIP.me Full API",
    "version": "1.0.1",
    "summary": "IP intelligence: geolocation, network, and proxy/VPN/Tor/hosting detection.",
    "description": "Look up any public IPv4 or IPv6 address and get its location, network owner, connection type and risk signals: proxy, VPN, Tor, hosting/datacenter, compromised hosts and scrapers, plus VPN operator details, attack history and device estimates.\n\nNo sign-up and no API key. Looking up your own IP is unlimited; lookups of other IPs are limited to 120 per hour per client (shared with checkip.me). Recently looked-up IPs are served from cache, do not count against the limit, and can be up to 30 days old.\n\nFor flat JSON with fixed field names and plain-text single fields, see the Simple API at https://checkip.me/openapi.json.",
    "termsOfService": "https://checkip.me/api",
    "contact": {
      "name": "CheckIP.me",
      "url": "https://checkip.me"
    }
  },
  "externalDocs": {
    "description": "Documentation and code examples",
    "url": "https://checkip.me/api"
  },
  "security": [],
  "servers": [
    {
      "url": "https://api.checkip.me"
    }
  ],
  "tags": [
    {
      "name": "Lookup",
      "description": "IP address lookups"
    }
  ],
  "paths": {
    "/whoami": {
      "get": {
        "tags": ["Lookup"],
        "operationId": "lookupMyIp",
        "summary": "Look up the caller's own IP",
        "description": "Returns all available data for the public IP address the request comes from. Not rate limited.",
        "responses": {
          "200": {
            "$ref": "#/components/responses/LookupOk"
          },
          "502": {
            "$ref": "#/components/responses/UpstreamError"
          }
        }
      }
    },
    "/{ip}": {
      "get": {
        "tags": ["Lookup"],
        "operationId": "lookupIp",
        "summary": "Look up any IP address",
        "description": "Returns all available data for a public IPv4 or IPv6 address, including proxy, VPN, Tor and hosting detection, risk score, VPN operator details and attack history.",
        "parameters": [
          {
            "name": "ip",
            "in": "path",
            "required": true,
            "description": "A public IPv4 or IPv6 address.",
            "schema": {
              "type": "string",
              "examples": ["8.8.8.8", "2001:4860:4860::8888"]
            },
            "example": "8.8.8.8"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/LookupOk"
          },
          "404": {
            "$ref": "#/components/responses/InvalidIp"
          },
          "422": {
            "$ref": "#/components/responses/PrivateIp"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "502": {
            "$ref": "#/components/responses/UpstreamError"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "LookupOk": {
        "description": "Lookup succeeded. The response has one key named after the IP address, holding the data for it.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/LookupResponse"
            },
            "examples": {
              "google-dns": {
                "summary": "8.8.8.8 (Google Public DNS)",
                "value": {
                  "status": "ok",
                  "8.8.8.8": {
                    "network": {
                      "asn": "AS15169",
                      "range": "8.8.8.0/24",
                      "hostname": "dns.google",
                      "provider": "Google LLC",
                      "organisation": "Level 3",
                      "type": "Business"
                    },
                    "location": {
                      "continent_name": "North America",
                      "continent_code": "NA",
                      "country_name": "United States",
                      "country_code": "US",
                      "region_name": "California",
                      "region_code": "CA",
                      "city_name": "Mountain View",
                      "postal_code": "94043",
                      "latitude": 37.422,
                      "longitude": -122.085,
                      "timezone": "America/Los_Angeles",
                      "currency": {
                        "name": "Dollar",
                        "code": "USD",
                        "symbol": "$"
                      }
                    },
                    "device_estimate": {
                      "address": 10,
                      "subnet": 60
                    },
                    "detections": {
                      "proxy": false,
                      "vpn": false,
                      "compromised": false,
                      "scraper": false,
                      "tor": false,
                      "hosting": false,
                      "anonymous": true,
                      "risk": 100,
                      "confidence": 100,
                      "first_seen": "2026-09-21T08:17:28Z",
                      "last_seen": "2026-09-21T08:17:28Z",
                      "times_seen": null
                    },
                    "detection_history": {
                      "delisted": true,
                      "delist_datetime": "2026-09-18T06:18:03Z"
                    },
                    "attack_history": {
                      "vulnerability_probing": 20
                    },
                    "operator": null,
                    "last_updated": "2026-09-20T11:30:55Z"
                  },
                  "query_time": 5,
                  "docs": "https://checkip.me/api"
                }
              },
              "tor-exit": {
                "summary": "185.220.101.1 (Tor exit node, with operator details)",
                "value": {
                  "status": "ok",
                  "185.220.101.1": {
                    "network": {
                      "asn": "AS60729",
                      "range": "185.220.101.1/28",
                      "hostname": "berlin01.tor-exit.artikel10.org",
                      "provider": "Stiftung Erneuerbare Freiheit",
                      "organisation": "Artikel10 e.V",
                      "type": "Business"
                    },
                    "location": {
                      "continent_name": "Europe",
                      "continent_code": "EU",
                      "country_name": "Germany",
                      "country_code": "DE",
                      "region_name": "State of Berlin",
                      "region_code": "BE",
                      "city_name": "Berlin",
                      "postal_code": "10178",
                      "latitude": 52.52,
                      "longitude": 13.405,
                      "timezone": "Europe/Berlin",
                      "currency": {
                        "name": "Euro",
                        "code": "EUR",
                        "symbol": "€"
                      }
                    },
                    "device_estimate": {
                      "address": 10,
                      "subnet": 1520
                    },
                    "detections": {
                      "proxy": true,
                      "vpn": false,
                      "compromised": true,
                      "scraper": false,
                      "tor": true,
                      "hosting": false,
                      "anonymous": true,
                      "risk": 100,
                      "confidence": 100,
                      "first_seen": "2026-01-31T12:41:23Z",
                      "last_seen": "2026-09-20T18:49:52Z",
                      "times_seen": 14609
                    },
                    "detection_history": {
                      "delisted": false,
                      "delist_datetime": "2026-09-22T18:49:52Z"
                    },
                    "attack_history": {
                      "login_attempt": 7,
                      "registration_attempt": 3
                    },
                    "operator": {
                      "name": "TOR",
                      "url": "https://www.torproject.org/",
                      "anonymity": "high",
                      "popularity": "high",
                      "services": ["residential_proxies", "wireless_proxies", "datacenter_proxies"],
                      "protocols": ["Onion Routing"],
                      "policies": {
                        "ad_filtering": false,
                        "free_access": true,
                        "paid_access": false,
                        "port_forwarding": false,
                        "logging": false,
                        "anonymous_payments": false,
                        "crypto_payments": false,
                        "traceable_ownership": true
                      },
                      "additional_operators": ["PacketStream", "ASocks", "Webshare"]
                    },
                    "last_updated": "2026-09-20T18:49:52Z"
                  },
                  "query_time": 8,
                  "docs": "https://checkip.me/api"
                }
              }
            }
          }
        }
      },
      "InvalidIp": {
        "description": "The value is not a valid IPv4 or IPv6 address.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "status": "error",
              "ip": "999.1.1.1",
              "error": "No valid IP Addresses supplied.",
              "message": "No valid IP Addresses supplied."
            }
          }
        }
      },
      "PrivateIp": {
        "description": "The address is private or reserved (for example 10.x, 192.168.x, 127.x, ::1), so no public data exists for it.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "status": "error",
              "ip": "10.0.0.1",
              "error": "This is a private or reserved IP address. No public data is available for it.",
              "message": "This is a private or reserved IP address. No public data is available for it."
            }
          }
        }
      },
      "RateLimited": {
        "description": "Too many lookups of other IPs (limit: 120 per hour per client). Wait for the number of seconds in Retry-After.",
        "headers": {
          "Retry-After": {
            "description": "Seconds to wait before retrying.",
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "UpstreamError": {
        "description": "The data source did not respond. Try again later.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "LookupResponse": {
        "type": "object",
        "description": "Successful lookup. Besides the fields below, the object has exactly one more key: the IP address that was looked up (for /whoami, the caller's IP), whose value is an IPData object.",
        "required": ["status"],
        "properties": {
          "status": {
            "type": "string",
            "enum": ["ok", "warning"],
            "description": "`ok`, or `warning` when the lookup succeeded but with a caveat explained in `message`. The IP data is present in both cases."
          },
          "message": {
            "type": "string",
            "description": "Explanation of the warning. Present only when status is `warning`."
          },
          "query_time": {
            "type": "integer",
            "description": "Server processing time in milliseconds."
          },
          "docs": {
            "type": "string",
            "format": "uri",
            "description": "Link to the documentation."
          }
        },
        "additionalProperties": {
          "$ref": "#/components/schemas/IPData"
        }
      },
      "IPData": {
        "type": "object",
        "description": "Everything known about one IP address. Unknown values are null.",
        "properties": {
          "network": {
            "$ref": "#/components/schemas/Network"
          },
          "location": {
            "$ref": "#/components/schemas/Location"
          },
          "device_estimate": {
            "oneOf": [
              { "$ref": "#/components/schemas/DeviceEstimate" },
              { "type": "null" }
            ]
          },
          "detections": {
            "$ref": "#/components/schemas/Detections"
          },
          "detection_history": {
            "oneOf": [
              { "$ref": "#/components/schemas/DetectionHistory" },
              { "type": "null" }
            ]
          },
          "attack_history": {
            "description": "Counts of abuse seen from this IP, keyed by type (for example login_attempt, registration_attempt, vulnerability_probing). Null when none was seen.",
            "type": ["object", "null"],
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            }
          },
          "operator": {
            "description": "The VPN, proxy or anonymity network behind this IP, when known.",
            "oneOf": [
              { "$ref": "#/components/schemas/Operator" },
              { "type": "null" }
            ]
          },
          "last_updated": {
            "type": ["string", "null"],
            "format": "date-time",
            "description": "When this data was last refreshed."
          }
        }
      },
      "Network": {
        "type": "object",
        "properties": {
          "asn": {
            "type": ["string", "null"],
            "description": "Autonomous system number.",
            "examples": ["AS15169"]
          },
          "range": {
            "type": ["string", "null"],
            "description": "Network range in CIDR notation.",
            "examples": ["8.8.8.0/24"]
          },
          "hostname": {
            "type": ["string", "null"],
            "description": "Reverse DNS name."
          },
          "provider": {
            "type": ["string", "null"],
            "description": "Internet service provider (ISP)."
          },
          "organisation": {
            "type": ["string", "null"],
            "description": "Organisation the range is registered to."
          },
          "type": {
            "type": ["string", "null"],
            "description": "Connection type.",
            "examples": ["Residential", "Business", "Wireless", "Hosting"]
          }
        }
      },
      "Location": {
        "type": "object",
        "description": "Approximate location.",
        "properties": {
          "continent_name": { "type": ["string", "null"] },
          "continent_code": { "type": ["string", "null"], "examples": ["NA"] },
          "country_name": { "type": ["string", "null"] },
          "country_code": {
            "type": ["string", "null"],
            "description": "ISO 3166-1 alpha-2 code.",
            "examples": ["US"]
          },
          "region_name": { "type": ["string", "null"] },
          "region_code": { "type": ["string", "null"] },
          "city_name": { "type": ["string", "null"] },
          "postal_code": { "type": ["string", "null"] },
          "latitude": { "type": ["number", "null"] },
          "longitude": { "type": ["number", "null"] },
          "timezone": {
            "type": ["string", "null"],
            "description": "IANA time zone.",
            "examples": ["America/Los_Angeles"]
          },
          "currency": {
            "oneOf": [
              { "$ref": "#/components/schemas/Currency" },
              { "type": "null" }
            ]
          }
        }
      },
      "Currency": {
        "type": "object",
        "properties": {
          "name": { "type": ["string", "null"], "examples": ["Dollar"] },
          "code": {
            "type": ["string", "null"],
            "description": "ISO 4217 code.",
            "examples": ["USD"]
          },
          "symbol": { "type": ["string", "null"], "examples": ["$"] }
        }
      },
      "DeviceEstimate": {
        "type": "object",
        "description": "Estimated number of devices seen behind this IP and its subnet.",
        "properties": {
          "address": { "type": ["integer", "null"] },
          "subnet": { "type": ["integer", "null"] }
        }
      },
      "Detections": {
        "type": "object",
        "properties": {
          "proxy": { "type": "boolean", "description": "Open or commercial proxy." },
          "vpn": { "type": "boolean", "description": "VPN exit." },
          "tor": { "type": "boolean", "description": "Tor exit node." },
          "hosting": { "type": "boolean", "description": "Data center or cloud IP." },
          "compromised": { "type": "boolean", "description": "Host appears to be compromised (botnet, malware)." },
          "scraper": { "type": "boolean", "description": "Seen scraping websites." },
          "anonymous": { "type": "boolean", "description": "The IP hides the real user in some way." },
          "risk": {
            "type": ["integer", "null"],
            "minimum": 0,
            "maximum": 100,
            "description": "Risk score from 0 (clean) to 100 (very risky)."
          },
          "confidence": {
            "type": ["integer", "null"],
            "minimum": 0,
            "maximum": 100,
            "description": "Confidence in the detection, from 0 to 100."
          },
          "first_seen": {
            "type": ["string", "null"],
            "format": "date-time",
            "description": "When the IP was first flagged."
          },
          "last_seen": {
            "type": ["string", "null"],
            "format": "date-time",
            "description": "When the IP was last flagged."
          },
          "times_seen": {
            "type": ["integer", "null"],
            "description": "How many times the IP was flagged."
          }
        }
      },
      "DetectionHistory": {
        "type": "object",
        "properties": {
          "delisted": {
            "type": ["boolean", "null"],
            "description": "True once the IP has been removed from the detection lists."
          },
          "delist_datetime": {
            "type": ["string", "null"],
            "format": "date-time",
            "description": "When the IP was, or is scheduled to be, delisted."
          }
        }
      },
      "Operator": {
        "type": "object",
        "properties": {
          "name": { "type": ["string", "null"], "examples": ["TOR", "NordVPN"] },
          "url": { "type": ["string", "null"], "format": "uri" },
          "anonymity": { "type": ["string", "null"], "examples": ["low", "medium", "high"] },
          "popularity": { "type": ["string", "null"], "examples": ["low", "medium", "high"] },
          "services": {
            "type": "array",
            "items": { "type": "string" },
            "examples": [["vpn", "datacenter_proxies"]]
          },
          "protocols": {
            "type": "array",
            "items": { "type": "string" },
            "examples": [["WireGuard", "OpenVPN"]]
          },
          "policies": {
            "type": "object",
            "description": "Operator policies, for example logging, free_access, crypto_payments.",
            "additionalProperties": { "type": "boolean" }
          },
          "additional_operators": {
            "type": "array",
            "description": "Other networks seen on this IP.",
            "items": { "type": "string" }
          }
        }
      },
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "status": { "type": "string", "const": "error" },
          "ip": { "type": "string", "description": "The value that was looked up." },
          "error": { "type": "string", "description": "Human-readable error message." },
          "message": { "type": "string", "description": "Same as error (kept for backward compatibility)." }
        }
      }
    }
  }
}