ipwhois-python

KO | EN

gitlite — search

#shell #http #csharp #computer-vision #large-language-models #monitoring #ai-agent #cloud-native #markdown #agent

(★ 9)

Official Python client library for the IPWhois API

File Explorer

ZIP Download

- basic.py
- bulk.py
- defaults.py
- - __init__.py
  - ipwhois.py
  - py.typed
- test_ipwhois.py
.gitignore
CHANGELOG.md
LICENSE
pyproject.toml
README.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

# Project Badges

PyPI Version Visit
Python Versions Visit
License Visit

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Official, dependency-free Python client for the [ipwhois.io](https://ipwhois.io) IP Geolocation API.

- ✅ Single and bulk IP lookups (IPv4 and IPv6)
- ✅ Works with both the **Free** and **Paid** plans
- ✅ HTTPS by default
- ✅ Localisation, field selection, threat detection, rate info
- ✅ Never raises — all errors returned as `success: False` dicts
- ✅ No external dependencies — only the Python standard library
- ✅ Python 3.8+

## Installation

```bash
pip install ipwhois-python
```

## Free vs Paid plan

The same `IPWhois` class is used for both plans. The only difference is whether
you pass an API key:

- **Free plan** — create the client **without arguments**. No API key, no
  signup required. Suitable for low-traffic and non-commercial use.
- **Paid plan** — create the client **with your API key** from
  <https://ipwhois.io>. Higher limits, plus access to bulk lookups and
  threat-detection data.

```python
from ipwhois import IPWhois

free = IPWhois()                 # Free plan — no API key
paid = IPWhois("YOUR_API_KEY")   # Paid plan — with API key
```

Everything else (`lookup()`, options, error handling) is identical.

## Quick start — Free plan (no API key)

```python
from ipwhois import IPWhois

ipwhois = IPWhois()  # no API key

info = ipwhois.lookup("8.8.8.8")

print(info["country"], info["flag"]["emoji"])
# → United States 🇺🇸

print(f"{info['city']}, {info['region']}")
# → Mountain View, California
```

## Quick start — Paid plan (with API key)

Get an API key at <https://ipwhois.io> and pass it to the constructor:

```python
from ipwhois import IPWhois

ipwhois = IPWhois("YOUR_API_KEY")  # with API key

info = ipwhois.lookup("8.8.8.8")

print(info["country"], info["flag"]["emoji"])
# → United States 🇺🇸

print(f"{info['city']}, {info['region']}")
# → Mountain View, California
```

> ℹ️ Pass nothing to look up your own public IP: `ipwhois.lookup()` — works
> on both plans.

## Lookup options

Every option below can be passed per call as a keyword argument, or set once
on the client as a default.

| Option       | Type    | Plans needed         | Description                                                            |
| ------------ | ------- | -------------------- | ---------------------------------------------------------------------- |
| `lang`       | str     | Free + Paid          | One of: `en`, `ru`, `de`, `es`, `pt-BR`, `fr`, `zh-CN`, `ja`           |
| `fields`     | list    | Free + Paid          | Restrict the response to specific fields (e.g. `["country", "city"]`)  |
| `rate`       | bool    | Basic and above      | Include the `rate` block (`limit`, `remaining`)                        |
| `security`   | bool    | Business and above   | Include the `security` block (proxy/vpn/tor/hosting)                   |

### Setting defaults once

Every option can be passed two ways: **per call** (as a keyword argument to
`lookup()` / `bulk_lookup()`) or **once as a default** on the client. Per-call
options always override the defaults, so it's safe to set sensible defaults
and only override what differs for a specific call.

Defaults are set with fluent setters — `set_language()`, `set_fields()`,
`set_security()`, `set_rate()`, `set_timeout()`, `set_connect_timeout()`,
`set_user_agent()` — and can be chained:

```python
from ipwhois import IPWhois

# Free plan
ipwhois = (
    IPWhois()
    .set_language("en")
    .set_fields(["success", "country", "city", "flag.emoji"])
    .set_timeout(8)
)
```

```python
from ipwhois import IPWhois

# Paid plan
ipwhois = (
    IPWhois("YOUR_API_KEY")
    .set_language("en")
    .set_fields(["success", "country", "city", "flag.emoji"])
    .set_timeout(8)
)
```

Either client behaves the same way at call time — per-call options always
win over the defaults:

```python
ipwhois.lookup("8.8.8.8")              # uses lang=en, the field whitelist, and timeout=8
ipwhois.lookup("1.1.1.1", lang="de")   # overrides lang for this single call only
```

> ⚠️ When you restrict fields with `set_fields()` (or the per-call `fields=`
> keyword), the API only returns the fields you ask for. Always include
> `"success"` in the list if you rely on `info["success"]` for error
> checking — otherwise the field will be missing on responses.

> ℹ️ `set_security(True)` requires Business+ and `set_rate(True)` requires
> Basic+. See the table above for what's available where.

## HTTPS encryption

By default, all requests are sent over HTTPS. If you need to disable it (for
example, in environments without an up-to-date CA bundle), pass `ssl=False`
to the constructor:

```python
from ipwhois import IPWhois

# Free plan
ipwhois = IPWhois(ssl=False)
```

```python
from ipwhois import IPWhois

# Paid plan
ipwhois = IPWhois("YOUR_API_KEY", ssl=False)
```

> ℹ️ HTTPS is strongly recommended for production traffic — your API key is
> sent in the query string and would otherwise travel in clear text.

## Bulk lookup (Paid plan only)

The bulk endpoint sends **up to 100 IPs** in a single GET request. Each
address counts as one credit. Available on the **Business** and **Unlimited**
plans.

```python
from ipwhois import IPWhois

ipwhois = IPWhois("YOUR_API_KEY")

results = ipwhois.bulk_lookup([
    "8.8.8.8",
    "1.1.1.1",
    "208.67.222.222",
    "2c0f:fb50:4003::",     # IPv6 is fine — mix freely
])

for row in results:
    if row.get("success") is False:
        # Per-IP errors (e.g. "Invalid IP address") are returned inline,
        # they do NOT raise — the rest of the batch is still usable.
        print(f"skip {row['ip']}: {row['message']}")
        continue
    print(f"{row['ip']} → {row['country']}")
```

> ℹ️ Bulk requires an API key. Calling `bulk_lookup()` without one will fail
> at the API level.

## Error handling

**The library never raises.** Every failure — invalid IP, bad API key, rate
limit, network outage, bad options — comes back inside the response dict
with `success` set to `False` and a `message`. Just check
`info["success"]` after every call:

```python
info = ipwhois.lookup("8.8.8.8")

if not info["success"]:
    print(f"Lookup failed: {info['message']}")
    return

print(info["country"])
```

This means an outage of the ipwhois.io API (or of your machine's DNS,
connection, etc.) will never surface as an unhandled exception in your
application — you decide how to react.

### Error response fields

Every error response contains `success: False`, a human-readable `message`,
and an `error_type` so you can branch on the category of the failure. Some
errors include extra fields you can branch on:

| Field          | When it's present                                                                            |
| -------------- | -------------------------------------------------------------------------------------------- |
| `success`      | Always — False for error responses (True for successful responses)                           |
| `message`      | Always — human-readable description of what went wrong                                       |
| `error_type`   | Always — one of `'api'`, `'network'`, or `'invalid_argument'`                                |
| `http_status`  | On HTTP 4xx / 5xx responses                                                                  |
| `retry_after`  | On HTTP 429 — **free plan only** (the paid endpoint does not send a `Retry-After` header)    |

```python
import time

info = ipwhois.lookup("8.8.8.8")

if not info["success"]:
    if info.get("http_status") == 429:
        time.sleep(info.get("retry_after", 60))
        # ...retry

if info.get("error_type") == "network":
        # DNS failure, connection refused, timeout, ...
        pass

print(f"Error: {info['message']}")
```

## Response shape

A successful response includes (depending on your plan and selected options):

```jsonc
{
    "ip": "8.8.4.4",
    "success": true,
    "type": "IPv4",
    "continent": "North America",
    "continent_code": "NA",
    "country": "United States",
    "country_code": "US",
    "region": "California",
    "region_code": "CA",
    "city": "Mountain View",
    "latitude": 37.3860517,
    "longitude": -122.0838511,
    "is_eu": false,
    "postal": "94039",
    "calling_code": "1",
    "capital": "Washington D.C.",
    "borders": "CA,MX",
    "flag": {
        "img": "https://cdn.ipwhois.io/flags/us.svg",
        "emoji": "🇺🇸",
        "emoji_unicode": "U+1F1FA U+1F1F8"
    },
    "connection": {
        "asn": 15169,
        "org": "Google LLC",
        "isp": "Google LLC",
        "domain": "google.com"
    },
    "timezone": {
        "id": "America/Los_Angeles",
        "abbr": "PDT",
        "is_dst": true,
        "offset": -25200,
        "utc": "-07:00",
        "current_time": "2026-05-08T14:31:48-07:00"
    },
    "currency": {
        "name": "US Dollar",
        "code": "USD",
        "symbol": "$",
        "plural": "US dollars",
        "exchange_rate": 1
    },
    "security": {
        "anonymous": false,
        "proxy": false,
        "vpn": false,
        "tor": false,
        "hosting": false
    },
    "rate": {
        "limit": 250000,
        "remaining": 50155
    }
}
```

For the full field reference, see the [official documentation](https://ipwhois.io/documentation).

An **error** response looks like:

```jsonc
{
    "success": false,
    "message": "Rate limit exceeded",
    "error_type": "api",       // 'api' / 'network' / 'invalid_argument'
    "http_status": 429,         // present for HTTP 4xx / 5xx
    "retry_after": 60       // additionally present on HTTP 429 — free plan only
}
```

## Requirements

- Python **3.8** or newer
- No third-party dependencies — only the standard library (`urllib`, `json`)

## Contributing

Issues and pull requests are welcome on
[GitHub](https://github.com/IPWhois/ipwhois-python).

## License

ipwhois-python

Owner Repos

File Explorer

# Use via CDN

# Project Badges

Was this content helpful?

Recent Feedback

ipwhois-python

Owner Repos

File Explorer

# Use via CDN

# Project Badges

Was this content helpful?

Recent Feedback

Download README