Metadata-Version: 2.4
Name: myip-foo
Version: 1.0.0
Summary: Official Python client for myip.foo - free IP lookup API with geolocation
Project-URL: Homepage, https://myip.foo
Project-URL: Documentation, https://myip.foo/api-docs.html
Project-URL: Repository, https://github.com/virtualox/myip-packages
Project-URL: Issues, https://github.com/virtualox/myip-packages/issues
Author-email: "VirtualOx B.V." <hello@virtualox.io>
License: MIT
Keywords: dual-stack,geolocation,ip,ip-address,ipv4,ipv6,myip,vpn-detection
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.8
Provides-Extra: async
Requires-Dist: aiohttp>=3.8.0; extra == 'async'
Description-Content-Type: text/markdown

# myip-foo

Official Python client for [myip.foo](https://myip.foo) - a free, privacy-focused IP lookup API.

[![PyPI version](https://img.shields.io/pypi/v/myip-foo.svg)](https://pypi.org/project/myip-foo/)
[![Python versions](https://img.shields.io/pypi/pyversions/myip-foo.svg)](https://pypi.org/project/myip-foo/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Features

- Full type hints (PEP 561)
- Zero dependencies (async requires aiohttp)
- Dual-stack IPv4/IPv6 support
- Connection type detection
- No API key required

## Installation

```bash
pip install myip-foo

# With async support
pip install myip-foo[async]
```

## Quick Start

```python
from myip_foo import get_ip, get_ip_data, get_dual_stack

# Get plain IP
ip = get_ip()
print(ip)  # "203.0.113.42"

# Get full data with geolocation
data = get_ip_data()
print(data['ip'])                    # "203.0.113.42"
print(data['location']['city'])      # "Amsterdam"
print(data['location']['country'])   # "NL"
print(data['network']['isp'])        # "KPN B.V."
print(data['connectionType'])        # "residential"

# Get both IPv4 and IPv6
dual = get_dual_stack()
print(dual['ipv4'])  # "203.0.113.42"
print(dual['ipv6'])  # "2001:db8::1" or None
```

## API Reference

### Functions

#### `get_ip() -> str`
Returns your IP address as plain text.

#### `get_ip_data() -> IPData`
Returns full IP data including geolocation.

#### `get_dual_stack(timeout: int = 5) -> DualStackData`
Returns both IPv4 and IPv6 addresses.

#### `get_connection_type() -> ConnectionTypeData`
Detects if connection is residential, VPN, or datacenter.

#### `get_headers() -> dict[str, str]`
Returns all HTTP headers as seen by the server.

#### `get_user_agent() -> str`
Returns your user agent string.

### Async Functions

Install with `pip install myip-foo[async]` to use async versions:

```python
import asyncio
from myip_foo import get_ip_async, get_ip_data_async, get_dual_stack_async

async def main():
    ip = await get_ip_async()
    data = await get_ip_data_async()
    dual = await get_dual_stack_async()
    print(f"IP: {ip}, City: {data['location']['city']}")

asyncio.run(main())
```

### Types

```python
class IPData(TypedDict):
    ip: str
    type: str  # "IPv4" or "IPv6"
    hostname: Optional[str]
    connectionType: Optional[str]  # "residential", "vpn", "datacenter", "tor"
    location: Location
    network: Network
    cloudflare: Cloudflare

class DualStackData(TypedDict):
    ipv4: Optional[str]
    ipv6: Optional[str]

class ConnectionTypeData(TypedDict):
    ip: str
    type: str  # "residential", "vpn", "datacenter", "unknown"
```

## Dual-Stack Endpoints

The `get_dual_stack()` function uses dedicated subdomains:

- `ipv4.myip.foo/ip` - Returns IPv4 only (A record)
- `ipv6.myip.foo/ip` - Returns IPv6 only (AAAA record)

## Privacy

myip.foo does not log IP addresses or use cookies. See [Privacy Policy](https://myip.foo/privacy.html).

## Links

- **Website:** [myip.foo](https://myip.foo)
- **API Docs:** [myip.foo/api-docs](https://myip.foo/api-docs.html)
- **GitHub:** [myip-packages](https://github.com/virtualox/myip-packages)

## License

MIT License - see [LICENSE](../../LICENSE) for details.
