IPGeolocation.io Python SDK

Typed Python SDK for the IPGeolocation.io IP Geolocation API.

• Single lookup (/v3/ipgeo) and bulk lookup (/v3/ipgeo-bulk)
• Sync client built on requests and async client built on httpx
• Typed response models plus raw JSON/XML methods
• Python 3.10+

Table of Contents

• Install
• Quick Start
• Authentication
• Notes
• Plan Behavior
• Examples
• Request Options
• Response Metadata
• Errors
• Links
• Development

Install

pip install ipgeolocationio

PyPI package: ipgeolocationio Package page: https://pypi.org/project/ipgeolocationio/ Import: ipgeolocation

Quick Start

from ipgeolocation import (
    IpGeolocationClient,
    IpGeolocationClientConfig,
    LookupIpGeolocationRequest,
)

config = IpGeolocationClientConfig(api_key="YOUR_API_KEY")

with IpGeolocationClient(config) as client:
    response = client.lookup_ip_geolocation(
        LookupIpGeolocationRequest(ip="8.8.8.8")
    )

    print(response.data.ip)

    if response.data.location is not None:
        print(response.data.location.country_name)
        print(response.data.location.city)

    if response.data.time_zone is not None:
        print(response.data.time_zone.name)

Async

import asyncio

from ipgeolocation import (
    AsyncIpGeolocationClient,
    IpGeolocationClientConfig,
    LookupIpGeolocationRequest,
)


async def main() -> None:
    config = IpGeolocationClientConfig(api_key="YOUR_API_KEY")

    async with AsyncIpGeolocationClient(config) as client:
        response = await client.lookup_ip_geolocation(
            LookupIpGeolocationRequest(ip="8.8.8.8")
        )
        print(response.data.ip)

        if response.data.location is not None:
            print(response.data.location.country_name)


asyncio.run(main())

The async client exposes the same methods as coroutines. Use async with for cleanup, or call await client.aclose() manually.

Authentication

API key: API key authentication supports single lookups on all plans. Bulk lookup requires a paid plan.

config = IpGeolocationClientConfig(api_key="YOUR_API_KEY")

Client Config

Notes

• Typed methods require JSON. For XML output, use the _raw methods with output=ResponseFormat.XML.
• Optional modules need include. Fields like security, abuse, user_agent, hostname, geo_accuracy, and dma_code only appear in the response when you pass the matching include value. Without it, those fields will be None.
• fields and excludes only filter the response. They do not enable optional modules or unlock paid data.
• Domain lookup is paid only. Passing a domain as ip="google.com" works on paid plans. Free plans get a 401.
• The SDK does not retry. Timeouts, server errors, and rate limits raise exceptions directly. Implement your own retry logic if you need it.
• Do not reuse a closed client. After close(), aclose(), or leaving a with or async with block, further requests raise ValidationException.

Plan Behavior

Responses vary by plan.

Capabilities

Default Response Sections

Default single-lookup response:

Examples

The examples below assume you already have a configured client in scope. See Quick Start for setup.

Caller IP

Omit the ip parameter to look up the IP of the machine making the request:

response = client.lookup_ip_geolocation(LookupIpGeolocationRequest())
print(response.data.ip)  # your public IP

Domain Lookup (Paid)

When you look up a domain, the response includes the resolved IP and the original domain name:

response = client.lookup_ip_geolocation(
    LookupIpGeolocationRequest(ip="google.com")
)
print(response.data.ip)       # resolved IP address
print(response.data.domain)   # "google.com"

Security and Abuse

response = client.lookup_ip_geolocation(
    LookupIpGeolocationRequest(
        ip="9.9.9.9",
        include=["security", "abuse"],
    )
)

if response.data.security is not None:
    print(response.data.security.threat_score)

if response.data.abuse is not None and response.data.abuse.emails:
    print(response.data.abuse.emails[0])

User-Agent Parsing

To parse a visitor's user-agent string, pass include=["user_agent"] and send the visitor string in the request User-Agent header:

visitor_ua = (
    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_2) "
    "AppleWebKit/601.3.9 (KHTML, like Gecko) Version/9.0.2 Safari/601.3.9"
)

response = client.lookup_ip_geolocation(
    LookupIpGeolocationRequest(
        ip="115.240.90.163",
        include=["user_agent"],
        headers={"User-Agent": visitor_ua},
    )
)

if response.data.user_agent is not None:
    print(response.data.user_agent.name)
    print(response.data.user_agent.operating_system)

Note: The user_agent field on the request model is different. It overrides the outbound User-Agent header for the HTTP request itself and takes precedence over headers["User-Agent"]. If you set both, the API parses the user_agent value.

Filtered Response

Use fields to keep specific fields, or excludes to remove them:

response = client.lookup_ip_geolocation(
    LookupIpGeolocationRequest(
        ip="8.8.8.8",
        include=["security"],
        fields=["location.country_name", "security.threat_score", "security.is_vpn"],
        excludes=["currency"],
    )
)

if response.data.location is not None:
    print(response.data.location.country_name)

if response.data.security is not None:
    print(response.data.security.threat_score)
    print(response.data.security.is_vpn)

Raw XML

Typed methods only support JSON. For XML, use a raw method:

from ipgeolocation import ResponseFormat

response = client.lookup_ip_geolocation_raw(
    LookupIpGeolocationRequest(ip="8.8.8.8", output=ResponseFormat.XML)
)
print(response.data)  # raw XML string

Bulk Lookup (Paid)

Bulk lookup uses POST and accepts up to 50,000 IPs or domains. Each item in the response is either BulkLookupSuccess or BulkLookupError:

from ipgeolocation import (
    BulkLookupError,
    BulkLookupIpGeolocationRequest,
    BulkLookupSuccess,
)

response = client.bulk_lookup_ip_geolocation(
    BulkLookupIpGeolocationRequest(
        ips=["8.8.8.8", "invalid-ip", "1.1.1.1"],
        include=["security"],
    )
)

for result in response.data:
    if isinstance(result, BulkLookupSuccess):
        print(result.data.ip, result.data.security)  # 8.8.8.8 Security(...)
    elif isinstance(result, BulkLookupError):
        print(result.error.message)  # 'invalid-ip' is not a valid IP address.

Request Options

Single Lookup

Bulk Lookup

Bulk lookup accepts the same fields as single lookup, plus:

Set api_key in your client settings for bulk lookups. The SDK sets Content-Type: application/json for you.

include Values

Supported lang values: en, de, ru, ja, fr, cn, es, cs, it, ko, fa, pt, ar (Arabic)

Response Metadata

Every SDK method returns ApiResponse(data=..., metadata=...).

• Typed single lookup returns IpGeolocationResponse
• A typed bulk lookup returns one BulkLookupResult per input. If the API sends too few or too many results, the SDK raises SerializationException.
• Raw methods return the response body as a string

Header access helpers:

metadata.header_values("Header-Name")        # all values as a tuple
metadata.first_header_value("Header-Name")   # first value or None

JSON Serialization

Use to_json() or to_pretty_json() to print SDK objects as JSON. When you print your client settings, the SDK hides your API key.

from ipgeolocation import JsonOutputMode, to_pretty_json

# Compact mode (default): omits None fields
print(to_pretty_json(response.data))

# Full mode: includes None fields as null
print(to_pretty_json(response.data, mode=JsonOutputMode.FULL))

Errors

All exceptions inherit from IpGeolocationException. The SDK does not retry failed requests.

Before the request is sent:

• ValidationException for bad config, invalid request parameters, or calling a closed client

Transport problems:

• RequestTimeoutException for timeouts
• TransportException for connection or other HTTP-level failures

API errors (non-2xx responses):

All API exceptions have .status_code and .api_message attributes. If the error body is too large or the connection closes early, you still get the HTTP status. The SDK hides your API key in error messages, including errors for individual IPs in a typed bulk lookup.

Links

• PyPI package
• Python SDK documentation
• API documentation
• Authentication
• Response formats
• Credits and usage
• GitHub repository