Metadata-Version: 2.4
Name: apogeoapi
Version: 1.0.0
Summary: Official Python SDK for ApogeoAPI — IP geolocation, countries, cities, and exchange rates
Project-URL: Homepage, https://apogeoapi.com
Project-URL: Documentation, https://api.apogeoapi.com/api/docs
Project-URL: Repository, https://github.com/APOGEOAPI/apogeoapi-python
Project-URL: Bug Tracker, https://github.com/APOGEOAPI/apogeoapi-python/issues
Author-email: ApogeoAPI <support@apogeoapi.com>
License: MIT
Keywords: api,cities,countries,exchange-rates,geolocation,ip,sdk
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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 :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-mock; extra == 'dev'
Description-Content-Type: text/markdown

# apogeoapi — Python SDK

Official Python client for [ApogeoAPI](https://apogeoapi.com).
IP geolocation, countries, cities, states, and exchange rates. **Zero dependencies.**

[![PyPI version](https://img.shields.io/pypi/v/apogeoapi)](https://pypi.org/project/apogeoapi/)
[![Python versions](https://img.shields.io/pypi/pyversions/apogeoapi)](https://pypi.org/project/apogeoapi/)

## Installation

```bash
pip install apogeoapi
```

Requires Python ≥ 3.9. No third-party dependencies.

## Quick start

```python
from apogeoapi import ApogeoAPIClient

client = ApogeoAPIClient(api_key="your_key_here")

# Country info
country = client.get_country("DE")
print(country["name"]["common"])   # Germany
print(country["capital"])          # Berlin
print(country["currencies"])       # {"EUR": {...}}

# IP geolocation
geo = client.geolocate_ip("8.8.8.8")
print(geo["country"]["name"])      # United States
print(geo["city"])                 # Mountain View
print(geo["timezone"])             # America/Los_Angeles
print(geo["isp"])                  # Google LLC

# Exchange rate (relative to USD)
rate = client.get_currency_rate("EUR")
print(rate["usdRate"])             # e.g. 0.9214

# List all countries in a region
europe = client.list_countries(region="Europe")
print(len(europe))                 # 44

# States/provinces
states = client.get_states("BR")
print(states[0]["name"])           # Acre

# Cities
cities = client.get_cities("MX", state="Jalisco", limit=5)

# Full-text search
results = client.search_countries("united")
# → [United States, United Kingdom, United Arab Emirates, ...]

# Global search (countries + cities + currencies)
all_results = client.global_search("paris")
```

## API Reference

| Method | Description |
|--------|-------------|
| `list_countries(region, subregion, limit, offset, fields)` | List all countries |
| `get_country(code, fields)` | Country by ISO2 or ISO3 code |
| `search_countries(query, limit)` | Search countries by name |
| `get_states(country_code)` | States/provinces for a country |
| `get_cities(country_code, state, limit, offset)` | Cities, optionally filtered by state |
| `geolocate_ip(ip)` | Geolocate IPv4 or IPv6 |
| `get_currency_rate(currency_code)` | USD exchange rate for a currency |
| `list_exchange_rates()` | All 161 supported currencies |
| `global_search(query, limit)` | Search across all data types |

## Error handling

```python
from apogeoapi import (
    ApogeoAPIClient,
    ApogeoAPIError,
    ApogeoAPIAuthError,
    ApogeoAPIRateLimitError,
)

try:
    data = client.get_country("XX")
except ApogeoAPIAuthError:
    print("Invalid API key — get one at https://apogeoapi.com")
except ApogeoAPIRateLimitError:
    print("Rate limit hit — upgrade at https://apogeoapi.com/pricing")
except ApogeoAPIError as e:
    print(f"API error {e.status_code}: {e}")
```

## Get an API key

Sign up at [apogeoapi.com](https://apogeoapi.com). Free plan: 1,000 requests/month
with a **14-day full-access trial** on signup.

## License

MIT
