ApogeoAPI quickstart — JavaScript (fetch)

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 https://app.apogeoapi.com/dashboard/api-keys
const API_KEY = 'YOUR_KEY';
const BASE = 'https://api.apogeoapi.com/v1';

async function api(path) {
  const res = await fetch(BASE + path, {
    headers: { 'X-API-Key': API_KEY },
  });
  if (!res.ok) throw new Error('API ' + res.status);
  return res.json();
}

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.

const ar = await api('/countries/AR?include=full');
console.log(ar.name, ar.capital, ar.currencyRate?.rate);
// → "Argentina" "Buenos Aires" 1395.34

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.

const geo = await api('/ip/8.8.8.8');
console.log(geo.country, geo.timezone);
// → "United States" "America/Chicago"

// Detect the visitor's IP (server-side; in the browser you'd hit your backend):
// const visitor = await api('/ip/me');

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.

const fx = await api('/exchange-rates/USD?targets=EUR,ARS,BRL');
console.log(`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.

const { data: states } = await api('/countries/US/states?limit=60');
states.forEach(s => console.log(s.stateCode, s.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.

async function safeApi(path) {
  try {
    const res = await fetch(BASE + path, {
      headers: { 'X-API-Key': API_KEY },
    });
    if (res.status === 429) {
      const wait = Number(res.headers.get('Retry-After') || '60');
      await new Promise(r => setTimeout(r, wait * 1000));
      return safeApi(path); // single retry
    }
    if (!res.ok) return null;
    return await res.json();
  } catch {
    return null; // network error
  }
}