ApogeoAPI quickstart — C# (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.

public sealed class ApogeoClient
{
    private readonly HttpClient _http;

    public ApogeoClient(HttpClient http, IConfiguration cfg)
    {
        _http = http;
        _http.BaseAddress = new Uri("https://api.apogeoapi.com/v1/");
        _http.DefaultRequestHeaders.Add("X-API-Key", cfg["Apogeo:Key"]);
        _http.Timeout = TimeSpan.FromSeconds(5);
    }

    public Task<T?> GetAsync<T>(string path) =>
        _http.GetFromJsonAsync<T>(path);
}

// Program.cs
builder.Services.AddHttpClient<ApogeoClient>();

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.

public record Country(string Iso2, string Name, string Capital, string Currency);

var ar = await apogeo.GetAsync<Country>("countries/AR?include=full");
Console.WriteLine($"{ar?.Name} — {ar?.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.

public record IpGeo(string Country, string CountryCode, string Timezone, double Latitude, double Longitude);

var geo = await apogeo.GetAsync<IpGeo>("ip/8.8.8.8");
Console.WriteLine($"{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.

public record FX(string Base, Dictionary<string, decimal> Rates);

var fx = await apogeo.GetAsync<FX>("exchange-rates/USD?targets=EUR,ARS,BRL");
foreach (var r in fx?.Rates ?? new())
    Console.WriteLine($"1 USD = {r.Value} {r.Key}");

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.

public record State(string Name, string StateCode, string Iso3166_2);
public record StateList(List<State> Data);

var list = await apogeo.GetAsync<StateList>("countries/BR/states?limit=50");
foreach (var s in list?.Data ?? new())
    Console.WriteLine($"{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.

// dotnet add package Microsoft.Extensions.Http.Polly
using Polly;
using Polly.Extensions.Http;

builder.Services.AddHttpClient<ApogeoClient>()
    .AddTransientHttpErrorPolicy(p => p.WaitAndRetryAsync(
        3, attempt => TimeSpan.FromSeconds(Math.Pow(2, attempt))));