ApogeoAPI quickstart — Python (requests)

Install

pip install requests

1. Authenticate

Every request needs an X-API-Key header. Get your key from the dashboard — free tier or 14-day trial, no credit card.

# Replace YOUR_KEY with the key from your dashboard
import os
import requests

API_KEY = os.environ.get("APOGEOAPI_KEY", "YOUR_KEY")
s = requests.Session()
s.headers.update({"X-API-Key": API_KEY})
BASE = "https://api.apogeoapi.com/v1"

2. Get country data

Returns ISO codes, capital, currency with live exchange rate, phone code, flag URL, timezones, name translations and more — for any of the 250 countries.

r = s.get(f"{BASE}/countries/AR", params={"include": "full"}, timeout=5)
r.raise_for_status()
country = r.json()
print(country["name"], country["capital"], country["currencyRate"]["rate"])

Full country list: browse all 250 →

3. IP geolocation

Pass any IPv4 or IPv6 address. Returns country, city, timezone, coordinates and accuracy radius. Use /ip/me server-side to detect the visitor.

geo = s.get(f"{BASE}/ip/8.8.8.8", timeout=5).json()
print(geo["country"], geo["timezone"], geo["isEU"])
# → United States America/Chicago False

Try it live without signup: /ip-lookup →

4. Live exchange rates

161 currencies, refreshed every 4 hours. Specify a base currency and any number of target codes.

fx = s.get(
    f"{BASE}/exchange-rates/USD",
    params={"targets": "EUR,ARS,BRL"},
    timeout=5,
).json()
print(f"1 USD = {fx['rates']['ARS']} ARS")

5. States & cities

List all states / provinces for a country (5,000+ globally). Each includes the ISO 3166-2 code and coordinates. Cities are accessible by state ID with /v1/states/:id/cities.

states = s.get(
    f"{BASE}/countries/AR/states",
    params={"limit": 30},
    timeout=5,
).json()["data"]
for st in states:
    print(st["stateCode"], st["name"])

6. Production-grade error handling

Always handle 429 (rate limit) — read the Retry-After header and back off. For transient 5xx, retry up to 3 times with exponential backoff.

from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

retry = Retry(
    total=3,
    backoff_factor=1,
    status_forcelist=[429, 500, 502, 503, 504],
    allowed_methods=["GET"],
    respect_retry_after_header=True,
)
s.mount("https://", HTTPAdapter(max_retries=retry))