Official Python client for ApogeoAPI. IP geolocation, countries, cities, states, and exchange rates. Zero dependencies.
pip install apogeoapiRequires Python ≥ 3.9. No third-party dependencies.
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")| 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 |
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}")Sign up at apogeoapi.com. Free plan: 1,000 requests/month with a 14-day full-access trial on signup.
MIT