apogeoapi 1.0.0

Official Python SDK for ApogeoAPI — IP geolocation, countries, cities, and exchange rates

apogeoapi — Python SDK

Official Python client for ApogeoAPI. IP geolocation, countries, cities, states, and exchange rates. Zero dependencies.

Installation

pip install apogeoapi

Requires Python ≥ 3.9. No third-party dependencies.

Quick start

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

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. Free plan: 1,000 requests/month with a 14-day full-access trial on signup.

License

MIT