countrycheck: which country is this point in?

An offline lookup library built on the Trifold grid. The level-10 grid (~7 km cells) classified against country polygons with accurate OSM-derived borders — extended with coastal waters and including X-coded territories like Kosovo and the Caspian Sea — collapses into a 323 KB dataset that names the country anywhere on Earth in microseconds, with a confidence value for every answer. Python and JavaScript give identical results. This page runs the real JS library in your browser; the dataset is embedded right in this HTML file.

Click any classified point for its full answer: country code (GADM gid_0), ISO 2, name, kind, confidence, area share and cell address (computed on the fly for open-ocean points, whose cells are not stored). Switching on exact border refinement makes the source polygons authoritative in every cell a border crosses. Caveats inherited from the source data: coastal waters are an approximate distance-based assignment, not legal EEZ; disputed territories follow GADM (Crimea, Western Sahara…); lakes belong to their surrounding country, except the Caspian Sea, which is its own XCA entry.

User guide

import { CountryCheck } from "./countrycheck.mjs";

// Node: bundled file · browser: fetch the 323 KB dataset
const cc = await CountryCheck.fromFile();                  // Node
const cc = await CountryCheck.fromUrl("countries_L10.tfcs"); // browser

cc.country(24.7536, 59.437);   // 'EST'  (lon, lat)
cc.check(-0.1276, 51.5072);
// { country: 'GBR', iso2: 'GB', name: 'United Kingdom',
//   kind: 'country', confidence: 1, share: 1,
//   cell: 'TFA95BM', refined: false }

from countrycheck import CountryCheck

cc = CountryCheck()                    # bundled data
cc.country(24.7536, 59.4370)           # 'EST'
cc.check(-0.1276, 51.5072)
# CountryResult(country='GBR', iso2='GB',
#   name='United Kingdom', kind='country',
#   confidence=1.0, share=1.0, cell='TFA95BM',
#   refined=False)

What the answer means

Measured accuracy: 99.82% agreement with exact polygon containment on 30,000 uniform random points. The country and none answers were 100% correct; all residual error lives in border answers, which self-report lower confidence. With the border refinement loaded, agreement reaches 100.0% on the same sample.

Command line

$ python countrycheck/python/countrycheck.py 24.7536 59.4370
EST  iso2=EE  name='Estonia'  kind=country  confidence=1.000  share=1.0  cell=TFAVKGR  refined=False

The CLI loads the border refinement automatically when borders_L10.tfcr is present. Install with pip install countrycheck or npm install countrycheck, or run straight from a repo checkout.

Technical info

The borders come from the timezone-boundary-builder “with oceans” polygons (OSM-derived, already reaching into territorial water); GADM level-0 supplies only the country identity and ISO codes, joined by max land overlap. 256 countries and territories, 6.90M level-10 cells belonging to some country, of which 195,473 are border cells. Full documentation, the one-pass build.py, the PostGIS source build (sql/build_countries_coastal.sql) and the cross-language test suite live in countrycheck/ on GitHub. Roadmap: an L12 (~1.8 km) variant and timezone detection from the same source data.

Accuracy: tested on 57,501 real airports

Ground truth is the OurAirports dump — 57,501 points, each tagged with an ISO country code from an unrelated source. countrycheck places 99.50% of them in the correct country from the bundled 323 KB data, and 99.68% with the border refinement loaded. Interior-country answers are 99.91% correct; the refinement works only on the 729 airports that fall in a border cell, and there it lifts agreement from 80.66% to 95.20% — the payoff of the accurate OSM-derived borders.

Reproduce with scripts/accuracy_countrycheck_airports.py (airports) and scripts/benchmark_countrycheck.py (vs. SQL containment).

Benchmark: 7–97× faster than SQL spatial engines

One workload, four engines: assign a country (gid_0) to 100,000 sphere-uniform random points against the same country polygons. Median of seven warm runs, Apple M5 Pro, June 2026. The refined Trifold answers reproduce exact polygon containment to 99.995% (see above) while running an order of magnitude faster — ~7× PostGIS, ~97× DuckDB Spatial. Called one point at a time, the gap holds.

DuckDB 1.5.3 and PostGIS 3.6.3 compute exact containment and returned byte-identical answers; BigQuery is documented but was not run in this pass. PostGIS singular includes localhost TCP + Docker transport; DuckDB runs embedded in-process. The live figure in the demo panel is the same throughput measured on your own device. Full methodology, dataset manifest, the airport test and the BigQuery procedure: countrycheck_benchmark.md.