How Edge Geolocation Works: x-vercel-ip-country, CF-IPCountry & Friends

TL;DR

Major CDNs resolve every visitor's country from their IP during TLS termination and attach it to the request as a header — x-vercel-ip-country (Vercel), cf-ipcountry (Cloudflare), cloudfront-viewer-country (AWS). Reading a header is ~0ms and free, which is why edge headers beat third-party geo API calls for production geo-routing.

Every geo-targeting product ultimately answers one question — where is this request from? — and there are exactly two ways to answer it: call a geolocation API with the IP, or read the answer the CDN already computed. This is a reference for the second, better way.

The headers by provider

Vercel — x-vercel-ip-country, plus -country-region and -city companions.
Cloudflare — cf-ipcountry (enable "IP geolocation"); richer data via request.cf in Workers.
AWS CloudFront — cloudfront-viewer-country (opt-in via origin request policy).
Fastly — geo data via VCL variables (client.geo.country_code), surfaced as headers you define.

All use ISO 3166-1 alpha-2 codes (DE, NO), with provider-specific sentinels for unknowns (XX) and Tor (T1).

Why this beats geo API calls

Latency — the lookup happened during connection handling; reading the header costs nothing. A third-party API call adds a full round-trip (50–300ms) to every decision.
Cost & limits — headers are included in the platform; geo APIs meter per request and rate-limit free tiers.
Privacy — the IP never leaves your infrastructure path or gets shared with a third-party lookup service; you can consume the country code and discard the IP entirely.

The privacy upside: country is derived in-path and the IP can be dropped immediately.

Implementation notes

Normalize to uppercase, treat XX/T1/missing as "unknown" (do nothing rather than guess), and if you support multiple deployment targets, read headers in preference order — e.g. Vercel's, then Cloudflare's — so the same code runs anywhere. This is exactly how Easy Redirects resolves country: edge headers on our hosting platform, zero external geo API calls, IP discarded after the read.

Geo-redirects on your HubSpot site in 5 minutes

One script tag, no code, no DNS changes. Free plan included.

Start free

Frequently asked questions

Can these headers be spoofed?

Not by visitors — edge providers strip inbound copies of their own geo headers and set them from the connecting IP, so a client sending a fake x-vercel-ip-country gets it overwritten. The header is only trustworthy when your traffic actually flows through that provider; a request reaching your origin directly could carry anything.

What's in the header beyond country?

Most providers expose more granular companions: region/state (x-vercel-ip-country-region, cf-region-code), city (x-vercel-ip-city), and sometimes lat/long and timezone. Accuracy drops with granularity — country is the dependable one.

What does XX or T1 mean in a country header?

Unknown/unclassifiable IP (XX) or Tor exit node (T1, Cloudflare). Treat both as 'no country': fall through to default behavior rather than guessing.