# Network · Traffic map accuracy

> How to get city/state-level truth on the /admin/traffic map — Cloudflare location headers, the places contract extension, and what the map does and does not claim today.

---

.. toc::

## What the map claims today (be honest with yourself first)

Two very different data sources share one map:

- **Hub visits (2plot.ai)** plot at **real coordinates** — ip-api.com
  returns lat/lon + city + region per public IP, and markers group into
  ~10 km cells. City-level, genuinely useful.
- **Satellite reports** only carry `countries: {CC: hits}` — so their
  markers sit on **country centroids**. Every US visitor to dash-email
  becomes one marker in Kansas. The per-app ring offset around each
  centroid is *presentation* (so overlapping apps stay hoverable), not
  accuracy — the tooltip still names only the country.

That is the ceiling of the current satellite contract, and why the map
clusters at country centers. Raising the ceiling means satellites must
*capture* finer location, then *report* it.

## Step 1 — turn on Cloudflare visitor-location headers (free)

For every zone proxied through Cloudflare (2plot.media, 2plot.xyz,
2plot.dev, …): **Dashboard → your zone → Rules → Settings → Managed
Transforms → enable "Add visitor location headers".** Available on all
plans, including Free. Every request then arrives with:

```
CF-IPCity: Denver          CF-IPLatitude: 39.739
CF-Region: Colorado        CF-IPLongitude: -104.984
CF-Region-Code: CO         CF-IPCountry: US
CF-IPContinent / CF-Timezone / CF-PostalCode also available
```

No API calls, no latency, no rate limits — the accuracy problem becomes
a header read. **The headers only appear on proxied (orange-cloud)
records**, and proxying is decided **per DNS record, not per zone** —
which matters for this network:

- **Clerk's records must stay DNS-only** (`clerk.<domain>`,
  `accounts.<domain>`, and the email DKIM CNAMEs) — proxying those
  breaks Clerk's TLS provisioning. But those are Clerk's own
  subdomains; the app host record (`2plot.media`, `www`, …) is a
  separate record and CAN be proxied without touching them. In this
  network only the hub carries Clerk DNS anyway — satellites use the
  redirect model (sign-in happens on 2plot.ai), so their zones have no
  Clerk records at all.
- **Render behind the Cloudflare proxy works** with SSL/TLS mode set
  to *Full (Strict)* on the zone. Test the sign-in round trip after
  flipping any record.

**If you'd rather not proxy anything, that's fine too** — the map does
not depend on Cloudflare. The hub already gets city-level lat/lon from
ip-api.com per public IP (free tier ~45 lookups/min over plain HTTP:
cache per IP, resolve outside the request path), and that is what
powers the map's "Precise" layer today. Cloudflare headers are the
zero-cost upgrade path, not a requirement; without them, satellites
simply stay on the country-centroid layer.

## Step 2 — the `places` contract extension (v2.1)

Alongside `countries`, satellites report a capped list of place rollups:

```json
"places": [
  {"cc": "US", "region": "CO", "city": "Denver",
   "lat": 39.7, "lon": -105.0, "hits": 41},
  {"cc": "DE", "region": "BE", "city": "Berlin",
   "lat": 52.5, "lon": 13.4, "hits": 9}
]
```

Rules that keep it truthful and private:

- **Round lat/lon to one decimal (~10 km)** — enough to see a metro,
  impossible to see a house. Never ship raw coordinates.
- Cap at ~30 places, most-visited first; everything below the cap stays
  country-level in `countries` (which remains the complete count).
- `region`/`city` optional — send what you have. A place with only
  `cc` + rounded lat/lon still beats a centroid.
- Humans only, same as every other v2 field.

Hub-side this rides the same accumulate-across-restarts reader as
pages/countries; the map prefers a report's `places` and falls back to
centroid-`countries` per app. (Reader + map support is the next hub
change; satellites can start sending `places` first — unknown fields
are ignored, nothing breaks.)

## Step 3 — reading the map like a marketing tool

- **Visits mode** answers "where is my audience" — size ads/regions by
  marker area, which scales with √hits so big markers don't lie.
- **Session-length mode** answers "where is my *engaged* audience" — a
  small marker with long sessions is a better ad target than a big
  marker of bounces. Cross-check both before spending.
- Satellite session-length markers all use the app's overall median
  (that's the reported granularity); only hub markers have per-place
  session medians until `places` ships with per-place durations.
- Bot filtering happens before any of this, but scrapers with browser
  UAs still slip through — a "city" showing hundreds of hits, seconds
  of session, from one visitor is a crawler, not a market.

## Current limitations, stated plainly

| Limitation | Cause | Fix |
|---|---|---|
| Satellite traffic clusters at country centers | contract sends countries only | Steps 1–2 |
| Ring offsets around centroids | presentation, not data | tooltip names the country; ignore the spread |
| Hub geo misses some visitors | private/CGNAT IPs, ip-api misses | unavoidable; counts stay truthful, only the map thins |
| One app median for satellite session markers | reported granularity | per-place durations in a later `places` rev |


---

*Source: /docs/traffic-map*