Geolocation Logic in Edge Functions: Country Detection, Compliance, and Routing

Last year a client called me at 11 PM because their new streaming launch was showing German users a French content catalog. The bug wasn't in their CMS — it was a single misconfigured edge function that trusted the wrong header for country detection. We fixed it in about twenty minutes, but that call is a perfect example of why geolocation logic at the edge feels simple until it isn't.

How Country Detection Actually Works at the Edge

After a decade of working on CDN edge platforms, I can tell you there's no magic GPS lookup happening. When a request hits an edge PoP, the platform has already mapped the client IP to a country using a GeoIP database, usually MaxMind or something very similar that the provider keeps updated every few days. That result gets injected as a header before your code even runs — think CF-IPCountry on Cloudflare, X-Vercel-IP-Country on Vercel, or client.geo.country_code in Fastly's VCL and Compute. Your function isn't doing the lookup, it's just reading a string someone else set for you.

That's important because the accuracy isn't 100%, and you shouldn't treat it like it is. Country-level accuracy is generally solid, around 98-99% for most providers in North America and Europe, but it falls apart for IPs coming from corporate VPNs, mobile carriers that backhaul traffic, or the smaller island nations that get bucketed incorrectly. I once spent two days chasing a "bug" where users in Switzerland were being flagged as Italy — turned out their mobile ISP was routing through Milan. If you're building compliance features, you have to design for UNKNOWN or XX and not just assume you'll always get a clean two-letter code. The HTTP Working Group Specifications don't standardize these geo headers, so each provider's implementation is slightly different.

You've also got choices in how you access that data. The header approach is fastest because it adds near-zero overhead, but some runtimes expose a richer geo object via their request context. That object often includes city, region, latitude/longitude, and even the timezone, but it costs more to parse. For most country detection and routing, I stick with the header. It keeps the function lean, which matters a lot when you're trying to control Edge Function Cold Start Optimization: Reducing Initialization Latency to Milliseconds and shave every possible millisecond off TTFB. Don't parse what you don't need.

// Cloudflare Workers / Vercel Edge - reliable country detection pattern
export function getCountry(request) {
  // Try provider-specific headers first, normalize to upper case
  const country = 
    request.headers.get('cf-ipcountry') ||
    request.headers.get('x-vercel-ip-country') ||
    request.headers.get('x-geo-country') ||
    'XX'; // Fallback for unknown

  // Filter out invalid or failed lookups
  if (country === 'XX' || country === 'T1' || !/^[A-Z]{2}$/.test(country)) {
    return null;
  }
  
  return country.toUpperCase();
}

export default {
  async fetch(request) {
    const country = getCountry(request);
    
    if (!country) {
      // Don't guess - send to default experience and log it
      console.warn('Geo lookup failed for IP:', request.headers.get('cf-connecting-ip'));
      return fetch(request);
    }
    
    // Add normalized header for downstream origin
    const newHeaders = new Headers(request.headers);
    newHeaders.set('x-detected-country', country);
    return fetch(new Request(request, { headers: newHeaders }));
  }
}

Building Compliance-Aware Geographic Routing That Doesn't Annoy Users

The first time we rolled out geo-based compliance at scale, we made the classic mistake: we blocked everything we weren't sure about. If a user from Germany hit a page that wasn't explicitly cleared for GDPR, we showed a hard block page. Our legal team loved it, our bounce rate didn't. You can't treat compliance routing as a simple firewall rule. For regulations like GDPR, CCPA, or content licensing deals, you need routing logic that is both accurate and graceful — redirect to the right experience, don't just deny access.

The pattern that actually works is a tiered decision tree inside the edge function. First, detect the country. Second, map that country to a compliance region — for example, EU, EEA, UK, California, or Rest of World. Third, apply the rule for that region without performing heavy computation. I keep a static allowlist/blocklist baked into the function bundle rather than fetching it from KV or an external API on every request. An external fetch adds 10-40ms and risks failure, and when you're up against Edge Function Execution Limits: CPU Time, Subrequests, and Creative Workarounds you don't want a subrequest to decide whether the page can load. Pre-compile your region maps at build time if you can.

And please, handle the user experience edge cases I see teams forget every time. Don't redirect a user in a loop if they manually choose a different country or language — set a cookie like user_override_country=FR and respect it. Don't base pricing or currency routing solely on IP if the user is logged in and has an account country. And always log your routing decisions with the x-detected-country value so you can debug it later. According to guides on web.dev Articles, unexpected redirects are one of the top causes of poor Core Web Vitals for international sites because they add round trips. Keep your routing at the edge to a single 302 or, better yet, an internal rewrite where the URL doesn't change at all.

// Geographic routing with compliance regions - no external fetch
const REGION_MAP = {
  EU: ['DE', 'FR', 'IT', 'ES', 'NL', 'PL', 'SE', 'IE', 'BE', 'AT', 'PT', 'FI'],
  UK: ['GB'],
  EEA: ['NO', 'IS', 'LI'],
  CALIFORNIA: ['US'] // Special handling for CCPA if state data available
};

const COMPLIANCE_RULES = {
  EU: { consentRequired: true, contentPolicy: 'strict' },
  UK: { consentRequired: true, contentPolicy: 'strict' },
  DEFAULT: { consentRequired: false, contentPolicy: 'standard' }
};

function getRegion(country) {
  for (const [region, countries] of Object.entries(REGION_MAP)) {
    if (countries.includes(country)) return region;
  }
  return 'DEFAULT';
}

export async function handleRouting(request) {
  // Respect user override first
  const cookieCountry = request.headers.get('cookie')?.match(/user_override_country=([A-Z]{2})/)?.[1];
  const detectedCountry = cookieCountry || getCountry(request) || 'US';
  
  const region = getRegion(detectedCountry);
  const rule = COMPLIANCE_RULES[region] || COMPLIANCE_RULES.DEFAULT;

  // Example: rewrite to localized path instead of redirect loop
  const url = new URL(request.url);
  if (rule.consentRequired && !url.pathname.startsWith(`/${detectedCountry.toLowerCase()}`)) {
    url.pathname = `/${detectedCountry.toLowerCase()}${url.pathname}`;
    // Use rewrite at edge - better for SEO than 302
    return fetch(new Request(url, request));
  }

  return fetch(request);
}

Performance Reality Check: What Geolocation Logic Actually Costs

Everyone worries that adding logic to the edge will slow things down, and they're right to worry. But country detection itself is almost free. Reading a header is sub-millisecond work. Where I've seen teams get burned is when they start adding city-level lookups, large JSON mapping files for country-to-language, or — the worst offender — a call out to a third-party geolocation API for "more accurate" data. I audited one function that loaded a 1.2MB JSON file of geo mappings on every cold start. It blew past our memory budget and added 80ms. We refactored it to a simple trie and cut it to 12KB, which plays much nicer with Edge Function Memory Management: Working Within Tight Limits at CDN Scale.

Keep your bundle small and your logic branch-free where possible. If you're only routing by country, your region map should be a Set or Object lookup, not an array scan. Avoid regex for country codes unless you have to validate. And measure properly — don't just test from your office in Virginia. Test from a PoP in Singapore or São Paulo. The latency characteristics change based on where the function is actually executing versus where your origin is.

Here's what I've consistently measured across Cloudflare Workers, Fastly Compute, and Vercel Edge when the logic is kept lean and header-based. These numbers are from production traffic on a mid-sized e-commerce site doing about 15M requests per day, measured over a 7-day window with 95th percentile included:

Implementing Country Detection Without Wrecking Your Cache

You've got the country code — now don't shoot yourself in the foot with how you use it. The rookie mistake we see constantly is branching your entire response on the raw two-letter code inside the handler. Something like if (country === 'DE') return fetch('de-origin.example.com') for 180+ countries. It works in dev, but in production it atomizes your cache. We've watched teams drop from a 92% cache hit ratio to 28% overnight because every country variant created its own cache key. Your origin suddenly takes 3-4x the traffic and your p95 jumps by 140ms.

The pattern that actually scales is to normalize countries into compliance and routing buckets *before* you touch the cache key. Don't cache by country — cache by intent. For most global apps, three to five buckets covers 95% of the logic: EU (GDPR), UK (UK-GDPR), US-CA (CCPA), RESTRICTED (sanctioned/blocked regions), and ROW (rest of world). You map the 195+ ISO codes to those buckets in a tiny lookup, then use that bucket for routing and for your Vary or Cache-Key. That keeps your cache cardinality low and your hit rate in the high 80s or 90s.

And please, don't ship geo-logic straight to production without a way to mock it locally. The edge runtime isn't your laptop — request.cf.country doesn't exist in Node. We strongly recommend building this with proper Edge Function Testing Strategies: Unit, Integration, and End-to-End at the Edge — mock the geo headers in Vitest, run integration tests against a local Miniflare/Wrangler instance with different CF-IPCountry headers, and add synthetic checks for each bucket. It's a 20-minute setup that saves you a 2 AM rollback when you realize you typo'd 'GB' as 'UK'.

// Production-ready geo routing with bucketed caching
export default {
  async fetch(request, env) {
    // 1. Extract country - Cloudflare, Vercel, Fastly all differ
    const country = request.cf?.country 
      || request.headers.get('x-vercel-ip-country') 
      || request.headers.get('x-geo-country') 
      || 'US';

    // 2. Normalize to buckets - keeps cache sane
    const EU_COUNTRIES = new Set(['DE','FR','IT','ES','NL','PL','IE','SE','BE','FI','PT','AT','DK','CZ','GR','HU','RO']);
    const RESTRICTED = new Set(['RU','BY','IR','KP','SY','CU']);
    
    let bucket = 'ROW';
    if (RESTRICTED.has(country)) bucket = 'RESTRICTED';
    else if (EU_COUNTRIES.has(country)) bucket = 'EU';
    else if (country === 'GB') bucket = 'UK';
    else if (country === 'US') bucket = 'US';

    // 3. Compliance gate before routing
    if (bucket === 'RESTRICTED') {
      return new Response('Not available in your region', { status: 451 });
    }
    if (bucket === 'EU' && isBlockedForGDPR(request)) {
      return Response.redirect('/eu-consent', 302);
    }

    // 4. Route with bucketed cache key - not raw country
    const url = new URL(request.url);
    url.hostname = bucket === 'EU' ? 'eu.origin.example.com' : 'global.origin.example.com';
    
    let response = await fetch(url, request);
    response = new Response(response.body, response);
    response.headers.set('Vary', 'X-Geo-Bucket');
    response.headers.set('X-Geo-Bucket', bucket);
    response.headers.set('Cache-Tag', `geo-${bucket}`);
    return response;
  }
}

When GeoIP Lies: VPNs, Anycast Drift, and Silent Failures

Let's be blunt: country detection is 98.5% to 99.2% accurate at the country level if you're using MaxMind GeoIP2 or the CDN's native DB, but that last 1-2% will generate 90% of your support tickets. Corporate VPNs egressing from Frankfurt while the user sits in Chicago, Apple's iCloud Private Relay bouncing through random regions, Starlink's ground stations showing a user 800 miles away — we've seen all of it. Don't treat the geo header as ground truth. Treat it as a strong hint. If you're doing hard compliance blocking based *solely* on IP, you're going to block legitimate users and miss the ones you're supposed to block.

The fix isn't more accurate IP data, it's defense in depth. Always provide a fallback chain. First, trust the edge header. Second, check for a user-set preference cookie like user_region_override — if they've manually selected "Deutschland" in your region picker, respect it. Third, use Accept-Language as a tie-breaker, not a primary signal. And for anything with legal teeth — GDPR consent, age-gating, export controls — log the decision. Emit a structured log with { country, bucket, ip, acceptLanguage, decision } so you can audit later. If you ever get a regulator asking why you served personalized ads to someone in France, "the GeoIP said US" won't cut it without receipts.

When it does go wrong, it'll fail silently. The user won't get an error, they'll just get routed to the wrong pricing, the wrong language, or the wrong compliance flow. That's why you can't debug this with console.log alone in production. You need to attach tail workers and inject a debug header in staging — something like x-geo-debug: country=DE, bucket=EU, colo=FRA — and watch it in real time. Our workflow is to lean on Edge Function Debugging Techniques: Console, Tail Workers, and Remote Inspection to trace these ghost routes, and we never push a geo rule change without a Edge Function Versioning and Deployment Patterns: Blue-Green, Canary, and Gradual strategy. Roll it to 5% of traffic in one colo (say, lhr), compare conversion and 451 rates for 30 minutes, then promote. It adds 45 minutes to your deploy but prevents a global mis-route.

Frequently Asked Questions