IPWho Python SDK

The official Python SDK for the IPWho IP Geolocation API — get geolocation, timezone, connection and security information for IP addresses with full type safety and comprehensive data validation.

Installation

Install via pip:

pip install ipwho-ip-geolocation-api

Or with poetry:

poetry add ipwho-ip-geolocation-api

Quick Start

from ipwho import IPWho

client = IPWho(api_key='your-api-key')

# Get caller's location (uses your IP by default)
location = client.get_location()
print(location)

Example minimal response (normalized):

{
    'country': 'United States',
    'countryCode': 'US',
    'city': 'Ashburn',
    'latitude': 37.751,
    'longitude': -97.822
}

API Reference

All methods accept an optional ip parameter. When omitted, the SDK queries the caller’s IP (/me). When provided, it queries /ip/{ip}.

• get_location(ip: str | None = None): dict | None — Returns normalized geographical information.
• get_timezone(ip: str | None = None): dict | None — Returns timezone details, includes current_time when available.
• get_connection(ip: str | None = None): dict | None — ISP/ASN/org details.
• get_security(ip: str | None = None): dict | None — VPN/Tor/threat indicators.
• get_me(): dict — Raw API payload for the caller’s IP.
• get_ip(ip: str): dict — Raw API payload for a specific IP.

Requirements

Requires Python 3.8 or higher. See pyproject.toml for dependency specifications.

Type Definitions

The SDK includes full type hints for all methods and return types. Example summary:

from typing import Optional, TypedDict

class GeoLocation(TypedDict):
    continent: str
    country: str
    countryCode: str
    city: Optional[str]
    latitude: Optional[float]
    longitude: Optional[float]

Usage Examples

Basic usage (explicit IP):

location = client.get_location('76.102.11.203')
print(location.get('country'), location.get('city'))

Handling errors:

try:
    data = client.get_ip('invalid-ip')
    print(data)
except Exception as e:
    print(f'API or network error: {e}')

Getting full geolocation data:

full_data = client.get_ip('76.102.11.203')
print(full_data)
# Returns complete response with geolocation, timezone, currency, security, etc.

Troubleshooting & Errors

• Missing or invalid API key: Pass your API key to the IPWho constructor or set the IPWHO_API_KEY environment variable.
• API errors: The SDK raises exceptions when the API returns an error or the response is invalid.
• Network errors: Handle network timeouts and connection errors appropriately in your application.