Metadata-Version: 2.4
Name: db-geoip
Version: 1.3.21
Summary: 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.
Author: Ethan Cole
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Dynamic: license-file

# 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
