ApogeoAPI quickstart — Node.js (axios)

Install

npm install axios

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
import axios from 'axios';

export const apogeo = axios.create({
  baseURL: 'https://api.apogeoapi.com/v1',
  headers: { 'X-API-Key': process.env.APOGEOAPI_KEY },
  timeout: 5000,
});

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 { data } = await apogeo.get('/countries/AR', {
  params: { include: 'full' },
});
console.log(data.name, data.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.

const { data: geo } = await apogeo.get('/ip/8.8.8.8');
console.log(geo.country, geo.countryCode, geo.timezone);

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 { data: fx } = await apogeo.get('/exchange-rates/USD', {
  params: { targets: 'EUR,ARS,BRL' },
});
console.log(fx.rates);

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 } = await apogeo.get('/countries/BR/states', {
  params: { limit: 50 },
});
data.data.forEach(s => console.log(s.iso3166_2, 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.

import axiosRetry from 'axios-retry';

axiosRetry(apogeo, {
  retries: 3,
  retryDelay: (count, err) => {
    const wait = Number(err.response?.headers['retry-after']) || count * 2;
    return wait * 1000;
  },
  retryCondition: (err) => err.response?.status === 429,
});