db-geoip 1.3.21

Lightweight, open‑source Python client designed to resolve IPv4 and IPv6 addresses into their corresponding country codes with minimal overhead. Built specifically for users of the db‑geoip geolocation service, the package provides a clean, predictable interface that abstracts away network handling, request formatting, and error management.

db‑geoip — Lightweight Country‑Level IP Resolver for Python

db‑geoip is a lightweight, open‑source Python client designed to resolve IPv4 and IPv6 addresses into their corresponding country codes with minimal overhead. Built specifically for users of the db‑geoip geolocation service, the package provides a clean, predictable interface that abstracts away network handling, request formatting, and error management. Instead of maintaining large local databases or integrating heavy geolocation libraries, developers can rely on a simple, efficient API call that returns accurate country‑level information in milliseconds. This makes db‑geoip ideal for applications where geolocation is needed but full city‑level or ASN‑level data would be unnecessary or too resource‑intensive.

---

✨ Why db‑geoip?

• Lightweight by design — no bundled datasets, no complex dependencies
• Open‑source and transparent — easy to audit, extend, or integrate
• Consistent API — one function, one purpose, predictable output
• Optimized for production — minimal latency, minimal memory footprint
• Built for the db‑geoip ecosystem — seamless integration with the hosted resolver

🔍 What It Does

The package sends a small, authenticated request to the db‑geoip resolver service and returns a structured response containing:

- ISO‑compliant country code
- Additional metadata provided by the service (if available)
- Clear error messages for invalid keys or unresolvable IPs

This makes it suitable for a wide range of real‑world scenarios where country‑level attribution is enough to drive logic or analytics.

🧭 Use Cases

• Security and access control (e.g., blocking or allowing traffic by region)
• Lightweight analytics and traffic segmentation
• Content localization and regional feature toggles
• Network utilities, monitoring tools, and diagnostic scripts
• Fraud detection heuristics based on country‑level signals

🎯 Who This Package Is For

This client is intended for developers who already use or plan to use the db‑geoip service and want a minimal, reliable way to integrate country‑level IP resolution into Python applications without unnecessary complexity.

🚀 Installation

Install the package from PyPI:

pip install db-geoip

Or add it to your project’s requirements.txt:

db-geoip>=1.0.0

🔧 Usage Example

from db_geoip import resolve_ip

result = resolve_ip("8.8.8.8", api_key="YOUR_API_KEY")
print(result["country_code"])  # e.g., "US"

📘 API Documentation

resolve_ip(ip_address: str, api_key: str) -> dict

Resolves an IPv4 or IPv6 address to its associated country information using the db‑geoip resolver service.

Parameters

Parameter	Type	Description
ip_address	str	The IPv4 or IPv6 address to resolve.
api_key	bool	Your db‑geoip API key. Required for authentication.

Returns

A Python dictionary containing structured geolocation data. Typical fields include:

{
    "ip": "8.8.8.8",
    "country_code": "US",
    "country_name": "United States"
}

Exceptions

Parameter	Description
Exception("Invalid API key")	The IPv4 or IPv6 address to resolve.
Exception("Unable to resolve geolocation for this IP")	The IP address cannot be resolved.
requests.exceptions.RequestException	Network or connection issues.
ValueError	Response is not valid JSON.

Behavior

• Sends a POST request to the db‑geoip resolver endpoint
• Validates response status codes
• Parses JSON into a Python dictionary
• Raises clear, predictable exceptions