Geo

Three fields are stored per event and per visit: country, region and city. Nothing finer. No coordinates, no postcode, and never the IP address the lookup was made from.

Resolution order

The collector tries three sources, in this order, and stops at the first that answers.

1. Cloudflare’s own edge data. When the collector runs on Cloudflare Workers, every request arrives with request.cf.country, .region and .city already attached. It is free, it is computed at the edge before the request reaches any code, and it wins wherever it exists.

2. A local GeoLite2 City database. Off Cloudflare, the collector’s Node entry loads a MaxMind GeoLite2 City .mmdb file at boot and looks the client address up in memory. Private and loopback addresses are skipped without a lookup.

3. Nothing. All three fields are null. The hit is still recorded in full; it simply has no location.

The Worker bundle deliberately contains no geo library and no filesystem access, which is why the two paths exist at all.

What each field contains

Field	Cloudflare	GeoLite2
country	ISO-3166 alpha-2, e.g. DE	country.iso_code, falling back to registered_country.iso_code
region	Cloudflare’s region name	First subdivision, English name
city	Cloudflare’s city name	City, English name

The dashboard turns the country code into a name and a flag with Intl.DisplayNames, but the filter value is always the code:

/dashboard/<siteId>?range=30d&country=DE

Region and city are filtered on the string as stored.

The two sources do not agree word for word

Cloudflare and GeoLite2 name regions and cities differently. A site that moves between the two — say from a Node deployment to Workers — will see both spellings in the same breakdown for the overlapping period. Country codes are stable across both.

Accuracy

IP geolocation is an estimate, and city-level accuracy is the weakest part of it.

• Country is right the large majority of the time, and is the level worth making decisions on.
• Region is materially less reliable, especially in small countries and on mobile networks.
• City is frequently the location of the ISP’s egress rather than the visitor’s. Mobile carriers, corporate VPNs and privacy relays (iCloud Private Relay, consumer VPNs) routinely place a visitor hundreds of kilometres away or in another country entirely.

Treat city as a hint about your audience’s shape, never as a fact about a person.

Requirements for it to work at all

Geo is derived from the address the collector sees.

• Behind Cloudflare, cf-connecting-ip is set for you.
• Behind any other proxy, forward X-Forwarded-For (the Node entry reads the first hop) or X-Real-IP.
• A proxy that strips both leaves every visitor at the proxy’s own location, and — worse — collapses every visitor into one hash.

See Proxying the collector for the details.

Attribution

This product includes GeoLite2 data created by MaxMind, available from https://www.maxmind.com.

That notice is a condition of the GeoLite2 End User Licence Agreement, and the hosted service reproduces it here.

The database is refreshed weekly on the hosted collector. Old databases drift: addresses are reassigned constantly, and a year-old file misplaces a meaningful share of traffic.

What is not collected

• No IP address is stored. It is an input to the visitor hash and to the geo lookup, and is discarded.
• No latitude or longitude is written, even though GeoLite2 returns them.
• No timezone, ASN, ISP or connection type.
• No browser geolocation API is ever called, so no permission prompt appears.

Related

• What is stored
• Filters & dimensions