API Reference — IPfastcheck

Endpoints

Plain text — pipe directly into scripts

GET /ip plain text Returns your public IP address as a bare string

GET /ip?ip=1.2.3.4 plain text Echoes the supplied IP address (validation only)

GET /country plain text Two-letter country code for your IP, e.g. US

GET /country?ip=1.2.3.4 plain text Two-letter country code for a specific IP

JSON — CORS-open, full record

GET /check JSON Full assessment record for your IP

GET /short/{ip} JSON Full assessment record for any IPv4 or IPv6 address

Base URL: https://ipfastcheck.com
Both JSON endpoints return {"ok":true,"data":{...}} on success and {"ok":false,"error":"..."} on failure. Only public addresses are accepted; private, loopback, reserved and documentation ranges answer 400.

Limits & API keys

Caller	Per minute	Per day
No key — counted per client IP (per /64 for IPv6)	60	1 000
Addresses not yet in the cache, per client IP	20	300
With a personal API key	300	10 000

Get a free key from the Telegram bot @ipfastcheckbot with /apikey (/apikey new replaces it), then send it as the X-API-Key header or the key query parameter: /short/8.8.8.8?key=ipfc_…. The limits apply to /check, /short/{ip} and /country.
Responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (unix time, end of the daily window); over a limit the answer is 429 with Retry-After.

Code examples

curl

# Your IP (plain text)
curl https://ipfastcheck.com/ip

# Country for a specific IP
curl https://ipfastcheck.com/country?ip=8.8.8.8

# Full JSON record
curl https://ipfastcheck.com/short/1.1.1.1

# Pipe IP directly into a script variable
MY_IP=$(curl -s https://ipfastcheck.com/ip)

Python

import requests

# Plain text — your IP
ip = requests.get("https://ipfastcheck.com/ip").text.strip()

# Full record
r = requests.get("https://ipfastcheck.com/short/8.8.8.8").json()
data = r["data"]
print(data["geo"]["country"], data["risk"], data["flags"]["proxy"])

JavaScript / fetch

// Full record — works from any origin (CORS open)
const res  = await fetch("https://ipfastcheck.com/short/8.8.8.8");
const json = await res.json();
const { ip, geo, flags, risk, verdict } = json.data;
console.log(ip, geo.country, risk, verdict.text);

PHP

$body = file_get_contents("https://ipfastcheck.com/short/8.8.8.8");
$rec  = json_decode($body, true)["data"];
echo $rec["geo"]["country_code"], " risk=", $rec["risk"];

Full response example

GET /short/8.8.8.8 — response

{
  "ok": true,
  "data": {
    "ip":      "8.8.8.8",
    "version": "IPv4",

    "geo": {
      "country":      "United States",
      "country_code": "US",
      "region":       "California",
      "city":         "Mountain View",
      "zip":          "94043",
      "lat":          37.386,
      "lon":          -122.083,
      "flag":         "🇺🇸"
    },

    "net": {
      "isp":  "Google LLC",
      "org":  "GOOGLE",
      "asn":  "AS15169",
      "type": "datacenter"
    },

    "time": {
      "timezone":   "America/Los_Angeles",
      "utc_offset": "-07:00"
    },

    "flags": {
      "fraud":   false,
      "scam":    false,
      "proxy":   false,
      "vpn":     false,
      "tor":     false,
      "hosting": true,
      "abuse":   false,
      "mobile":  false
    },

    "extra": {
      "fraud_score": 42,
      "scam_score":  null,
      "scam_risk":   null,
      "abuse_score": null,
      "blocklist":   false
    },

    "risk":    42,
    "verdict": { "cls": "risk", "text": "High risk" },
    "usage":   { "key": "datacenter", "label": "Datacenter", "level": "risk" },

    "cached":       true,
    "check_count":  7,
    "first_seen":   1700000000,
    "last_check":   1719000000
  }
}

Field reference

All fields below are present in every successful response; where a type allows null, it means the value could not be determined.

Field	Type	Possible values	Description
Top-level
ip	string	e.g. `8.8.8.8`	The queried IP address
version	string	IPv4IPv6	IP protocol version
risk	integer	0 – 100	Aggregate risk score. <35 clean, 35–69 caution, ≥70 high risk (see Risk score explained)
cached	boolean	truefalse	Whether this result was served from the cache. Records are kept for up to 180 days and refreshed in the background.
check_count	integer	1, 2, 3…	How many times this IP has been checked
first_seen	integer	Unix timestamp	When this IP was first looked up
last_check	integer	Unix timestamp	When this IP was most recently checked
verdict
verdict.cls	string	safewarnrisk	CSS class / severity level. `safe` = clean, `warn` = caution, `risk` = high risk
verdict.text	string	CleanCautionHigh risk	Human-readable verdict label
usage
usage.key	string	residentialdatacentermobile	Connection type identifier
usage.label	string	ResidentialDatacenterMobile	Human-readable connection type
usage.level	string	saferisk	Risk level of this connection type. Datacenter = `risk`
geo
geo.country	string	e.g. `United States`	Full country name. Empty string if unknown
geo.country_code	string	ISO 3166-1 alpha-2, e.g. `US`	Two-letter uppercase country code. Empty string if unknown
geo.region	string	e.g. `California`	State or region name. Empty string if unknown
geo.city	string	e.g. `Mountain View`	City name. Empty string if unknown
geo.zip	string	e.g. `94043`	Postal / ZIP code. Empty string if unknown
geo.lat	float\|null	−90 – 90	Latitude of the estimated location. `null` if unknown
geo.lon	float\|null	−180 – 180	Longitude of the estimated location. `null` if unknown
geo.flag	string	e.g. `🇺🇸` (emoji)	Country flag emoji. Falls back to 🌐 if country unknown
net
net.isp	string	e.g. `Google LLC`	Internet Service Provider name. Empty string if unknown
net.org	string	e.g. `GOOGLE`	Organisation or ASN description. Empty string if unknown
net.asn	string	e.g. `AS15169`	Autonomous System Number in `AS<N>` format. Empty string if unknown
net.type	string	residentialdatacentermobile	Mirrors `usage.key`
time
time.timezone	string	IANA, e.g. `America/Los_Angeles`	IANA timezone identifier for the IP location. Empty string if unknown
time.utc_offset	string	e.g. `-07:00`	Current UTC offset (DST-aware). Format `±HH:MM`. Empty string if unknown
flags — all boolean
flags.proxy	boolean	truefalse	Known open proxy (HTTP, SOCKS4, SOCKS5)
flags.vpn	boolean	truefalse	Known VPN exit node
flags.tor	boolean	truefalse	Tor exit node
flags.hosting	boolean	truefalse	Datacenter / hosting provider IP. High baseline risk for fraud prevention
flags.fraud	boolean	truefalse	Fraud signal detected
flags.scam	boolean	truefalse	Elevated scam risk detected (score ≥25/100)
flags.abuse	boolean	truefalse	Recent abuse activity on record (abuse score ≥25)
flags.mobile	boolean	truefalse	Mobile / cellular network
extra — additional scores
extra.fraud_score	integer	0 – 100	Fraud score 0–100; higher is riskier
extra.scam_score	integer\|null	0 – 100	Scam risk score 0–100. `null` if not available
extra.scam_risk	string\|null	LowMediumHighVery High	Scam risk label. `null` if not available
extra.abuse_score	integer\|null	0 – 100	Abuse confidence score 0–100. `null` if not available
extra.blocklist	boolean	truefalse	IP is present in a curated blocklist

Error responses

Error shape

{ "ok": false, "error": "string" }

HTTP status	error value	Cause
400	Invalid IP address	Malformed address, or not a public one (private, loopback, reserved, documentation)
401	Invalid API key	The key sent in `X-API-Key` / `?key=` is unknown or was replaced
429	Rate limit exceeded	Over one of the limits above; the response also carries `retry_after` (seconds) and a `Retry-After` header
502	Lookup failed for <ip>	All geo providers timed out; no cached record available

Risk score explained

The risk field is an integer 0–100 computed from weighted signals:

Signal	Impact	Notes
tor	High	Tor exit node — strongest anonymisation signal
proxy	High	Known open proxy (HTTP/SOCKS)
fraud_score	Variable	Sets a score floor; can raise the total
abuse_score	Variable	Proportional to the abuse confidence score
vpn	Medium	VPN exit node
hosting	Medium	Datacenter/hosting IP
scam	Medium	Elevated scam risk
blocklist	Medium	Present on a curated blocklist

Verdict: any of proxy, vpn, tor, hosting, fraud, abuse or extra.blocklist set, or risk ≥ 70 → High risk (risk) · otherwise scam set or 35 ≤ risk < 70 → Caution (warn) · otherwise → Clean (safe)