Skip to content

Geo database ​

Trail looks up the visitor's location from the request IP, in memory, then drops the IP. The IP is never stored and never sent to a third party.

Where the location comes from ​

For each event Trail takes the first source it can trust:

  1. Your edge, through the signed proxy. The first-party /t/* proxy that npx trail-analytics init adds forwards the location your host's edge attached (Vercel, Cloudflare or Netlify), signed with your crawl token. Trail uses it only when the signature checks out.
  2. Cloudflare. When Trail itself sits behind Cloudflare, it reads CF-IPCountry, CF-Region-Code and CF-IPCity, but only from requests that came from Cloudflare's own addresses. See Cloudflare.
  3. The database, for the client IP that Trail trusts. Which IP that is depends on TRAIL_TRUSTED_PROXIES; see Client IP and proxies.

When an edge gives a country but no region or city, Trail fills the gaps from the database, but only if the database agrees on the country. Every event records which source answered.

How accurate it is ​

The dashboard labels each level:

LevelLabelWhy
CountrynoneShown as fact
RegionRegions · approximateApproximate, whatever the source
CityCities · rough estimateOften the city of the visitor's network hub, not where they are

City is the weak level for every source. Mobile networks route through a few hub cities; independent GPS checks put only 20–37% of Indian visitors within 25 km of the city shown, whatever the database. The journey sheet adds "(rough estimate)" after a city, and the Visitors city column carries the same note.

Under the Overview's Location panel a chip names the source that answered most events in the last 24 hours:

ChipSource
Location: your edge (Vercel)The signed proxy, with Vercel's location
Location: CloudflareCloudflare, through the proxy or in front of Trail
Location: NetlifyThe signed proxy, with Netlify's location
Location: DB-IP Lite (country)The built-in country database
Location: your databaseThe database, with your TRAIL_GEO_DB file

Trail never shows latitude, longitude or postal codes.

Countries: built in ​

Countries work with no setup. The Trail binary embeds the DB-IP Lite Country database (about 8.5 MB), so a fresh install shows countries from the first visit.

Settings → Config shows the database in use and the month it was built, for example Countries, built in (2026-11). GET /api/config returns the same as "geo": {"source": "embedded-country", "build": "2026-11"}.

The built-in file is refreshed each month in the Trail repository. Upgrade Trail to get the newer edition.

Region and city: optional ​

For region and city without an edge, point Trail at a City database of your own. It replaces the built-in one.

We recommend GeoLite2 City with your own free MaxMind key over DB-IP City: it places about 1.5× more visitors within 25 km in India. Any database's city is still a rough estimate, often the ISP's hub city.

  1. Create a free MaxMind account and a license key, then download GeoLite2 City as an .mmdb file. Follow MaxMind's license terms for it.
  2. Put it on the server, for example /var/lib/trail/GeoLite2-City.mmdb.
  3. Set TRAIL_GEO_DB to that path and restart Trail.

DB-IP Lite City works the same way: download dbip-city-lite-YYYY-MM.mmdb.gz from db-ip.com/db/lite.php, unzip it (about 130 MB) and point TRAIL_GEO_DB at it.

Settings → Config then reads Your database (YYYY-MM) and /api/config reports "source": "custom". Trail refuses to start if TRAIL_GEO_DB points at a file it cannot open, so a typo does not silently turn cities off.

The file is opened once at startup. To refresh it, replace the file and restart. Both databases publish new editions regularly.

Privacy modes ​

Visitors in private mode, and visitors who have not given or have refused consent, get country only. Region and city are dropped whatever the source, even when TRAIL_GEO_DB is set or an edge sends a city.

Attribution ​

DB-IP Lite is licensed under CC BY 4.0, which requires a credit where the data is shown. Trail shows "IP geolocation by DB-IP" with a link to db-ip.com in Settings → Config, and lists the database in its NOTICE file. If you show Trail's location data elsewhere, credit DB-IP there too.

Next ​