ApogeoAPI quickstart — Java (HttpClient)

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.

// Java 11+
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

class Apogeo {
    static final String BASE = "https://api.apogeoapi.com/v1";
    static final String KEY = System.getenv("APOGEOAPI_KEY");
    static final HttpClient http = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(2))
        .build();

    static String get(String path) throws Exception {
        var req = HttpRequest.newBuilder()
            .uri(URI.create(BASE + path))
            .header("X-API-Key", KEY)
            .timeout(Duration.ofSeconds(5))
            .GET().build();
        var res = http.send(req, HttpResponse.BodyHandlers.ofString());
        if (res.statusCode() >= 400) throw new RuntimeException("API " + res.statusCode());
        return res.body();
    }
}

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.

// Parse with Jackson or Gson
String json = Apogeo.get("/countries/AR?include=full");
System.out.println(json);
// → {"iso2":"AR","name":"Argentina","capital":"Buenos Aires",...}

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.

String geo = Apogeo.get("/ip/8.8.8.8");
// Parse JSON, e.g. with Jackson:
// var node = new ObjectMapper().readTree(geo);
// System.out.println(node.get("country").asText());

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.

String fx = Apogeo.get("/exchange-rates/USD?targets=EUR,ARS,BRL");
// JSON: { "base":"USD","rates":{"EUR":0.91,"ARS":1395.34,...} }

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.

String states = Apogeo.get("/countries/AR/states?limit=30");
// JSON: { "data":[ {"stateCode":"C","name":"Buenos Aires",...} ] }

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.

static String getWithRetry(String path) throws Exception {
    for (int i = 0; i < 3; i++) {
        try { return get(path); }
        catch (RuntimeException e) {
            if (!e.getMessage().contains("429")) throw e;
            Thread.sleep(1000L * (1L << i));
        }
    }
    throw new RuntimeException("max retries");
}