ApogeoAPI quickstart — PHP (Guzzle)

Install

composer require guzzlehttp/guzzle

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.

<?php
use GuzzleHttp\Client;

$apogeo = new Client([
    'base_uri' => 'https://api.apogeoapi.com/v1/',
    'headers'  => ['X-API-Key' => getenv('APOGEOAPI_KEY')],
    'timeout'  => 5,
]);

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.

$res = $apogeo->get('countries/AR', [
    'query' => ['include' => 'full'],
]);
$country = json_decode($res->getBody(), true);
echo $country['name'] . ' — ' . $country['capital'];

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 = json_decode(
    $apogeo->get('ip/' . $_SERVER['REMOTE_ADDR'])->getBody(),
    true,
);
echo $geo['country'] . ' (' . $geo['countryCode'] . ')';

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 = json_decode(
    $apogeo->get('exchange-rates/USD', [
        'query' => ['targets' => 'EUR,ARS,BRL'],
    ])->getBody(),
    true,
);
echo '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 = json_decode(
    $apogeo->get('countries/BR/states', ['query' => ['limit' => 50]])->getBody(),
    true,
)['data'];

foreach ($states as $st) {
    echo $st['iso3166_2'] . ' — ' . $st['name'] . PHP_EOL;
}

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.

use GuzzleHttp\Exception\ClientException;
use GuzzleHttp\Exception\ServerException;

try {
    $res = $apogeo->get('countries/XX');
} catch (ClientException $e) {
    $code = $e->getResponse()->getStatusCode();
    if ($code === 429) {
        $wait = $e->getResponse()->getHeaderLine('Retry-After') ?: 60;
        sleep((int) $wait);
    }
    // 404 / 401 — log and skip
} catch (ServerException $e) {
    // 5xx — retry later
}