How to Use IPWHOIS.io: IP Geolocation API Guide

IPWHOIS.io is an IP intelligence API that returns geolocation, network, timezone, currency, and security data for any IPv4 or IPv6 address. You can start with a single HTTP GET request — no API key, no registration, no SDK. This guide walks through the free and Pro endpoints, request parameters, response fields, rate limits, and practical ways to validate the data you get back.

What IPWHOIS.io Actually Returns

How to Use IPWHOIS.io: IP Geolocation API Guide - What IPWHOIS.io Actually Returns.

Every lookup answers a simple question: what is known about this IP address? The response is structured JSON (or XML/CSV) covering four data groups:

• Location — continent, country, region, city, postal code, latitude/longitude, EU membership, capital, bordering countries, and calling code.
• Network — ASN, organization, ISP name, and the domain tied to the owning organization.
• Context — timezone ID, UTC offset, daylight saving status, current local time, currency name, ISO code, symbol, and exchange rate against the USD.
• Security — flags for proxy, VPN, Tor, hosting/cloud, Apple iCloud Private Relay, mobile carrier networks, and a combined anonymous boolean.

A native object also translates place names and currency into the local language of the country the IP belongs to, which is useful when you want to display a city name the way local users write it.

Step 1: Make Your First Free Request

How to Use IPWHOIS.io: IP Geolocation API Guide - Step 1: Make Your First Free Request.

The free endpoint lives at ipwho.is and needs no token. Send a GET request with the IP you want to inspect, or omit it to look up the caller's own address:

# Your own IP
curl "http://ipwho.is/"

# A specific IPv4 address
curl "http://ipwho.is/8.8.4.4"

# HTTPS works too, and is required for browser-based calls from secure pages
curl "https://ipwho.is/8.8.4.4"

A successful response starts with "success": true and includes the ip, type (IPv4 or IPv6), and the data groups described above. If the query fails, success is false and a message field explains why.

Tip: When you call the API from JavaScript on a website, requests are counted per domain rather than per visitor IP. That means a popular page can burn through the daily quota quickly — cache responses server-side instead of calling the API on every page view.

Step 2: Trim the Response with Field Selection

You rarely need every field. Request only what you will render to keep payloads small and parsing simple:

# Only timezone data
curl "http://ipwho.is/8.8.4.4?fields=timezone"

# Only currency data
curl "http://ipwho.is/8.8.4.4?fields=currency"

# Only security signals
curl "http://ipwho.is/8.8.4.4?fields=security"

This is the single biggest performance win for front-end integrations. A currency widget does not need latitude, longitude, and border codes, and a fraud check does not need flag emoji.

Step 3: Choose the Right Endpoint Tier

How to Use IPWHOIS.io: IP Geolocation API Guide - Step 3: Choose the Right Endpoint Tier.

IPWHOIS.io splits access into three tiers. Match the tier to your workload rather than defaulting to the cheapest option.

Tier	Cost	Requests	Key limits and extras
Free	$0	1,000 / day per client IP	Standard accuracy, no native-language data, no currency or security data, no bulk endpoint, no SLA
Pro	From $19.99/mo	600K to unlimited / month	Enhanced accuracy, native-language data, currency and security data, bulk endpoint (up to 100 IPs per call), dashboard, 99.99% uptime SLA
Bulk	Pro feature	Up to 100 IPs per call	Designed for batch enrichment jobs

Commercial use is allowed on every plan, including Free. The practical breakpoint is the security object: proxy, VPN, Tor, and hosting detection are Pro features, so if your use case is fraud prevention rather than content personalization, budget for Pro from the start.

Step 4: Handle Rate Limits Correctly

When you exceed the Free limit, the API returns HTTP 429 (Too Many Requests) along with a Retry-After header that tells you how many seconds remain until the quota resets. Access restores automatically after 24 hours.

Production-ready handling looks like this:

1. Read Retry-After and back off for that duration instead of retrying immediately.
2. Cache each IP's result — geolocation data does not change minute to minute.
3. Log 429s separately from other errors so you can tell quota exhaustion apart from a malformed request.
4. Move to Pro before you hit the ceiling in normal traffic, not after an outage.

Step 5: Use the Data in Real Applications

Common patterns that map cleanly onto the response fields:

• Localized storefronts — read currency.code and currency.exchange_rate to show prices in the visitor's currency without a separate FX service.
• Time-aware UI — use timezone.id and timezone.current_time to schedule messages, support hours, or delivery windows in the user's own clock.
• Form autofill — prefill country, calling code, and postal code from the location block to cut friction at checkout.
• Fraud screening — compare the billing country with country_code, and treat security.proxy, security.vpn, security.tor, and security.hosting as risk signals rather than verdicts.
• Traffic routing — send visitors to the correct regional site version or language using country_code and is_eu.

Step 6: Verify What the API Tells You

An API response is a claim about an IP, not proof of who is behind it. Two habits keep your integration honest:

Check your own connection first. Before you trust a geolocation result for your own traffic, confirm what your browser and network are actually exposing. A free IP address lookup and privacy check shows your visible IP, geolocation, ISP, and proxy signals side by side, which is a fast way to spot a VPN that is not routing the way you assumed. If the API says "proxy: false" but your own connection test shows a datacenter ASN, you have found a data gap worth logging.

Test the browser layer separately. IP data says nothing about fingerprinting or leaks. Run a fingerprint test to see how unique your browser looks, and a DNS and WebRTC leak check to confirm your real IP is not escaping through a side channel. Together with IPWHOIS.io output, these give you a full picture: network identity from the API, device identity from the browser.

Sanity-check the security flags. VPN, proxy, and Tor detection relies on continuously updated datasets. False positives happen with corporate NAT ranges and legitimate cloud infrastructure. Treat security.hosting: true as "this is a datacenter IP," not "this is an attacker."

For teams building broader detection workflows around this kind of data, the operational patterns in this IT security operations guide are a useful reference for turning raw signals into triage decisions.

Step 7: Pick a Response Format

JSON is the default and the right choice for most applications. XML and CSV are available when you are feeding a legacy system or a spreadsheet pipeline. If you are already standardizing on another geolocation provider, the setup steps in this BigDataCloud SDK and client guide show how comparable IP-data clients are installed and verified — useful for comparing integration effort before you commit.

Common Pitfalls to Avoid

• Calling the API on every page load. Cache aggressively; IP location is stable for long periods.
• Ignoring IPv6. The API accepts both address types, but a schema that assumes dotted-quad strings will break.
• Assuming city-level precision. IP geolocation resolves to a region or city area, not a street address. Never use it as proof of a person's physical location.
• Hardcoding field names. Request only the fields you need, but parse defensively — available fields vary by plan and request parameters.
• Skipping error handling. A success: false response with a message is a normal outcome, not an exception.

Related reading

• Online Port Scanner: Free Nmap-Powered Tool to Check Open Ports - Scan open TCP/UDP ports instantly with a free online port scanner. Learn how port scanning works, what results mean, and how to secure exposed services.
• Secure Messaging in 2026: How to Choose and Verify Privacy - Compare secure messaging apps by encryption, metadata, and identity design, plus how to verify your browser, IP, and DNS aren't leaking your privacy.
• Fingerprint Test: Check What Your Browser Reveals - Run a free fingerprint test to see how unique and trackable your browser is, what data it exposes, and how to reduce your digital fingerprint.

Sources and further reading

• Fast, Accurate Geolocation Data with IPWHOIS.io - In the world of marketing and content targeting, having accurate geolocation data can be the difference between a thriving enterprise and a floundering

FAQ

Do I need an API key to use IPWHOIS.io? No. The Free endpoint requires no token or registration. Pro plans use an API key managed through the dashboard.

What is the free request limit? 1,000 requests per day per client IP address. Browser-based CORS requests are counted per domain instead, shared across all visitors.

Can I look up my own IP without specifying an address? Yes. Calling http://ipwho.is/ with no IP returns data for the requesting address.

Does the free plan include VPN and proxy detection? No. Currency data, security data, and native-language responses are Pro features.

How accurate is the geolocation? The Pro tier offers enhanced accuracy, and the underlying database is updated multiple times per day using AI-assisted aggregation from regional internet registries and other sources. Accuracy is strongest at country level and weaker at city level.

Can I use it commercially for free? Yes, commercial use is permitted on all plans, including Free, within the rate limit.

What happens when I hit the limit? You receive HTTP 429 with a Retry-After header. Access resumes automatically after 24 hours.

Conclusion

IPWHOIS.io is deliberately simple: one GET request returns location, network, timezone, currency, and security data with no setup overhead. Start on the free endpoint to prototype, use field selection to keep payloads lean, and upgrade to Pro when you need security signals, bulk lookups, or an uptime guarantee. Then verify the results against your own connection — pairing API output with a browser-level privacy check is the difference between trusting a data point and actually knowing what your network is exposing.

For reference, see the official IPWHOIS.io documentation and the IPWHOIS.io homepage.