API Documentation

Complete reference for the IP Info API. 24 fields, 16 endpoints, 5 output formats, code examples in 7 languages. All data sourced from the edge network -- zero external API calls.

🔍

🔎No sections match your search.
Try a different keyword.

Quick Start

Get your public IP address with a single command. Free API key required -- register in seconds at ipfast.dev/login.

curl ipfast.dev/text

Get full geolocation data as JSON. The response includes 24 fields: IP, country (with flag, currency, calling code, continent, EU status, languages, TLD, capital), city, region, timezone, coordinates, postal code, ASN, and ISP:

curl ipfast.dev/json

{
  "ip": "216.73.216.14",
  "country": "US",
  "countryName": "United States",
  "city": "Columbus",
  "region": "Ohio",
  "timezone": "America/New_York",
  "latitude": "39.96118",
  "longitude": "-82.99879",
  "postalCode": "43215",
  "asn": 16509,
  "asOrganization": "Anthropic, PBC",
  "colo": "CMH",
  "regionCode": "OH",
  "flag": "🇺🇸",
  "continentCode": "NA",
  "continent": "Americas",
  "isEU": false,
  "currency": "USD",
  "currencyName": "United States Dollar",
  "currencySymbol": "$",
  "callingCode": "+1",
  "languages": "English",
  "countryTld": ".us",
  "countryCapital": "Washington, D.C."
}

Use it from JavaScript in the browser or Node.js. CORS is enabled for all origins, so this works from any website:

const data = await fetch('https://ipfast.dev/json').then(r => r.json());
console.log(data.ip);        // "216.73.216.14"
console.log(data.country);   // "US"
console.log(data.city);      // "Columbus"
console.log(data.timezone);  // "America/New_York"

Base URL

https://ipfast.dev

All endpoints are relative to this base URL. HTTPS is required -- HTTP requests will be redirected. The service runs across 300+ edge locations worldwide, so your request is handled by the nearest data center.

Authentication

Own IP endpoints: No API key required. Just send a request and get your data back.

Arbitrary IP endpoints: Free API key required. Register in seconds via magic link (no password). Free plan: 10 lookups/hour, 200/month.

Premium endpoints (arbitrary IP, bulk, enrichment): Requires an API key. Pass it via header or query parameter:

# Via header (recommended)
curl -H "X-API-Key: sk_live_xxxxxxxxxxxx" https://ipfast.dev/json/8.8.8.8

# Via query parameter
curl "https://ipfast.dev/json/8.8.8.8?apikey=sk_live_xxxxxxxxxxxx"

Plan	Rate Limit	Monthly Quota	Features
`free`	120/min per IP	10K	Own IP lookup, all formats + 10 arbitrary/hour
`starter`	500/min	50,000	+ Arbitrary IP, country metadata
`pro`	1,000/min	200,000	+ Company detection, distance, bulk (50 IPs)
`business`	2,000/min	1,000,000	+ Security, threat scoring, bulk (100 IPs)
`enterprise`	5,000/min	10,000,000	+ Custom SLA, webhooks

Rate Limits

Free tier: 120 requests per minute per IP address.

Premium tiers: Rate limit depends on your plan (500-5,000 req/min). Monthly quota is also enforced.

Rate limit information is included in every API response header. When the limit is exceeded, the API returns HTTP 429 with a Retry-After header.

Header	Type	Default	Description
`X-RateLimit-Limit`	number	-	Requests allowed per minute for your plan
`X-RateLimit-Remaining`	number	-	Requests remaining in the current window
`X-RateLimit-Reset`	timestamp	-	Unix timestamp when the rate limit resets
`X-Quota-Limit`	number	-	Monthly quota for your plan (premium only)
`X-Quota-Remaining`	number	-	Requests remaining this month (premium only)
`X-Quota-Reset`	date	-	ISO date when monthly quota resets (premium only)
`Retry-After`	seconds	-	Seconds to wait (only on 429 responses)

CORS

All API endpoints return Access-Control-Allow-Origin: *, which means you can call this API from any website, browser extension, or frontend application without needing a proxy server or CORS workaround.

Allowed methods: GET, OPTIONS. The API responds to preflight OPTIONS requests with a 204 No Content status.

Error Handling

The API uses standard HTTP status codes. Error responses are always JSON:

Status	Error Code	When It Happens
`200`	-	Request processed successfully
`400`	`invalid_ip`	Invalid IP address format in URL
`401`	`invalid_api_key`	Missing or invalid API key for premium endpoint
`402`	`quota_exceeded`	Monthly quota exhausted
`403`	`feature_not_available`	Feature requires a higher plan tier
`404`	`not_found`	Invalid endpoint or IP not in database
`405`	-	Non-GET/POST request
`429`	`rate_limit_exceeded`	Rate limit exceeded, includes `retry_after`

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Retry after 12 seconds.",
  "retry_after": 12
}

GET /json

Returns complete IP geolocation as JSON. This is the primary endpoint for most use cases. The response includes 24 fields covering IP address, location, country metadata (flag, currency, continent, EU status, languages, calling code, TLD, capital), and network information -- all free with your API key.

curl https://ipfast.dev/json

{
  "ip": "216.73.216.14",
  "country": "US",
  "countryName": "United States",
  "city": "Columbus",
  "region": "Ohio",
  "timezone": "America/New_York",
  "latitude": "39.96118",
  "longitude": "-82.99879",
  "postalCode": "43215",
  "asn": 16509,
  "asOrganization": "Anthropic, PBC",
  "colo": "CMH",
  "regionCode": "OH",
  "flag": "🇺🇸",
  "continentCode": "NA",
  "continent": "Americas",
  "isEU": false,
  "currency": "USD",
  "currencyName": "United States Dollar",
  "currencySymbol": "$",
  "callingCode": "+1",
  "languages": "English",
  "countryTld": ".us",
  "countryCapital": "Washington, D.C."
}

Field	Type	Description
`ip`	string	Your public IP address (IPv4 or IPv6)
`country`	string	ISO 3166-1 alpha-2 country code (e.g., "US", "DE", "JP")
`countryName`	string	Full country name in English
`city`	string	City name as determined by edge geolocation
`region`	string	State, province, or region name
`timezone`	string	IANA timezone identifier (e.g., "America/New_York")
`latitude`	string	Latitude coordinate (typically city-level accuracy)
`longitude`	string	Longitude coordinate (typically city-level accuracy)
`postalCode`	string	Postal or ZIP code (availability varies by country)
`asn`	number	Autonomous System Number identifying the network
`asOrganization`	string	Organization name (ISP, hosting provider, or enterprise)
`colo`	string	IATA code of the edge data center that handled the request
`regionCode`	string	ISO subdivision code for the region (e.g., "CA" for California)
`flag`	string	Country flag emoji (e.g., "🇺🇸")
`continentCode`	string	Two-letter continent code: AF, AN, AS, EU, NA, OC, SA
`continent`	string	Continent name (e.g., "Americas", "Europe", "Asia")
`isEU`	boolean	Whether the country is an EU member state
`currency`	string	ISO 4217 currency code (e.g., "USD", "EUR")
`currencyName`	string	Full currency name (e.g., "US Dollar")
`currencySymbol`	string	Currency symbol (e.g., "$", "€")
`callingCode`	string	International dialing code (e.g., "+1", "+44")
`languages`	string	Comma-separated language codes (e.g., "en-US,es-US")
`countryTld`	string	Country top-level domain (e.g., ".us", ".de")
`countryCapital`	string	Capital city name (e.g., "Washington, D.C.")

GET /text

Returns just your IP address as plain text with no JSON wrapping. Ideal for shell scripts where you need a single value without parsing. Aliases: /plain, /ip

curl https://ipfast.dev/text

216.73.216.14

The response body contains only the IP address followed by a newline. Content-Type is text/plain.

GET /all

Returns IP geolocation, connection security details, and parsed user agent in a single JSON response. Use this when you need everything the API offers in one request instead of calling multiple endpoints.

curl https://ipfast.dev/all

{
  "ip": {"ip":"216.73.216.14","country":"US","countryName":"United States","city":"Columbus","region":"Ohio","timezone":"America/New_York","latitude":"39.96118","longitude":"-82.99879","postalCode":"43215","asn":16509,"asOrganization":"Anthropic, PBC","colo":"CMH","regionCode":"OH","flag":"🇺🇸","continentCode":"NA","continent":"Americas","isEU":false,"currency":"USD","currencyName":"United States Dollar","currencySymbol":"$","callingCode":"+1","languages":"English","countryTld":".us","countryCapital":"Washington, D.C."},
  "connection": {"httpProtocol":"HTTP/2","tlsVersion":"TLSv1.3","tlsCipher":"AEAD-AES256-GCM-SHA384","clientTcpRtt":1,"edgeRequestKeepAliveStatus":1},
  "userAgent": {"raw":"Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)","browser":"Unknown","browserVersion":"","os":"Unknown","osVersion":"","device":"Bot","isBot":true},
  "acceptLanguage": "en-US,en;q=0.9",
  "requestTime": "2026-04-10T15:38:18.273Z"
}

GET /country | GET /country/{ip}

Returns the ISO 3166-1 alpha-2 country code as plain text. Without an IP parameter, returns data for the caller. With /{ip}, looks up any IP Premium

# Your IP
curl https://ipfast.dev/country
US

# Arbitrary IP (premium)
curl -H "X-API-Key: sk_live_xxx" https://ipfast.dev/country/8.8.8.8
US

GET /city | GET /city/{ip}

Returns the city name as plain text. Without an IP parameter, returns data for the caller. With /{ip}, looks up any IP Premium

# Your IP
curl https://ipfast.dev/city
Columbus

# Arbitrary IP (premium)
curl -H "X-API-Key: sk_live_xxx" https://ipfast.dev/city/1.1.1.1
Los Angeles

GET /region | GET /region/{ip}

Returns the state, province, or region name as plain text. For US IPs this is the state name; for other countries it varies (prefecture, canton, etc.). With /{ip}, looks up any IP Premium

# Your IP
curl https://ipfast.dev/region
Ohio

# Arbitrary IP (premium)
curl -H "X-API-Key: sk_live_xxx" https://ipfast.dev/region/8.8.8.8
California

GET /timezone | GET /timezone/{ip}

Returns the IANA timezone identifier as plain text. Use this with Intl.DateTimeFormat in JavaScript or pytz in Python. With /{ip}, looks up any IP Premium

# Your IP
curl https://ipfast.dev/timezone
America/New_York

# Arbitrary IP (premium)
curl -H "X-API-Key: sk_live_xxx" https://ipfast.dev/timezone/8.8.8.8
America/Chicago

GET /coordinates | GET /coordinates/{ip}

Returns latitude and longitude as comma-separated plain text. Aliases: /latlon, /coords. With /{ip}, looks up any IP Premium

# Your IP
curl https://ipfast.dev/coordinates
39.96118,-82.99879

# Arbitrary IP (premium)
curl -H "X-API-Key: sk_live_xxx" https://ipfast.dev/coordinates/8.8.8.8
37.751,-97.822

GET /asn | GET /asn/{ip}

Returns the Autonomous System Number and organization name as plain text. The ASN identifies the network (ISP, hosting provider, or enterprise). With /{ip}, looks up any IP Premium

# Your IP
curl https://ipfast.dev/asn
AS16509 Anthropic, PBC

# Arbitrary IP (premium)
curl -H "X-API-Key: sk_live_xxx" https://ipfast.dev/asn/1.1.1.1
AS13335 Cloudflare, Inc.

GET /postal | GET /postal/{ip}

Returns the postal or ZIP code as plain text. Alias: /zip. With /{ip}, looks up any IP Premium

# Your IP
curl https://ipfast.dev/postal
43215

# Arbitrary IP (premium)
curl -H "X-API-Key: sk_live_xxx" https://ipfast.dev/postal/8.8.8.8
67202

GET /flag | GET /flag/{ip}

Returns the country flag emoji as plain text. Alias: /emoji. With /{ip}, looks up any IP Premium

# Your IP
curl https://ipfast.dev/flag
🇺🇸

# Arbitrary IP (premium)
curl -H "X-API-Key: sk_live_xxx" https://ipfast.dev/flag/8.8.8.8
🇺🇸

GET /currency | GET /currency/{ip}

Returns the ISO 4217 currency code as plain text. Also available: /currency-name and /currency-symbol. With /{ip}, looks up any IP Premium

# Your IP
curl https://ipfast.dev/currency
USD

# Arbitrary IP (premium)
curl -H "X-API-Key: sk_live_xxx" https://ipfast.dev/currency/8.8.8.8
USD

GET /continent | GET /continent/{ip}

Returns the continent name as plain text. Also available: /continent-code. With /{ip}, looks up any IP Premium

# Your IP
curl https://ipfast.dev/continent
Americas

# Arbitrary IP (premium)
curl -H "X-API-Key: sk_live_xxx" https://ipfast.dev/continent/8.8.8.8
North America

GET /capital | GET /capital/{ip}

Returns the capital city of the detected country as plain text. With /{ip}, looks up any IP Premium

# Your IP
curl https://ipfast.dev/capital
Washington, D.C.

# Arbitrary IP (premium)
curl -H "X-API-Key: sk_live_xxx" https://ipfast.dev/capital/8.8.8.8
Washington, D.C.

GET /calling-code | GET /calling-code/{ip}

Returns the international dialing code as plain text. Alias: /dial. With /{ip}, looks up any IP Premium

# Your IP
curl https://ipfast.dev/calling-code
+1

# Arbitrary IP (premium)
curl -H "X-API-Key: sk_live_xxx" https://ipfast.dev/calling-code/8.8.8.8
+1

GET /languages | GET /languages/{ip}

Returns comma-separated language codes as plain text. With /{ip}, looks up any IP Premium

# Your IP
curl https://ipfast.dev/languages
English

# Arbitrary IP (premium)
curl -H "X-API-Key: sk_live_xxx" https://ipfast.dev/languages/8.8.8.8
English

GET /tld | GET /tld/{ip}

Returns the country top-level domain as plain text. With /{ip}, looks up any IP Premium

# Your IP
curl https://ipfast.dev/tld
.us

# Arbitrary IP (premium)
curl -H "X-API-Key: sk_live_xxx" https://ipfast.dev/tld/8.8.8.8
.us

GET /eu | GET /eu/{ip}

Returns whether the country is an EU member state as plain text ("true" or "false"). With /{ip}, looks up any IP Premium

# Your IP
curl https://ipfast.dev/eu
false

# Arbitrary IP (premium)
curl -H "X-API-Key: sk_live_xxx" https://ipfast.dev/eu/8.8.8.8
false

GET /geo | GET /geo/{ip}

Location-focused JSON preset. Returns IP, country (with flag), city, region, coordinates, timezone, and continent. Alias: /location. With /{ip}, looks up any IP Premium

# Your IP
curl https://ipfast.dev/geo

# Arbitrary IP (premium)
curl -H "X-API-Key: sk_live_xxx" https://ipfast.dev/geo/8.8.8.8

Fields: ip, country, countryName, flag, city, region, regionCode, latitude, longitude, postalCode, timezone, continent, continentCode

GET /locale | GET /locale/{ip}

Localization-focused JSON preset. Returns country, timezone, languages, currency, calling code, and EU status. Ideal for i18n/l10n. Alias: /localization. With /{ip}, looks up any IP Premium

# Your IP
curl https://ipfast.dev/locale

# Arbitrary IP (premium)
curl -H "X-API-Key: sk_live_xxx" https://ipfast.dev/locale/1.1.1.1

Fields: ip, country, countryName, flag, timezone, languages, currency, currencyName, currencySymbol, callingCode, isEU

GET /network | GET /network/{ip}

Network-focused JSON preset. Returns IP, ASN, ISP organization, edge location, plus full connection info (TLS, protocol, RTT). With /{ip}, looks up any IP Premium

# Your IP
curl https://ipfast.dev/network

# Arbitrary IP (premium)
curl -H "X-API-Key: sk_live_xxx" https://ipfast.dev/network/9.9.9.9

Fields: ip, asn, asOrganization, colo, httpProtocol, tlsVersion, tlsCipher, clientTcpRtt, edgeRequestKeepAliveStatus

GET /meta | GET /meta/{ip}

Country metadata JSON preset. Returns flag, capital, continent, EU status, currency, calling code, languages, and TLD. Alias: /country-info. With /{ip}, looks up any IP Premium

# Your IP
curl https://ipfast.dev/meta

# Arbitrary IP (premium)
curl -H "X-API-Key: sk_live_xxx" https://ipfast.dev/meta/8.8.8.8

Fields: country, countryName, flag, capital, continent, continentCode, isEU, currency, currencyName, currencySymbol, callingCode, languages, tld

GET /connection

Returns connection security details as JSON. Includes TLS version, cipher suite, HTTP protocol, and TCP round-trip time. Useful for security auditing and protocol debugging.

curl https://ipfast.dev/connection

{
  "httpProtocol": "HTTP/2",
  "tlsVersion": "TLSv1.3",
  "tlsCipher": "AEAD-AES256-GCM-SHA384",
  "clientTcpRtt": 1,
  "edgeRequestKeepAliveStatus": 1
}

Field	Description
`httpProtocol`	HTTP protocol version: HTTP/1.1, HTTP/2, or HTTP/3 (QUIC)
`tlsVersion`	TLS version negotiated (e.g., TLSv1.2, TLSv1.3)
`tlsCipher`	TLS cipher suite used for encryption
`clientTcpRtt`	TCP round-trip time in milliseconds (network latency indicator)

GET /useragent

Returns parsed user agent details as JSON. The built-in parser extracts browser, OS, device type, and bot status from your User-Agent header. Alias: /ua

curl https://ipfast.dev/useragent

{
  "raw": "Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)",
  "browser": "Unknown",
  "browserVersion": "",
  "os": "Unknown",
  "osVersion": "",
  "device": "Bot",
  "isBot": true
}

Field	Description
`raw`	The original User-Agent string
`browser`	Browser name (Chrome, Firefox, Safari, Edge, Opera, Brave, Vivaldi, curl, Wget, HTTPie)
`browserVersion`	Browser version string
`os`	Operating system (Windows, macOS, iOS, Android, Linux, Chrome OS)
`osVersion`	OS version (e.g., "10/11" for Windows, "15.2" for iOS)
`device`	Device type: Desktop, Mobile, Tablet, Bot, or CLI
`isBot`	Boolean -- true if the UA matches known bot/crawler patterns

GET /headers

Returns all HTTP request headers as JSON. Useful for debugging proxy chains, CDN configurations, and seeing exactly what headers your client sends after all intermediaries have modified the request.

curl https://ipfast.dev/headers

Note: This endpoint is excluded from search engine indexing via robots.txt, as header data is session-specific.

Premium API

GET /json/{ip} — Arbitrary IP Lookup

Look up geolocation data for any IPv4 or IPv6 address. This is the foundation of all premium features. Requires Starter+

curl -H "X-API-Key: sk_live_xxx" https://ipfast.dev/json/8.8.8.8

{
  "ip": "8.8.8.8",
  "country": "US",
  "countryName": "United States",
  "city": "Mountain View",
  "region": "California",
  "timezone": "America/Los_Angeles",
  "latitude": "37.386",
  "longitude": "-122.0838",
  "postalCode": "94035",
  "asn": 15169,
  "asOrganization": "Google LLC",
  "colo": null
}

You can also look up single fields for any IP:

curl -H "X-API-Key: sk_live_xxx" https://ipfast.dev/country/8.8.8.8
US

curl -H "X-API-Key: sk_live_xxx" https://ipfast.dev/city/1.1.1.1
Los Angeles

All output formats work with arbitrary IP lookup: ?format=xml, ?format=yaml, ?format=csv

GET /country-meta/{ip} — Country Metadata

Get enriched country metadata for any IP address: currency, calling code, capital, languages, TLD, flag, continent, EU status. Requires Starter+

curl -H "X-API-Key: sk_live_xxx" https://ipfast.dev/country-meta/8.8.8.8

{
  "ip": "8.8.8.8",
  "country": "US",
  "country_meta": {
    "country_name": "United States",
    "capital": "Washington, D.C.",
    "continent": "Americas",
    "continent_code": "NA",
    "is_eu": false,
    "flag_emoji": "\ud83c\uddfa\ud83c\uddf8",
    "calling_code": "+1",
    "tld": ".us",
    "languages": ["English"],
    "currency": { "code": "USD", "name": "US Dollar", "symbol": "$" }
  }
}

All 196 countries are supported. Data is embedded in the worker -- zero external API calls.

GET /company/{ip} — Company Detection

Identify the company or organization that owns/operates an IP address. Classifies into ISP, hosting, business, education, or government. Requires Pro+

curl -H "X-API-Key: sk_live_xxx" https://ipfast.dev/company/8.8.8.8

{
  "ip": "8.8.8.8",
  "company": {
    "name": "Google LLC",
    "domain": "google.com",
    "type": "hosting"
  }
}

Type	Description
`isp`	Internet service provider (residential/commercial)
`hosting`	Cloud/hosting provider (AWS, GCP, Azure, DO, etc.)
`business`	Enterprise or business network
`education`	University or educational institution
`government`	Government network

GET /distance/{ip1}/{ip2} — Distance Calculator

Calculate the geographic distance between two IP addresses using the Haversine formula. Requires Pro+

# Distance between two IPs
curl -H "X-API-Key: sk_live_xxx" https://ipfast.dev/distance/8.8.8.8/1.1.1.1

{
  "from": { "ip": "8.8.8.8", "latitude": 37.386, "longitude": -122.0838 },
  "to": { "ip": "1.1.1.1", "latitude": 34.0544, "longitude": -118.2441 },
  "distance_km": 493.2,
  "distance_miles": 306.5
}

# Distance from IP to coordinates
curl -H "X-API-Key: sk_live_xxx" "https://ipfast.dev/distance/8.8.8.8?lat=51.5074&lon=-0.1278"

GET /security/{ip} — VPN/Proxy/Tor Detection

Detect VPN providers, proxy networks, Tor exit nodes, and datacenter IPs. Uses 10,000+ VPN CIDR ranges (updated daily), ASN-based detection, reverse DNS hostname analysis, and Tor exit node feeds. Requires Business plan.

curl -H "X-API-Key: sk_live_xxx" https://ipfast.dev/security/2.56.16.1

{
  "ip": "2.56.16.1",
  "country": "VN",
  "asn": 9009,
  "organization": "M247 Europe SRL",
  "security": {
    "is_vpn": true,
    "is_proxy": false,
    "is_tor": false,
    "is_datacenter": true,
    "is_residential": false,
    "threat_score": 40,
    "classification": "vpn",
    "hostname": "vlan180.agg1.fra4.de.m247.com"
  }
}

Classification types

What we detect

Commercial VPN providers (NordVPN, ExpressVPN, Mullvad, PIA, Surfshark, etc.)
Enterprise VPN gateways (Zscaler, Palo Alto, Fortinet, Cisco AnyConnect)
Proxy networks and anonymizers
Tor exit nodes
Datacenter and cloud provider IPs
Residential vs hosting classification

Detection data is refreshed daily for maximum accuracy.

GET /threat/{ip} — Threat Intelligence

Threat assessment combining security classification with known attacker databases. Requires Business plan.

curl -H "X-API-Key: sk_live_xxx" https://ipfast.dev/threat/20.219.190.139

{
  "ip": "20.219.190.139",
  "country": "IN",
  "asn": 8075,
  "organization": "Microsoft Corporation",
  "threat": {
    "threat_level": "high",
    "threat_score": 50,
    "categories": ["datacenter", "non_residential", "known_attacker"],
    "is_known_attacker": true,
    "is_known_abuser": false,
    "is_bot": true,
    "recommendation": "challenge"
  }
}

Threat levels

Level	Score	Recommendation
`low`	0-29	`allow`
`medium`	30-49	`challenge`
`high`	50-69	`challenge`
`critical`	70-100	`block`

GET /risk/{ip} — IP Risk Score

Comprehensive fraud risk assessment. Combines anonymizer detection, network analysis, country risk tiers, and threat intelligence into a single risk score. Requires Business plan.

curl -H "X-API-Key: sk_live_xxx" https://ipfast.dev/risk/8.8.8.8

{
  "ip": "8.8.8.8",
  "country": "US",
  "city": "",
  "asn": 15169,
  "organization": "Google LLC",
  "risk": {
    "risk_score": 15,
    "risk_level": "low",
    "ip_type": "datacenter",
    "anonymizer": {
      "is_anonymous": false,
      "is_vpn": false,
      "is_proxy": false,
      "is_tor": false,
      "is_relay": false
    },
    "network": {
      "is_datacenter": true,
      "is_residential": false,
      "is_hosting": false,
      "asn": 15169,
      "organization": "Google LLC",
      "network_type": "corporate"
    },
    "country_risk": {
      "country": "US",
      "risk_level": "low"
    },
    "recommendation": "allow",
    "reasons": ["Datacenter/hosting IP"]
  }
}

Risk levels

Level	Score	Action
`minimal`	0-9	`allow`
`low`	10-19	`allow`
`medium`	20-49	`monitor`
`high`	50-74	`challenge`
`critical`	75-100	`block`

Risk scoring factors

Tor exit node: +40 points
Known proxy network: +35 points
VPN provider: +20 points
Any anonymizer: +5 points
Datacenter IP: +15 points
High-risk country: +15 points
Medium-risk country: +7 points
Residential + low-risk country: -10 points (bonus)

GET /rdns/{ip} — Reverse DNS

Resolve an IP address to its hostname(s) via PTR record lookup. Free with your API key.

curl https://ipfast.dev/rdns/8.8.8.8
# {"ip":"8.8.8.8","hostnames":["dns.google"],"query_time_ms":20}

Supports both IPv4 and IPv6. Results cached for 5 minutes.

GET /asn/{asn} — ASN Info

Look up an Autonomous System Number to get organization details. Free endpoint. Accepts AS15169 or 15169 format.

curl https://ipfast.dev/asn/AS15169
# {"asn":15169,"name":"Google LLC","domain":"google.com","type":"business","network":"AS15169"}

Returns: name, domain, type (isp/hosting/business/education/government), network.

POST /bulk — Bulk IP Lookup

Look up multiple IP addresses in a single request. Pro: up to 50 IPs. Business: up to 100 IPs. Requires Pro+

curl -X POST -H "X-API-Key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"ips":["8.8.8.8","1.1.1.1","9.9.9.9"]}' \
  https://ipfast.dev/bulk

{
  "count": 3,
  "results": [
    { "ip": "8.8.8.8", "country": "US", "city": "Mountain View", ... },
    { "ip": "1.1.1.1", "country": "US", "city": "Los Angeles", ... },
    { "ip": "9.9.9.9", "country": "US", "city": "Berkeley", ... }
  ]
}

You can enrich bulk results with modules: ?modules=country_meta,company

Modular Enrichment (?modules=)

Add ?modules= to any JSON response to enrich it with additional data. Combine multiple modules with commas. Each module requires a minimum plan tier.

# Single module
curl -H "X-API-Key: sk_live_xxx" "https://ipfast.dev/json/8.8.8.8?modules=country_meta"

# Multiple modules
curl -H "X-API-Key: sk_live_xxx" "https://ipfast.dev/json/8.8.8.8?modules=country_meta,company"

Module	Min Plan	Adds
`country_meta`	Starter	Currency, capital, languages, flag, TLD, continent, EU status
`company`	Pro	Organization name, domain, type (ISP/hosting/business/edu/gov)
`security`	Business	VPN/proxy/Tor detection, datacenter classification, threat score
`threat`	Business	Threat level, categories, known attacker status, recommendation
`risk`	Business	Risk score, anonymizer breakdown, network analysis, country risk

If your plan doesn't include a module, it will be listed in _gated_modules in the response instead of being silently dropped.

Pay-Per-Request with x402

Premium endpoints support pay-per-request using the x402 protocol (HTTP 402 Payment Required). No subscription or API key needed -- pay with USDC on Base network.

How it works

Call a premium endpoint without an API key. You get a 402 response with payment details.
Sign the payment with your wallet using the x402 client SDK.
Retry the request with the signed payment in the X-PAYMENT header.
Your request is served. Settlement happens in the background (~1 second).

Pricing

Endpoint	Price
`/json/{ip}`	$0.001 USDC
`/country-meta/{ip}`	$0.001 USDC
`/company/{ip}`	$0.002 USDC
`/distance/{ip1}/{ip2}`	$0.002 USDC
`POST /bulk`	$0.01 USDC

Client integration

import { x402Client, wrapFetchWithPayment } from '@x402/fetch';
import { ExactEvmScheme } from '@x402/evm/exact/client';
import { privateKeyToAccount } from 'viem/accounts';

const signer = privateKeyToAccount(process.env.WALLET_KEY);
const client = new x402Client();
client.register('eip155:*', new ExactEvmScheme(signer));
const paidFetch = wrapFetchWithPayment(fetch, client);

// Automatically handles 402 -> sign -> retry
const res = await paidFetch('https://ipfast.dev/json/8.8.8.8');
const data = await res.json();

API key holders are never charged per-request. If you have a valid API key, all premium endpoints are included in your subscription.

Pricing API

Machine-readable pricing is available at /pricing.json. Use it to discover current per-request costs programmatically.

curl https://ipfast.dev/pricing.json

{
  "x402Version": 1,
  "network": "eip155:84532",
  "endpoints": {
    "ip-lookup": { "amount": "1000", "description": "..." },
    "ip-company": { "amount": "2000", "description": "..." },
    ...
  }
}

JSON Format

JSON is the default format for all structured endpoints (/json, /all, /connection, /useragent, /headers). Responses are pretty-printed with 2-space indentation for readability.

curl https://ipfast.dev/json

XML Format

Get IP geolocation as XML with a root <ipInfo> element. Compatible with .NET, Java, SOAP services, and any system that consumes XML.

curl https://ipfast.dev/xml

<?xml version="1.0" encoding="UTF-8"?>
<ipInfo>
  <ip>216.73.216.14</ip>
  <country>US</country>
  <city>Columbus</city>
  ...
</ipInfo>

YAML Format

Get IP geolocation as YAML. Useful for embedding in configuration files, Ansible playbooks, or any tool that consumes YAML natively.

curl https://ipfast.dev/yaml

ip: 216.73.216.14
country: US
city: Columbus
...

CSV Format

Get IP geolocation as CSV with a header row followed by a data row. Import directly into Excel, Google Sheets, or any data processing pipeline.

curl https://ipfast.dev/csv

ip,country,countryName,city,region,timezone,...
216.73.216.14,US,...

JSONP

Add ?callback=functionName to any JSON endpoint for JSONP output. The callback name is validated against /^[$A-Za-z_][$A-Za-z0-9_.]*$/ to prevent XSS injection.

curl "https://ipfast.dev/json?callback=myCallback"

/**/ typeof myCallback === 'function' && myCallback({"ip":"216.73.216.14",...});

JSONP is primarily useful for legacy cross-domain integrations. For modern applications, use the standard JSON endpoints with CORS (which is enabled for all origins).

Format Override

Add ?format=xml|yaml|csv to the /json endpoint to get data in a different format without changing the URL path. This is useful when you want to switch formats with a query parameter instead of changing the endpoint.

curl "https://ipfast.dev/json?format=yaml"

ip: 216.73.216.14
country: US
...

JavaScript SDK

Lightweight client library. Load from CDN — works in browsers and Node.js 18+:

<script src="https://ipfast.dev/sdk.js"></script>
<script>
  // Configure API key (optional, needed for premium endpoints)
  ipfast.config({ apiKey: 'sk_live_xxx' })

  // Your IP — free with API key
  const me = await ipfast.json()
  console.log(me.ip, me.city, me.countryName)

  // Arbitrary IP lookup (premium)
  const data = await ipfast.json('8.8.8.8')

  // Single field — free for your IP, premium for arbitrary
  const country = await ipfast.field('country')
  const usCity = await ipfast.field('city', '8.8.8.8')

  // Presets — all support optional IP parameter
  const geo = await ipfast.geo()
  const loc = await ipfast.locale('1.1.1.1')

  // Security & Threat Intelligence (premium)
  const sec = await ipfast.security('8.8.8.8')
  const threat = await ipfast.threat('8.8.8.8')
  const risk = await ipfast.risk('8.8.8.8')

  // Company detection (premium)
  const co = await ipfast.company('8.8.8.8')

  // Bulk lookup (premium)
  const batch = await ipfast.bulk(['8.8.8.8', '1.1.1.1', '9.9.9.9'])
</script>

Source: /sdk.js (2KB, no dependencies)

JavaScript / TypeScript

Works in both browser and Node.js environments. CORS is enabled for all origins, so no proxy is needed.

// Browser or Node.js 18+
const response = await fetch('https://ipfast.dev/json');
const data = await response.json();

console.log(data.ip);        // "216.73.216.14"
console.log(data.country);   // "US"
console.log(data.city);      // "Columbus"
console.log(data.timezone);  // "America/New_York"

// Get just the IP as text
const ip = await fetch('https://ipfast.dev/text').then(r => r.text());

Python

Using the requests library (most common) or the built-in urllib module.

import requests

# Full geolocation
data = requests.get('https://ipfast.dev/json').json()
print(f"IP: {data['ip']}")
print(f"Location: {data['city']}, {data['country']}")
print(f"Timezone: {data['timezone']}")
print(f"ISP: {data['asOrganization']}")

# Just the IP
ip = requests.get('https://ipfast.dev/text').text.strip()
print(f"My IP: {ip}")

Go

package main

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

func main() {
    resp, _ := http.Get("https://ipfast.dev/json")
    defer resp.Body.Close()

    var info map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&info)
    fmt.Println("IP:", info["ip"])
    fmt.Println("Country:", info["country"])
    fmt.Println("City:", info["city"])
}

Laravel / PHP

Using Laravel's HTTP client for clean, fluent API calls:

use Illuminate\Support\Facades\Http;

// Your IP geolocation (free)
$data = Http::get('https://ipfast.dev/json')->json();
$data['ip'];       // "88.238.231.82"
$data['country'];  // "TR"
$data['city'];     // "Istanbul"

// Arbitrary IP lookup (premium)
$google = Http::withHeaders([
    'X-API-Key' => config('services.ipfast.key'),
])->get('https://ipfast.dev/json/8.8.8.8')->json();

// Security check — VPN/proxy/Tor detection
$security = Http::withHeaders([
    'X-API-Key' => config('services.ipfast.key'),
])->get('https://ipfast.dev/security/8.8.8.8')->json();

if ($security['security']['is_vpn']) {
    Log::warning('VPN detected', ['ip' => '8.8.8.8']);
}

// Risk scoring for fraud prevention
$risk = Http::withHeaders([
    'X-API-Key' => config('services.ipfast.key'),
])->get('https://ipfast.dev/risk/' . $request->ip())->json();

if ($risk['risk']['risk_score'] >= 50) {
    return response()->json(['error' => 'High risk'], 403);
}

// Bulk lookup
$batch = Http::withHeaders([
    'X-API-Key' => config('services.ipfast.key'),
])->post('https://ipfast.dev/bulk', [
    'ips' => ['8.8.8.8', '1.1.1.1', '9.9.9.9'],
])->json();

Add IPFAST_API_KEY to your .env and 'ipfast' => ['key' => env('IPFAST_API_KEY')] to config/services.php.

Bash / Shell

The plain text endpoints are designed for shell scripting -- no JSON parser needed.

# Just your IP
MY_IP=$(curl -s ipfast.dev/text)
echo "My IP: $MY_IP"

# Individual fields (no JSON parsing)
COUNTRY=$(curl -s ipfast.dev/country)
CITY=$(curl -s ipfast.dev/city)
TZ=$(curl -s ipfast.dev/timezone)
echo "Location: $CITY, $COUNTRY ($TZ)"

# Full JSON (pipe to jq for specific fields)
curl -s ipfast.dev/json | jq '{ip, country, city, timezone}'

PowerShell

# Full geolocation
$data = Invoke-RestMethod -Uri "https://ipfast.dev/json"
$data.ip
$data.city
$data.country
$data.timezone

# Just the IP
$ip = Invoke-RestMethod -Uri "https://ipfast.dev/text"
Write-Host "My IP: $ip"

PHP

<?php
// Full geolocation
$data = json_decode(file_get_contents('https://ipfast.dev/json'), true);
echo "IP: " . $data['ip'] . "\n";
echo "Country: " . $data['country'] . "\n";
echo "City: " . $data['city'] . "\n";

// Just the IP
$ip = trim(file_get_contents('https://ipfast.dev/text'));
echo "My IP: $ip\n";

Ruby

require 'net/http'
require 'json'

# Full geolocation
uri = URI('https://ipfast.dev/json')
data = JSON.parse(Net::HTTP.get(uri))
puts "IP: #{data['ip']}"
puts "Location: #{data['city']}, #{data['country']}"

# Just the IP
ip = Net::HTTP.get(URI('https://ipfast.dev/text')).strip
puts "My IP: #{ip}"

llms.txt

Machine-readable service description for AI agents and Large Language Models. This file follows the llms.txt convention for making APIs discoverable by AI systems.

curl https://ipfast.dev/llms.txt

Also available at /llms-full.txt with the same content.

AI Plugin Manifest

OpenAI-compatible AI plugin manifest. Enables ChatGPT and other AI assistants to discover and use the IP Info API as a tool.

curl https://ipfast.dev/.well-known/ai-plugin.json

OpenAPI 3.1 Specification

Machine-readable API specification following the OpenAPI 3.1 standard. Can be imported into Swagger UI, Postman, Insomnia, or any OpenAPI-compatible tool.

curl https://ipfast.dev/openapi.json

XML Sitemap

Standard XML sitemap for search engine crawlers. Lists all public pages with change frequencies and priorities.

curl https://ipfast.dev/sitemap.xml