IPWHOIS.io Setup Guide: API, Python & Verification

Setting up IPWHOIS.io is not a single task. The name covers two different tools: the hosted IP geolocation and IP intelligence API at ipwhois.io, and the open-source Python library ipwhois that retrieves and parses WHOIS and RDAP records. This guide separates them, shows the exact setup steps for each, and explains how to verify that the data you receive actually matches your real connection.

What "IPWHOIS.io setup" actually means

Before you install or call anything, decide which of these you need:

• Hosted REST API (ipwhois.io / ipwho.is): returns geolocation, timezone, currency, connection, and security flags for an IP address. No registration is required on the free tier.
• Python ipwhois package: queries RDAP and legacy WHOIS servers directly and parses the results into a standard dictionary. It is a separate open-source project, not part of the commercial API.

If your goal is to show a visitor's country, currency, or timezone, you want the REST API. If your goal is to look up network registration details, abuse contacts, or ASN ownership, you want the Python library.

Setting up the IPWHOIS.io REST API

IPWHOIS.io Setup Guide: API, Python & Verification - Setting up the IPWHOIS.io REST API.

The hosted API is the fastest path. You can test it from a terminal before writing any application code.

Step 1: Make a test request

The free tier does not require an access token, so a single curl call is enough to confirm connectivity:

curl "http://ipwho.is/8.8.4.4"

The response includes fields such as country, region, city, latitude, longitude, and connection details. If you only need one field, request it explicitly to keep payloads small:

curl "http://ipwho.is/8.8.4.4?fields=timezone"
curl "http://ipwho.is/8.8.4.4?fields=currency"
curl "http://ipwho.is/8.8.4.4?fields=security"

Step 2: Understand the security fields

The security object is the part most privacy and fraud teams care about. It reports flags such as anonymous, proxy, vpn, tor, and hosting. A true value on any of these tells you the request is probably not coming from a residential connection.

Step 3: Plan for rate limits and upgrades

The free plan allows up to 1,000 requests per day, which is fine for prototyping and small projects. Commercial use is permitted on all plans, including free. Move to a paid plan when you need higher limits, bulk lookups, threat intelligence, or an uptime SLA.

Step 4: Handle failures in code

Any network call can fail. Wrap requests with a timeout and a fallback so a slow geolocation response never blocks your page render. Cache results per IP for a short period instead of calling the API on every request.

For a deeper look at the data model behind these responses, see this guide to an API for IP data, which covers geolocation, proxy detection, and rate-limit planning.

Setting up the Python ipwhois library

The Python package solves a different problem: it talks to RDAP and WHOIS servers and normalizes the messy output.

Install the package

pip install --upgrade ipwhois

Run an RDAP lookup

RDAP is the recommended method because it returns structured JSON rather than free-form text:

from ipwhois import IPWhois

obj = IPWhois("8.8.4.4")
result = obj.lookup_rdap()
print(result["asn"], result["asn_description"])

Know which ports must be open

The library needs outbound access on several ports depending on the lookup type:

• 53/tcp for ASN lookups over DNS
• 43/tcp for legacy WHOIS and ASN WHOIS
• 80/tcp and 443/tcp for RDAP and NIR queries over HTTP/HTTPS

If your server sits behind a restrictive firewall, RDAP over HTTPS is usually the easiest path because it reuses standard web ports.

Choose RDAP or legacy WHOIS

Method	Output quality	Best for
RDAP	Structured, includes contacts and entities	Modern applications, automation
Legacy WHOIS	Free-form text, parsed into a dictionary	Older registries, fallback coverage

RDAP also provides more detailed network information, which makes it the better default. Legacy WHOIS remains useful as a fallback when a registry does not yet support RDAP.

The library's official documentation is the authoritative reference for arguments such as timeout, proxy_opener, and inc_nir: ipwhois documentation.

REST API vs Python library: which should you set up?

IPWHOIS.io Setup Guide: API, Python & Verification - REST API vs Python library: which should you set up?.

• Use the REST API when you need to personalize content, auto-fill forms, display local currency, or flag suspicious traffic in real time.
• Use the Python library when you need registration data, abuse contacts, or ASN ownership for investigations, reporting, or security tooling.
• Use both when you are building a fraud pipeline: the API flags VPN or proxy usage, and the library tells you who owns the network behind that IP.

Verifying that the data matches your real connection

Geolocation data is only useful if it reflects reality. Two checks are worth running before you trust any lookup result.

First, confirm what IP address the outside world sees. If you are on a VPN, a leak test will show whether your real address is exposed through WebRTC or DNS. Second, compare the API's reported city and ISP against your known location. Small discrepancies are normal because IP geolocation is approximate, but a completely different country usually means the request is exiting through a proxy or hosting provider.

BrowserScan's free IP address lookup tool does exactly this kind of cross-check: it reports geolocation, ISP, and proxy signals for your current connection without any installation. Running it alongside your API response is a quick way to spot mismatches.

Common setup mistakes

• Hardcoding the API call on every page load. Cache per IP and respect the daily request limit.
• Assuming city-level accuracy. IP geolocation is reliable at the country level and approximate at the city level.
• Ignoring the hosting flag. Many legitimate users on cloud or corporate networks will trip this flag, so treat it as a signal, not a verdict.
• Forgetting firewall rules for the Python library. Port 43 and port 53 are commonly blocked.
• Mixing up the two products. The Python package and the hosted API are maintained separately and have different update cycles.

Related reading

• IP Address Detection: How It Works and How to Verify It - Learn how IP address detection works, what it reveals about you, how VPN leaks expose your real IP, and how to test your connection with free tools.
• OpenVAS Scanner: How the Open Vulnerability Assessment Scanner Works - OpenVAS Scanner explained: what it is, how the Greenbone feed works, authenticated vs unauthenticated scans, setup options, and how to verify your own exposure.
• IP to Location: How It Works, Accuracy, and Privacy - Learn how IP to location lookup works, why city-level accuracy varies, what data you can get, and how to check your own IP with free privacy tests.

Sources and further reading

• IP Geolocation API - IPWHOIS.io - Free IP Geolocation and IP Location Lookup API
• ipwhois - Retrieve and parse whois data for IPv4 and IPv6 addresses.
• ipwhois Documentation - Oct 15, 2024 ... https://ipwhois.readthedocs.io/en/latest/RDAP.html#input. Legacy ... IPWhois settings: --timeout TIMEOUT The default timeout for socket ...

FAQ

Do I need an API key for IPWHOIS.io?

No. The free plan does not require an access token, so you can start testing immediately. Paid plans add higher limits and advanced features.

How many requests does the free plan allow?

Up to 1,000 requests per day, which suits small projects and development work.

Is the Python ipwhois library the same as the ipwhois.io API?

No. The Python package is an independent open-source project that queries RDAP and WHOIS servers. The hosted API returns geolocation and security data over HTTP.

Which lookup method should I use, RDAP or legacy WHOIS?

Use RDAP when the registry supports it because the output is structured and includes more detail. Fall back to legacy WHOIS for registries that have not adopted RDAP.

Can I use the API on a commercial site?

Yes. Commercial use is allowed on all plans, including the free tier.

How accurate is IP geolocation?

Country-level results are generally dependable, while city-level results vary by ISP and region. Treat coordinates as an estimate rather than a precise address.

Conclusion

IPWHOIS.io setup comes down to picking the right tool for the job. Use the hosted REST API for geolocation, currency, timezone, and VPN or proxy flags, and use the Python ipwhois library when you need RDAP or WHOIS registration data. Test with curl first, plan for rate limits and firewall ports, and verify your results against an independent check so you know the data matches your real connection.