ApogeoAPI quickstart — Ruby (Faraday)

Install

gem install faraday

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.

require 'faraday'
require 'json'

APOGEO = Faraday.new(
  url: 'https://api.apogeoapi.com/v1',
  headers: { 'X-API-Key' => ENV.fetch('APOGEOAPI_KEY') },
) do |f|
  f.options.timeout = 5
  f.options.open_timeout = 2
end

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', { include: 'full' })
country = JSON.parse(res.body)
puts "#{country['name']} — #{country['capital']}"
puts "1 USD = #{country['currencyRate']['rate']} #{country['currency']}"

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.parse(APOGEO.get('ip/8.8.8.8').body)
puts "#{geo['country']} · #{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.

fx = JSON.parse(
  APOGEO.get('exchange-rates/USD', { targets: 'EUR,ARS,BRL' }).body
)
fx['rates'].each { |code, rate| puts "1 USD = #{rate} #{code}" }

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.parse(
  APOGEO.get('countries/BR/states', { limit: 50 }).body
)['data']

states.each { |s| puts "#{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.

def apogeo_get(path, params = {}, attempts: 3)
  attempts.times do |i|
    res = APOGEO.get(path, params)
    return JSON.parse(res.body) if res.success?
    if res.status == 429
      sleep((res.headers['retry-after'] || (2**i)).to_i)
      next
    end
    raise "API error: #{res.status}"
  end
  raise "max retries exceeded"
end