ApogeoAPI quickstart — cURL

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
curl -H "X-API-Key: YOUR_KEY" https://api.apogeoapi.com/v1/health

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.

curl -H "X-API-Key: YOUR_KEY" \
  "https://api.apogeoapi.com/v1/countries/AR?include=full"

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.

curl -H "X-API-Key: YOUR_KEY" \
  "https://api.apogeoapi.com/v1/ip/8.8.8.8"

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.

curl -H "X-API-Key: YOUR_KEY" \
  "https://api.apogeoapi.com/v1/exchange-rates/USD?targets=EUR,ARS,BRL"

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.

curl -H "X-API-Key: YOUR_KEY" \
  "https://api.apogeoapi.com/v1/countries/AR/states?limit=30"

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.

# Check HTTP status code
curl -s -o /dev/null -w "%{http_code}\n" \
  -H "X-API-Key: YOUR_KEY" \
  https://api.apogeoapi.com/v1/countries/XX
# 404 — country not found
# 401 — invalid API key
# 429 — rate limited (Retry-After header tells you when)