DEV Community: ApogeoAPI

Astro Middleware: Detect Visitor Country in 15 Lines (with ApogeoAPI)

ApogeoAPI — Mon, 04 May 2026 19:48:35 +0000

Astro 4 ships with a middleware API that runs server-side before the page renders. Combined with ApogeoAPI, you can detect the visitor's country and pass it down to every page as a typed prop — no client-side flicker.

Setup

Astro middleware lives at src/middleware.ts. Astro automatically picks it up. Make sure your project is using output: 'server' or output: 'hybrid' in astro.config.mjs (static-only sites can't run middleware).

// astro.config.mjs
import { defineConfig } from 'astro/config';
export default defineConfig({
output: 'hybrid',
adapter: /* your adapter — vercel, cloudflare, node, etc. */,
});

The middleware

// src/middleware.ts
import { defineMiddleware } from 'astro:middleware';
export const onRequest = defineMiddleware(async (ctx, next) => {
const ip =
ctx.request.headers.get('x-forwarded-for')?.split(',')[0] ??
ctx.request.headers.get('cf-connecting-ip') ??
ctx.clientAddress;
if (ip) {
try {
const res = await fetch(`https://api.apogeoapi.com/v1/api/geo/ip/${ip}`, {
headers: { 'X-API-Key': import.meta.env.APOGEOAPI_KEY },
});
if (res.ok) {
const data = await res.json();
ctx.locals.geo = {
country: data.country?.iso2,
countryName: data.country?.name,
city: data.city?.name,
currency: data.country?.currency,
currencyRate: data.country?.currencyRate,
};
}
} catch {
// fail silently; pages will fall back to defaults
}
}
return next();
});

Type the locals

Astro's ctx.locals is untyped by default. Add this to src/env.d.ts for autocomplete and type-checking:

/// 
declare namespace App {
interface Locals {
geo?: {
country?: string;
countryName?: string;
city?: string;
currency?: string;
currencyRate?: number;
};
}
}

Use it in any page

---
// src/pages/index.astro
const { geo } = Astro.locals;
const greeting = geo?.country === 'AR' ? '¡Hola!' : 'Hello';
---
{greeting} from {geo?.countryName ?? 'somewhere'} 👋
{geo?.currency && geo.currency !== 'USD' && (

Your currency: {geo.currency} — 1 USD = {geo.currencyRate?.toFixed(2)}

)}

Adding edge caching

Without caching, every page render hits ApogeoAPI. To keep API quota low, add a 1-hour cache keyed by IP. On Vercel/Cloudflare adapters this is automatic with fetch's next: { revalidate } option (Vercel) or cf: { cacheTtl } (Cloudflare):

const res = await fetch(`https://api.apogeoapi.com/v1/api/geo/ip/${ip}`, {
headers: { 'X-API-Key': import.meta.env.APOGEOAPI_KEY },
// Vercel adapter:
// @ts-expect-error — Astro fetch doesn't yet type 'next' option
next: { revalidate: 3600 },
});

For self-hosted Node, wrap in a small in-memory LRU cache (~10 lines, no library needed).

Production gotchas

Static prerendered pages. Middleware doesn't run for routes you've explicitly marked export const prerender = true. Either keep those pages static (no geo personalization) or remove the prerender flag.
Localhost. ctx.clientAddress can be ::1 in dev. Hardcode an IP behind import.meta.env.DEV for testing.
Rate limits. ApogeoAPI free tier is 1,000 req/month — with 1h cache, that covers ~5,000 unique visitors per month before you'd need to upgrade.

Free key at apogeoapi.com. Postman collection with all endpoints at /postman.

Originally published at https://apogeoapi.com/blog/astro-detect-country. Try ApogeoAPI free at apogeoapi.com.

Country Dropdown for Tailwind / shadcn — Drop-In Component

ApogeoAPI — Mon, 04 May 2026 19:47:49 +0000

Country dropdowns sound easy until you build one. Then you realize you need: searchable list, flag images that don't tank your bundle, keyboard navigation, ARIA, and a way to hydrate the data without re-fetching on every component mount.

This is a drop-in component for Tailwind / shadcn projects. ~80 lines, no extra dependencies, works with any state management.

Component code

Save as components/CountryDropdown.tsx:

'use client';
import { useEffect, useMemo, useRef, useState } from 'react';
interface Country {
iso2: string;
name: string;
flagUrl: string;
}
interface Props {
countries: Country[];
value?: string;
onChange: (iso2: string) => void;
placeholder?: string;
}
export function CountryDropdown({ countries, value, onChange, placeholder = 'Select a country…' }: Props) {
const [open, setOpen] = useState(false);
const [query, setQuery] = useState('');
const ref = useRef(null);
const selected = countries.find((c) => c.iso2 === value);
const filtered = useMemo(() => {
const q = query.trim().toLowerCase();
if (!q) return countries;
return countries.filter(
(c) => c.name.toLowerCase().includes(q) || c.iso2.toLowerCase().startsWith(q)
);
}, [query, countries]);
useEffect(() => {
function onClickOutside(e: MouseEvent) {
if (ref.current && !ref.current.contains(e.target as Node)) setOpen(false);
}
document.addEventListener('mousedown', onClickOutside);
return () => document.removeEventListener('mousedown', onClickOutside);
}, []);
return (

 setOpen((o) => !o)}
aria-haspopup="listbox"
aria-expanded={open}
className="flex w-full items-center justify-between rounded-md border border-slate-700 bg-slate-900 px-3 py-2 text-sm text-slate-100 hover:border-slate-500 focus:outline-none focus:ring-2 focus:ring-blue-500"
>
{selected ? (

{selected.name}

) : (
{placeholder}
)}
▾

{open && (

 setQuery(e.target.value)}
placeholder="Search…"
className="sticky top-0 w-full border-b border-slate-700 bg-slate-950 px-3 py-2 text-sm text-slate-100 focus:outline-none"
/>
{filtered.length === 0 ? (
No matches.
) : (
filtered.map((c) => (
 {
onChange(c.iso2);
setOpen(false);
setQuery('');
}}
className="flex w-full items-center gap-2 px-3 py-2 text-left text-sm text-slate-200 hover:bg-slate-800"
>

{c.name}
{c.iso2}

))
)}

)}

);
}

Hydrating the country list (Server Component)

You don't want to fetch 250 countries on every component mount. Fetch once at the page level (Server Component) and pass to the client component as a prop:

import { CountryDropdown } from '@/components/CountryDropdown';
async function getCountries() {
const res = await fetch('https://api.apogeoapi.com/v1/countries', {
headers: { 'X-API-Key': process.env.APOGEOAPI_KEY! },
next: { revalidate: 86400 }, // country list rarely changes — 24h cache is fine
});
return res.json();
}
export default async function SignupPage() {
const countries = await getCountries();
return (

Country
 console.log(iso2)}
/>

);
}

The revalidate: 86400 tells Next.js to cache this fetch for 24 hours per origin. Country data doesn't change daily, so this is safe and saves your API quota.

Combining with auto-detection

To pre-select the visitor's country based on their IP:

import { headers } from 'next/headers';
async function detectCountry(): Promise {
const ip = headers().get('x-forwarded-for')?.split(',')[0];
if (!ip) return undefined;
const res = await fetch(`https://api.apogeoapi.com/v1/ip/${ip}`, {
headers: { 'X-API-Key': process.env.APOGEOAPI_KEY! },
next: { revalidate: 3600 },
});
if (!res.ok) return undefined;
const { country } = await res.json();
return country.iso2;
}

Then pass value={await detectCountry()} to the component. The dropdown opens with the visitor's country pre-selected — the most-frequent reason for needing this widget at all.

Accessibility checklist

✓ aria-haspopup and aria-expanded on trigger
✓ role="listbox" on the dropdown panel
✓ role="option" and aria-selected on each item
✓ Keyboard: focus moves to search input on open (autoFocus)
✗ Arrow-key navigation between items — add if your spec requires it (most don't)

Bundle impact

Component itself: ~2KB minified+gzipped. Flag images load lazily from flagcdn.com via the flagUrl field — no bundling, no build-time conversion, no PNG sprite. ApogeoAPI returns the flag URL inline so you don't need a separate flag CDN config.

Free API key at apogeoapi.com.

Originally published at https://apogeoapi.com/blog/tailwind-country-dropdown. Try ApogeoAPI free at apogeoapi.com.

Building a City Autocomplete with 150K Cities — Tutorial

ApogeoAPI — Mon, 04 May 2026 19:41:43 +0000

City autocomplete sounds simple until you realize you need to search across 150,000 cities from 250 countries — with fast response times and no UI jank. Here's how to do it right.

The Challenge

You can't load 150K cities into the browser — that's tens of megabytes. You need server-side search that returns relevant results as the user types. ApogeoAPI's global search endpoint handles this.

The API Approach

Use the global search endpoint for cross-country city search:

GET /v1/search?q=lon&limit=5
// Returns cities, states, and countries matching "lon"
// Results: London GB, Long Beach US, Longueuil CA, ...

Step 1: Build the Search Hook with Debounce

// hooks/useCitySearch.ts
import { useState, useEffect } from 'react';
function useDebounce(value: T, ms: number): T {
const [debounced, setDebounced] = useState(value);
useEffect(() => {
const timer = setTimeout(() => setDebounced(value), ms);
return () => clearTimeout(timer);
}, [value, ms]);
return debounced;
}
interface CityResult {
name: string;
stateCode: string;
stateName: string;
countryCode: string;
countryName: string;
latitude: number;
longitude: number;
}
export function useCitySearch(query: string) {
const [results, setResults] = useState([]);
const [loading, setLoading] = useState(false);
const debouncedQuery = useDebounce(query, 300);
useEffect(() => {
if (debouncedQuery.length  r.json())
.then(data => setResults(data.cities ?? []))
.finally(() => setLoading(false));
}, [debouncedQuery]);
return { results, loading };
}

Step 2: The Autocomplete Component

'use client';
import { useState } from 'react';
import { useCitySearch } from '@/hooks/useCitySearch';
interface Props {
onSelect: (city: { name: string; country: string; lat: number; lon: number }) => void;
}
export function CityAutocomplete({ onSelect }: Props) {
const [query, setQuery] = useState('');
const { results, loading } = useCitySearch(query);
return (

 setQuery(e.target.value)}
placeholder="Search city..."
className="w-full border rounded px-3 py-2"
/>
{loading && (
...
)}
{results.length > 0 && (

{results.map(city => (
 {
onSelect({ name: city.name, country: city.countryCode,
lat: city.latitude, lon: city.longitude });
setQuery(`${city.name}, ${city.stateName}, ${city.countryCode}`);
// close dropdown implicitly by clearing results
}}
className="px-4 py-2.5 hover:bg-gray-50 cursor-pointer"
>
{city.name}

{city.stateName}, {city.countryCode}

))}

)}

);
}

Performance Notes

Debounce 300ms: Prevents a request on every keystroke.
Minimum 2 characters: Avoids overly broad results on single letters.
Limit to 8 results: Users don't scroll through more than that in a dropdown.
Cache recent searches: Store the last 10 queries in a useRef Map to avoid re-fetching the same query.

Originally published at https://apogeoapi.com/blog/city-autocomplete-api. Try ApogeoAPI free at apogeoapi.com.

Timezone API by Country — Full Guide 2026

ApogeoAPI — Mon, 04 May 2026 19:40:57 +0000

Timezone data is one of those things developers underestimate until they get a bug report at 2am from a user in a different country. Here's how to handle it properly.

Why Timezone Data Matters

Scheduling features (meeting bookings, reminders, cron jobs)
Displaying "last updated at" timestamps in the user's local time
Date pickers that need to know if a date is in the past for a given region
Calculating business hours across multiple locations

Getting Timezone from a Country Code

ApogeoAPI returns a timezones array in every country response:

const res = await fetch('https://api.apogeoapi.com/v1/countries/US', {
headers: { 'X-API-Key': 'your_key' }
});
const country = await res.json();
console.log(country.timezones);
// ['America/New_York', 'America/Chicago', 'America/Denver',
//  'America/Los_Angeles', 'America/Anchorage', 'Pacific/Honolulu']

Getting Timezone from IP (More Accurate)

For individual user sessions, IP geolocation gives you a single specific timezone — more accurate than a country-level list:

const res = await fetch('https://api.apogeoapi.com/v1/geolocate/USER_IP', {
headers: { 'X-API-Key': 'your_key' }
});
const geo = await res.json();
console.log(geo.timezone); // 'America/Los_Angeles'

Countries with Multiple Timezones

The US has 6, Russia has 11, and Australia has 5. When your app needs to display times for a country rather than a specific user, you'll need to handle the array:

function formatTimeInCountry(date: Date, country: { timezones: string[] }) {
// Use the first timezone as the "primary" one
// Or let the user pick from the list
const tz = country.timezones[0];
return new Intl.DateTimeFormat('en-US', {
timeZone: tz,
dateStyle: 'medium',
timeStyle: 'short',
}).format(date);
}

Converting to User's Timezone in JavaScript

Once you have an IANA timezone string from the API, Intl.DateTimeFormat does the heavy lifting — no libraries needed:

const userTimezone = 'Europe/Berlin'; // from IP geo or country data
const formatter = new Intl.DateTimeFormat('en-US', {
timeZone: userTimezone,
year: 'numeric',
month: 'long',
day: 'numeric',
hour: '2-digit',
minute: '2-digit',
});
console.log(formatter.format(new Date())); // "April 1, 2026, 10:30 AM"

Caching Strategy

Timezone data changes very rarely (maybe once a year when a country updates DST rules). Cache aggressively:

Country timezones: cache for 24 hours minimum, 7 days is fine
IP-based timezone: cache per IP for 1 hour (users travel, IPs change)
Store in Redis or localStorage depending on whether it's server-side or client-side

Originally published at https://apogeoapi.com/blog/timezone-api-by-country. Try ApogeoAPI free at apogeoapi.com.

Webhooks for Country Data Changes — Get Notified When ISO Codes Update

ApogeoAPI — Mon, 04 May 2026 19:34:23 +0000

Most apps using country / state / city data cache it locally for performance. The downside: when a country splits, an ISO code changes, or a state gets renamed, your cache goes stale until the next manual refresh.

ApogeoAPI's webhook system pushes those events to your endpoint as soon as the underlying data changes. This tutorial covers the full setup with HMAC signature verification.

Available events

Event	Fired when
country.created	A new country is added to the database (rare — average ~1/year)
country.updated	Any field on a country changes (capital, currency, name, region)
country.deleted	A country is removed (extremely rare)
state.updated	A state/province record changes
currency_rate.updated	Live FX refresh — fires every 4 hours per currency

Register the webhook

From your dashboard at app.apogeoapi.com → Webhooks → Add endpoint. Paste your URL, choose which events to subscribe to, and copy the secret. Or via API:

curl -X POST https://api.apogeoapi.com/v1/webhooks \
-H "X-API-Key: $APOGEOAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-app.com/webhooks/apogeoapi",
"events": ["country.updated", "state.updated"],
"active": true
}'

Response includes a secret field — save it; you'll need it to verify signatures.

Receive + verify in Node.js / Express

import express from 'express';
import crypto from 'node:crypto';
const app = express();
const SECRET = process.env.APOGEO_WEBHOOK_SECRET!;
// IMPORTANT: webhook handlers need the RAW body to verify the HMAC.
// Use express.raw() instead of express.json().
app.post(
'/webhooks/apogeoapi',
express.raw({ type: 'application/json' }),
(req, res) => {
const signature = req.header('X-ApogeoAPI-Signature');
if (!signature) return res.status(400).send('missing signature');
const expected = crypto
.createHmac('sha256', SECRET)
.update(req.body)
.digest('hex');
if (
!crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expected)
)
) {
return res.status(401).send('invalid signature');
}
const event = JSON.parse(req.body.toString('utf8'));
handleEvent(event);
res.status(204).end();
}
);
interface Event {
id: string;
event: string;
data: Record;
occurredAt: string;
}
function handleEvent(event: Event) {
switch (event.event) {
case 'country.updated':
console.log('Country changed:', event.data);
// invalidateCache(event.data.iso2)
break;
case 'currency_rate.updated':
// updateLocalRate(event.data.currency, event.data.usdRate)
break;
}
}

Payload examples

country.updated

{
"id": "evt_2026_03_27_abc123",
"event": "country.updated",
"data": {
"iso2": "TR",
"name": "Türkiye",
"previousName": "Turkey",
"changedFields": ["name", "translations"]
},
"occurredAt": "2026-03-27T14:32:11Z"
}

currency_rate.updated

{
"id": "evt_2026_03_27_def456",
"event": "currency_rate.updated",
"data": {
"currency": "ARS",
"usdRate": 1480.5,
"previousUsdRate": 1450.2,
"lastUpdated": "2026-03-27T14:00:00Z"
},
"occurredAt": "2026-03-27T14:00:03Z"
}

Retry behavior

If your endpoint returns non-2xx, ApogeoAPI retries with exponential backoff: 1 min, 5 min, 30 min, 2h, 8h. After 5 failed attempts, the webhook is marked inactive and an email is sent to your account address.

To handle retries idempotently, key your local processing on the id field. ApogeoAPI guarantees the same id for retries of the same event.

Testing locally

Use ngrok or Cloudflare Tunnel to expose your localhost endpoint, register that URL as the webhook target, and trigger test events from the dashboard's "Send test event" button.

What we don't deliver via webhooks

City updates. 150K cities = too much churn for webhooks. Use cities/{id} with If-Modified-Since instead.
API key events. These are account-level, not data-level. Different webhook type (planned).
IP geolocation events. No "fired when an IP changes country" semantic exists. Just re-call the endpoint.

Webhooks are a paid-tier feature on ApogeoAPI (Basic and above). Free tier customers should poll endpoints with conservative TTLs instead. Get started at apogeoapi.com — 14-day full trial includes webhooks.

Originally published at https://apogeoapi.com/blog/webhook-country-data-changes. Try ApogeoAPI free at apogeoapi.com.

SvelteKit Localized Pricing with ApogeoAPI in 30 Lines (Server Hooks)

ApogeoAPI — Mon, 04 May 2026 19:33:36 +0000

SvelteKit's server hooks run on every request before the page is rendered. Combined with ApogeoAPI, you can detect the visitor's country and look up the live exchange rate, then pass everything down to every +page.svelte as typed locals.

The hook

// src/hooks.server.ts
import type { Handle } from '@sveltejs/kit';
import { APOGEOAPI_KEY } from '$env/static/private';
const APOGEO = 'https://api.apogeoapi.com/v1/api/geo';
export const handle: Handle = async ({ event, resolve }) => {
const ip =
event.request.headers.get('x-forwarded-for')?.split(',')[0] ??
event.getClientAddress();
if (ip && APOGEOAPI_KEY) {
try {
const res = await fetch(`${APOGEO}/ip/${ip}`, {
headers: { 'X-API-Key': APOGEOAPI_KEY },
});
if (res.ok) {
const data = await res.json();
event.locals.geo = {
country: data.country?.iso2,
currency: data.country?.currency,
rate: data.country?.currencyRate, // USD → local
};
}
} catch {
// fail-open
}
}
return resolve(event);
};

Type the locals

// src/app.d.ts
declare global {
namespace App {
interface Locals {
geo?: {
country?: string;
currency?: string;
rate?: number;
};
}
}
}
export {};

Use in a +page.server.ts

// src/routes/pricing/+page.server.ts
import type { PageServerLoad } from './$types';
const PLANS = [
{ name: 'Basic', usd: 19 },
{ name: 'Starter', usd: 29 },
{ name: 'Professional', usd: 79 },
];
export const load: PageServerLoad = async ({ locals }) => {
const { currency, rate } = locals.geo ?? {};
const plans = PLANS.map((p) => ({
...p,
localPrice:
currency && rate && currency !== 'USD'
? new Intl.NumberFormat(undefined, {
style: 'currency',
currency,
maximumFractionDigits: 0,
}).format(p.usd * rate)
: null,
}));
return { plans, currency };
};

Render in +page.svelte


import type { PageData } from './$types';
export let data: PageData;

- **{plan.name}**: ${plan.usd} USD {#if plan.localPrice} ≈ {plan.localPrice} {/if}

Caching the FX lookup

The hook above hits ApogeoAPI once per request — great for testing, expensive at scale. Use SvelteKit's fetch caching options:

const res = await event.fetch(`${APOGEO}/ip/${ip}`, {
headers: { 'X-API-Key': APOGEOAPI_KEY },
// SvelteKit-specific: cache by URL for 1h on the server
cache: 'force-cache',
});

For more granular control (e.g. invalidate hourly), wrap the call in a small in-memory Map with TTL. ~15 lines and you're done.

Common pitfalls

Static adapter. If you're using @sveltejs/adapter-static, hooks don't run — the site is fully prerendered. Switch to adapter-vercel, adapter-cloudflare, or adapter-node if you need geo personalization.
Localhost dev. event.getClientAddress() returns 127.0.0.1 which ApogeoAPI rejects. Hardcode a real IP behind dev guard for local testing.
Server-only env. $env/static/private only works in server contexts (+page.server.ts, +layout.server.ts, hooks, endpoints). Never reference APOGEOAPI_KEY in +page.svelte — that exposes it to the browser.

Free API key + 1,000 calls/month at apogeoapi.com.

Originally published at https://apogeoapi.com/blog/sveltekit-localized-pricing. Try ApogeoAPI free at apogeoapi.com.

Shopify Currency Widget with Live Exchange Rates (No App Required)

ApogeoAPI — Mon, 04 May 2026 19:27:28 +0000

Shopify's app store has dozens of "currency converter" apps — most cost $5-30/month and lock you into the vendor's theme. If your store doesn't have huge volume, the math doesn't work.

This is the no-app version: ~50 lines of JavaScript pasted into your theme's theme.liquid, using ApogeoAPI for the live exchange rates. Works on any Shopify plan including Lite, costs $0 for stores under ~5K daily visitors.

How it works

JavaScript runs on every page load.
Fetches the visitor's country (cached at edge).
Fetches the live USD->X exchange rate.
Finds all elements marked with data-shopify-price and overlays the converted amount.
Original price (in shop currency) stays in the DOM but is visually replaced. Cart still uses the canonical Shopify currency for checkout.

This is display-only. Shopify still charges in your shop's base currency. Visitors see comfortable numbers; Shopify accounting stays clean.

The script (paste into theme.liquid before

Cloudflare Workers + ApogeoAPI: Country Detection at the Edge in 30 Lines

ApogeoAPI — Mon, 04 May 2026 19:26:40 +0000

Cloudflare Workers are the most underrated edge runtime in 2026. They run in 300+ cities, cold-start in milliseconds, and the free tier is 100,000 requests / day — generous enough to power a real product.

Pairing Workers with ApogeoAPI gives you geographic data anywhere on Earth, with sub-50ms latency from the user's perspective. Here's the full implementation with KV caching for cost control.

The Worker (30 lines)

// index.ts — deploy with: wrangler deploy
export interface Env {
APOGEOAPI_KEY: string;
GEO_CACHE: KVNamespace; // KV namespace bound in wrangler.toml
}
export default {
async fetch(req: Request, env: Env, ctx: ExecutionContext): Promise {
const ip = req.headers.get('cf-connecting-ip');
if (!ip) return new Response('No IP', { status: 400 });
// Try KV cache first (free, sub-millisecond)
const cached = await env.GEO_CACHE.get(`geo:${ip}`);
if (cached) return jsonResponse(JSON.parse(cached));
// Fall through to ApogeoAPI
const res = await fetch(`https://api.apogeoapi.com/v1/ip/${ip}`, {
headers: { 'X-API-Key': env.APOGEOAPI_KEY },
});
if (!res.ok) return new Response('Geo lookup failed', { status: 502 });
const data = await res.json();
const out = {
country: data.country.name,
iso2: data.country.iso2,
city: data.city?.name,
timezone: data.timezone?.name,
currency: data.country.currency,
currencyRateUSD: data.country.currencyRate,
};
// Cache 1h in KV (matches typical user session length)
ctx.waitUntil(env.GEO_CACHE.put(`geo:${ip}`, JSON.stringify(out), { expirationTtl: 3600 }));
return jsonResponse(out);
},
};
function jsonResponse(data: unknown): Response {
return new Response(JSON.stringify(data), {
headers: { 'Content-Type': 'application/json', 'Cache-Control': 'private, max-age=300' },
});
}

wrangler.toml

name = "geo-edge"
main = "index.ts"
compatibility_date = "2026-01-01"
[[kv_namespaces]]
binding = "GEO_CACHE"
id = "your-kv-namespace-id"
[vars]
# APOGEOAPI_KEY set via: wrangler secret put APOGEOAPI_KEY

Deploy

npm install -g wrangler
wrangler kv:namespace create "GEO_CACHE"  # paste the id into wrangler.toml
wrangler secret put APOGEOAPI_KEY          # paste your key when prompted
wrangler deploy

Two minutes from npm install to live worker.

Why cf-connecting-ip instead of x-forwarded-for?

Cloudflare automatically sets cf-connecting-ip to the visitor's true IP, even when other proxies are in front. x-forwarded-for is spoofable and unreliable. On Cloudflare Workers, always use cf-connecting-ip.

The KV cache decision

Why KV instead of Cache API or in-memory?

Cache API is per-datacenter — a user routed to a different city on retry hits a cold cache.
In-memory dies with the worker instance (which may be every few seconds at low traffic).
KV is globally replicated, sub-millisecond reads, and the free tier covers 100,000 reads / day. For geo-by-IP this matches the access pattern perfectly.

Cost analysis at scale

Suppose you're running this Worker for 1 million visitors / month, with each visitor making 5 requests:

Worker invocations: 5M / month. Free up to 100K/day = 3M/month. Above that, $0.50 per million.
KV reads: 5M (one per request, mostly cache hits). Free up to 100K/day = 3M/month. Above that, $0.50 per million.
KV writes: 1M (one per unique visitor with cold cache). Free up to 1K/day = 30K/month. Above that, $5 per million.
ApogeoAPI: 1M lookups (one per unique IP, since cache absorbs the rest). Basic plan = $19/mo for 15K. Starter = $29/mo for 100K. Above that, Professional at $79 for 500K.

Worst case at 1M visitors/month: ~$30 in Cloudflare costs + $79 ApogeoAPI = $110/mo all-in for global edge geo-detection. For comparison, MaxMind's commercial GeoIP2 license starts at $370/mo for similar coverage.

Adding currency conversion at the edge

The Worker above already returns currencyRateUSD. Your frontend can use it to localize prices without a second roundtrip:

// On your site:
const geo = await fetch('https://geo-edge.your-domain.workers.dev').then(r => r.json());
const usdPrice = 79;
const localPrice = Math.round(usdPrice * geo.currencyRateUSD);
document.querySelector('#price').textContent =
new Intl.NumberFormat(undefined, { style: 'currency', currency: geo.currency }).format(localPrice);

Useful patterns this enables

A/B test by region — different copy or pricing per country, decided at the edge.
Compliance routing — block or redirect visitors from regions you don't serve (no need for a full geo-blocking service).
Localized signup defaults — pre-fill country dropdowns, currency, language at form load.
Edge analytics — log country distribution without bloating your main app's request log.

Free ApogeoAPI key + 1,000 calls/month at apogeoapi.com. The Cloudflare Workers free tier covers most starter projects without ever hitting paid limits.

Originally published at https://apogeoapi.com/blog/cloudflare-workers-geo. Try ApogeoAPI free at apogeoapi.com.

Localize Stripe Prices to the Visitor's Currency in 25 Lines

ApogeoAPI — Mon, 04 May 2026 19:20:33 +0000

Stripe is opinionated: a Price object has one currency. If your product is priced at $79 USD, that's what Stripe charges. But for conversion optimization, you want to display the price in the visitor's local currency — Argentinians see ARS, Brazilians see BRL, Germans see EUR — converted at the live FX rate.

The math is simple. The trick is doing it without a 200ms client-side flash.

The architecture

Stripe holds the canonical price (USD) — never change this.
At request time, detect visitor country (IP-based, server side).
Look up the local currency for that country.
Fetch the live USD->X rate for that currency.
Render "$79 USD ≈ AR$ {price * rate}" on the page.
When the user clicks "Buy", Stripe still charges in USD. The conversion was display-only.

This pattern is conversion-friendly (visitor sees comfortable numbers) AND chargeback-safe (Stripe records what they actually paid).

Server-side helper

Drop this in lib/localized-price.ts in your Next.js app:

import { headers } from 'next/headers';
interface LocalizedPrice {
usd: number;
display: string;
currency: string;
rate: number;
}
const APOGEO = 'https://api.apogeoapi.com/v1';
export async function localizedPrice(usdAmount: number): Promise {
const ip =
headers().get('x-forwarded-for')?.split(',')[0] ??
headers().get('x-real-ip') ??
'';
if (!ip) return fallback(usdAmount, 'USD', 1);
// Step 1: detect visitor country
const ipRes = await fetch(`${APOGEO}/ip/${ip}`, {
headers: { 'X-API-Key': process.env.APOGEOAPI_KEY! },
next: { revalidate: 3600 },
});
if (!ipRes.ok) return fallback(usdAmount, 'USD', 1);
const { country } = await ipRes.json();
const currency: string = country.currency;
if (currency === 'USD') return fallback(usdAmount, 'USD', 1);
// Step 2: fetch live rate
const fxRes = await fetch(`${APOGEO}/exchange-rates/${currency}`, {
headers: { 'X-API-Key': process.env.APOGEOAPI_KEY! },
next: { revalidate: 14400 }, // 4h
});
if (!fxRes.ok) return fallback(usdAmount, 'USD', 1);
const { usdRate }: { usdRate: number } = await fxRes.json();
const localAmount = Math.round(usdAmount * usdRate);
const display = new Intl.NumberFormat(undefined, {
style: 'currency',
currency,
maximumFractionDigits: 0,
}).format(localAmount);
return { usd: usdAmount, display, currency, rate: usdRate };
}
function fallback(usdAmount: number, currency: string, rate: number): LocalizedPrice {
return {
usd: usdAmount,
display: `$${usdAmount} ${currency}`,
currency,
rate,
};
}

Using it in a Server Component

import { localizedPrice } from '@/lib/localized-price';
export default async function PricingCard() {
const price = await localizedPrice(79); // your Stripe price in USD
return (

Professional Plan
$79 USD
{price.currency !== 'USD' && (

≈ {price.display} at today's rate

)}

Buy now

);
}

What happens at checkout

Stripe charges price_xxx_USD ($79 USD). The visitor sees their card statement in whatever currency their bank uses (their bank does the FX conversion). You as the merchant receive USD. Net effect for visitor: they paid roughly the AR$ amount they saw, give or take 1-2% for the bank's FX spread.

Pitfalls to avoid

Don't change the Stripe Price object dynamically. If you create one Price per currency, you'll have hundreds in Stripe and accounting becomes a mess. One canonical USD price + display-only localization.
Don't show fractional ARS. 300 ARS = 1 USD-ish. Showing "AR$ 7,900.43" looks weird; round to the nearest 100. The maximumFractionDigits: 0 in Intl.NumberFormat handles this.
Fall back gracefully. If ApogeoAPI is down or quota exceeded, fall back to USD display. Don't show "$undefined" or block checkout.
Cache at 4h. ApogeoAPI's exchange rates refresh every 4 hours, matching the ECB update cadence. There's no benefit to caching for less than that.

Stripe's own currency conversion (when it's actually the right choice)

Stripe offers Adaptive Pricing where Stripe creates per-currency Price objects automatically. It works but has trade-offs: 2% FX spread that Stripe pockets, locked-in to Stripe-decided rates, and you lose visibility into what the visitor actually saw before clicking buy. The display-only approach in this tutorial is simpler, transparent, and free.

Going further

If you want a "Switch currency" dropdown (where user can override auto-detect), store the choice in a cookie and check it before falling through to IP detection. The same localizedPrice() helper handles both flows; just pass an optional currency override.

ApogeoAPI free tier (1,000 req/month) covers this for ~5,000 page views per month with the 4h cache. Get a key at apogeoapi.com.

Originally published at https://apogeoapi.com/blog/stripe-localized-pricing-fx. Try ApogeoAPI free at apogeoapi.com.

Geo-Redirect Users at the Edge with Vercel + ApogeoAPI in 10 Lines

ApogeoAPI — Mon, 04 May 2026 19:19:46 +0000

If you serve users in multiple regions, geo-routing is one of those features that sounds complicated but is actually trivial on Vercel. Vercel's Edge Network already knows which datacenter is closest to the visitor — what's missing is enriching that with country / city / currency data so you can do something useful with it.

This tutorial: 10 lines of middleware that intercept every request, look up the visitor's country, and rewrite the URL to a locale-specific path. No client-side flicker, no double network round-trip.

Why edge instead of client-side?

The naive approach is detecting country in the browser via fetch() to your geo API after the page loads. Two problems:

Layout shift. The page renders in English, then 200ms later swaps to Spanish. Users notice.
Wasted server work. If the rendered page is per-locale, you're rendering the wrong one first.

Edge middleware runs before the page renders, so the response that hits the browser is already correct.

The middleware (10 lines)

Save this as middleware.ts at the root of your Next.js project:

import { NextRequest, NextResponse } from 'next/server';
export const config = { matcher: '/((?!_next|api|.*\\..*).*)' };
export async function middleware(req: NextRequest) {
const ip = req.ip ?? req.headers.get('x-forwarded-for')?.split(',')[0] ?? '';
if (!ip) return NextResponse.next();
const res = await fetch(`https://api.apogeoapi.com/v1/ip/${ip}`, {
headers: { 'X-API-Key': process.env.APOGEOAPI_KEY! },
next: { revalidate: 3600 }, // cache by IP for 1h
});
if (!res.ok) return NextResponse.next();
const { country } = await res.json();
const locale = countryToLocale(country.iso2); // your mapping
const url = req.nextUrl.clone();
if (!url.pathname.startsWith(`/${locale}`)) {
url.pathname = `/${locale}${url.pathname}`;
return NextResponse.rewrite(url);
}
return NextResponse.next();
}
function countryToLocale(iso2: string): string {
const map: Record = {
AR: 'es', MX: 'es', ES: 'es',
FR: 'fr', BE: 'fr',
DE: 'de', AT: 'de',
};
return map[iso2] ?? 'en';
}

How it actually works on Vercel

The matcher config tells Vercel which paths to run middleware on. We exclude _next/* (Next.js internals), /api/* (no need to geo-redirect APIs), and any URL with a file extension (images, fonts).

The next: { revalidate: 3600 } option caches the geo lookup at the Vercel edge for 1 hour per IP. So a returning visitor doesn't re-hit ApogeoAPI on every request — your API quota is preserved and latency stays near zero on repeat visits.

Adding live exchange rates to the same flow

If your app shows prices, fetch the country's currency rate alongside in the same middleware call. ApogeoAPI bundles it inline:

const res = await fetch(`https://api.apogeoapi.com/v1/countries/${country.iso2}`, {
headers: { 'X-API-Key': process.env.APOGEOAPI_KEY! },
next: { revalidate: 14400 }, // 4h matches FX cache
});
const { currency, currencyRate } = await res.json();
// Inject into response headers — your page reads from these
const response = NextResponse.rewrite(url);
response.headers.set('x-user-country', country.iso2);
response.headers.set('x-user-currency', currency);
response.headers.set('x-user-fx-rate', String(currencyRate));
return response;

Now any Server Component can read those headers via headers() and render localized prices in the user's currency without a second roundtrip.

Cost considerations

Vercel Edge Middleware is free up to 1M invocations / month on the Hobby plan. ApogeoAPI's free tier is 1,000 calls / month. That's enough for a project at the early-traction stage. With Vercel's edge caching at 1h, you only burn API quota once per IP per hour — typical usage stays under quota even with thousands of daily visitors.

Common gotchas

Localhost. req.ip is empty in dev. Hardcode an IP for testing or use ngrok.
VPN visitors. Geolocation reflects the VPN exit node, not the user's actual country. Acceptable for most apps, not for fraud detection.
Cookies. If you let users override the auto-detected locale (a "Switch to English" button), set a cookie and check it before geo-detecting.

Live demo

Visit apogeoapi.com/demo and ask the AI agent: "What country am I from?". It runs the same kind of edge lookup and returns the answer in under 200ms. Source code for the demo is in our public repo.

Get a free ApogeoAPI key at apogeoapi.com — 1,000 requests / month, no credit card.

Originally published at https://apogeoapi.com/blog/vercel-edge-geo-routing. Try ApogeoAPI free at apogeoapi.com.

ipstack Alternative — Free IP Geolocation API with Geographic Data

ApogeoAPI — Mon, 04 May 2026 19:13:34 +0000

ipstack is one of the most widely recommended IP geolocation APIs — but its free tier is nearly unusable and it doesn't include geographic data. Here's what you get with ApogeoAPI instead.

What Is ipstack?

ipstack is a dedicated IP geolocation API with 45+ billion IP records. It returns country, region, city, zip, timezone, and connection information. Paid plans start at $9.99/month. The free plan allows 100 requests/month over HTTP only — no HTTPS, which makes it impractical for any real application.

ipstack Limitations

HTTP only on free tier: HTTPS requires a paid plan — this is a dealbreaker for most production apps.
100 requests/month free: Less than 4 requests per day.
IP geolocation only: No country data, no states, no cities, no exchange rates.
Paid from $9.99/month: For 50,000 IP-only requests — you still need separate APIs for geographic data.

ApogeoAPI vs ipstack

Feature	ipstack	ApogeoAPI
IP Geolocation	✅	✅
HTTPS on free tier	❌	✅
Countries data	❌	✅
States/cities	❌	✅
Exchange rates	❌	✅
Free tier	100 req/mo, HTTP only	14-day full trial

Code Comparison

// ipstack
const res = await fetch(
'http://api.ipstack.com/134.201.250.155?access_key=YOUR_KEY' // HTTP only on free
);
// ApogeoAPI — same data + currency + timezone, HTTPS on all tiers
const res = await fetch(
'https://api.apogeoapi.com/v1/geolocate/134.201.250.155',
{ headers: { 'X-API-Key': 'YOUR_KEY' } }
);
// Returns: country_code, country_name, region, city, timezone, currency, lat, lon

When ipstack Is Still the Right Choice

ipstack has enterprise plans with very high volume limits and dedicated support. If you need 100M+ IP lookups per month and only care about IP data, ipstack's enterprise tier might be appropriate.

How to Migrate from ipstack

Change the base URL from api.ipstack.com/{ip}?access_key=KEY to api.apogeoapi.com/v1/geolocate/{ip} with an X-API-Key header. Field names are similar: country_code, city, region_name → region.

Originally published at https://apogeoapi.com/blog/ipstack-alternative. Try ApogeoAPI free at apogeoapi.com.

GeoDB Cities Alternative — Simpler API, Better Price

ApogeoAPI — Mon, 04 May 2026 19:12:48 +0000

GeoDB Cities is a solid geographic database — but its RapidAPI pricing, complex query syntax, and missing features have led many developers to look for alternatives. Here's what ApogeoAPI offers instead.

What Is GeoDB Cities?

GeoDB Cities is hosted on RapidAPI and provides access to countries, regions, and cities data worldwide. It covers 150K+ cities with coordinates and timezone data. However, the free plan is extremely limited: 1 request per second, 1,000 requests per day — barely usable in production.

The Problems with GeoDB Cities

Complex query syntax: GeoDB uses non-standard query parameters (namePrefix, minPopulation, sort) that require reading extensive documentation.
Rate limits on free tier: 1 req/sec and 1,000/day means a single busy hour can exhaust your daily quota.
RapidAPI pricing: Gets expensive at scale. You're also dependent on RapidAPI's infrastructure and terms.
No exchange rates: Zero support for currency data.
No IP geolocation: Can't detect user location from IP.

ApogeoAPI as a GeoDB Alternative

ApogeoAPI covers the same 150K+ cities with a simpler REST API — and adds exchange rates for 161 currencies and IP geolocation on top. One subscription, one key.

Side-by-Side API Comparison

// GeoDB Cities — complex query params
GET https://wft-geo-db.p.rapidapi.com/v1/geo/cities?namePrefix=lon&countryIds=US&limit=10
// ApogeoAPI — simple REST
GET https://api.apogeoapi.com/v1/countries/US/states/CA/cities?page=1&limit=10
// Global search across all countries
GET https://api.apogeoapi.com/v1/search?q=london&limit=10

Pricing Comparison

GeoDB Cities on RapidAPI: free plan is 1 req/sec / 1K/day, paid plans start at $10/month for 10K/day. ApogeoAPI: free tier forever (1,000 req/month for countries + states), $19/month Basic includes cities, exchange rates, and IP geo with 15,000 requests.

Migration Guide

GeoDB returns city, region, country, latitude, longitude, timezone. ApogeoAPI returns name, stateCode, countryCode, latitude, longitude, timezone. The field mapping is straightforward — change the field names and the base URL, and you're done.

Originally published at https://apogeoapi.com/blog/geodb-cities-alternative. Try ApogeoAPI free at apogeoapi.com.