# Atherverse atlas data

Retrieved 7 September 2026 from [GeoNames](https://www.geonames.org/), using its [cities500 export and schema](https://download.geonames.org/export/dump/readme.txt). GeoNames data is licensed under [Creative Commons Attribution 4.0](https://creativecommons.org/licenses/by/4.0/). Display attribution and a source link wherever the atlas is presented. This output is a filtered, reformatted derivative of GeoNames.

## Coverage and interpretation

The imported archive contains 235,684 rows. This atlas retains 225,019 populated-place records across 246 country/territory codes. GeoNames describes cities500 as places with population greater than 500 or administrative seats down to fourth order. That is the source's inclusion rule, not a claim that current populations are known, that every city is included, or that all included places legally qualify as cities. The export also contains villages, localities and other settlements. Country coverage and naming quality vary.

Retained feature class is `P`, with this explicit allowlist: `PPL`, `PPLA`, `PPLA2`, `PPLA3`, `PPLA4`, `PPLA5`, `PPLC`, `PPLCD`, `PPLF`, `PPLG`, `PPLL`, `PPLR`, `STLMT`. These codes cover ordinary populated places, administrative/government seats, farm/religious villages, localities and settlements. Codes absent from this archive are permitted by the importer for future snapshots when their meaning meets that rule.

Removed: 10,542 `PPLX` neighborhood/section rows; 27 `PPLH` historical places; 41 `PPLQ` abandoned places; 9 `PPLW` destroyed places; 45 `PPLS` collective populated-place records; and 1 `PPLCH` historical-capital record. The last category describes a former political role and does not prove a place is uninhabited; this conservative filter can therefore omit an inhabited place. It is explicitly excluded rather than silently reclassified.

No population estimates are emitted or displayed. Coordinates are GeoNames point coordinates, not boundaries, entrances, routes, or travel instructions. `modified` is the source record modification date, not an independent factual verification date. Dataset entries provide atlas previews; an editorial guide is available only where `guideId` is present. GeoNames provides data without warranties of accuracy, timeliness or completeness.

## Output contract

- `catalog.json`: version, source, source URL, license URL, retrieval date, coverage text, total, country summaries, and 43 featured records with reviewed links to existing city guides.
- `countries/XX.json`: `{code,name,continent,count,places}`. Each place has `id,name,asciiName,aliases,countryCode,country,continent,admin,lat,lon,timezone,modified`, plus optional `guideId`. IDs are string GeoNames IDs. Place and administrative names preserve source Unicode. Empty `admin` means no display name is available.
- `search.json`: compact `{version,fields,total,places}`. Tuples follow `fields`: `id,name,asciiName,aliases,countryCode,admin,guideId`. A missing final item means no guide. Search tuples retain **all** filtered, normalized unique source aliases, with no count cap, so native/local names such as Firenze remain searchable. Derive country and continent from the catalog. Search case/diacritic folding belongs in the consumer and should not replace the original display name.
- `search.json.gz`: deterministic gzip copy of the full search index. It requires decompression before JSON parsing.
- `search/00.json` to `search/63.json` and `search-manifest.json`: optional bounded asset shards, partitioned by integer GeoNames ID modulo 64. Each shard has version, fields and places. They contain the same records as the full search index; do not fetch every shard in browsers on initial render.
- `guide-map.json`: explicit IDs, country labels, matched existing names, existing guide map-bounds center, source coordinates and distance checks.
- `provenance.json`: source and generated-file SHA-256 hashes, byte sizes, import counts, feature-code counts, validation results and unresolved administrative labels.

Country and featured display records retain at most 16 aliases. Search tuples retain every filtered, normalized unique source alias without a count cap. Both pipelines trim surrounding whitespace, exclude obvious URLs and entries over 200 characters, deduplicate with Unicode NFKC plus case/whitespace normalization, and exclude the main display name. Display aliases prioritize a differing ASCII name and source aliases matching existing guide names; remaining display aliases favor script diversity, then source order. Search aliases preserve source order after a differing ASCII name. The consumer must match against all search aliases before capping aliases in any response. Aliases can be historical names or transliterations, not necessarily current official names. No new alias is invented.

Country and continent labels follow GeoNames, including `HK / Hong Kong` and `NL / The Netherlands`. These geographical groupings are source metadata rather than an assertion about sovereignty. GeoNames IDs, names and coordinates control guide mapping; same-name matches alone are never sufficient. All 43 existing city guides were matched. London uses `2643743` (London), not `2643741` (City of London). The Antarctica editorial destination is a region and intentionally has no populated-place link.

## Validation and regeneration

Every retained record has a unique numeric GeoNames ID, nonempty name, finite and valid WGS84 coordinates, known country reference, source-listed timezone and ISO modification date. All guide mappings pass country, name/alias and distance checks within 25 km of their existing guide bounds center. The administrative table has 36 unresolved first-order labels across 16 codes; these remain empty, and their codes/counts are reported in provenance. Empty/00 admin codes can also legitimately lack a display name. The importer does not guess replacements.

Run the reusable importer with Python 3 and the existing app metadata:

```sh
python3 import-atlas.py --source /tmp/atherverse-atlas-source \
  --output ./atlas --guide-directory ./app/generated/directory.json \
  --map-bounds ./app/map-bounds.json --retrieved 2026-09-07
```

Add `--download` to fetch a fresh public snapshot using curl and normal certificate checks. Inspect changed counts, exclusions, labels and guide mappings before replacing a published snapshot. Do not present these records as independently researched guides.

## Search alias verification

The full index was independently compared with every retained source row after filtering: all 971,030 normalized unique aliases are retained in search, with at most 263 aliases for one record. Exact/native name checks pass for Firenze → Florence (3176959), Zurich → Zürich (2657896), München → Munich (2867714), and Москва → Moscow (524901), both globally and with country filters. Country/catalog display files remain byte-for-byte unchanged from the 16-alias display build.

A local Node 24 run using the app’s actual normalization and search functions parsed and prepared the full index in approximately 1.10 seconds. Retained index heap increased by approximately 212 MiB; measured process RSS was approximately 623 MiB after preparation, including runtime and test dependencies. The four global test queries took approximately 8–18 ms after preparation. These are local measurements, not hosted latency guarantees; reuse the prepared index within a process and do not rebuild it per request. Match every indexed alias before limiting display aliases in API results. Detailed measurements are in `search-validation.json`.

## Published Atherverse layout

Preparation moves the 43 mapped full-guide records into server-only `guides.json` and uses 18 additional cities as featured atlas previews. Country files and the all-alias search index are stored as gzip snapshots outside the public directory. Only bounded search responses reach the browser. The exact deployed checksums are in `atlas-deployed-data.json`; upstream output hashes in `atlas-provenance.json` describe the importer output before deployment preparation.

The world locator uses Natural Earth 1:110 million land geometry, projected to 720×360 equirectangular coordinates. All 5,143 source vertices are preserved with 0.1-pixel rounding, in 128 subpaths with even-odd fill. Natural Earth data is public domain: https://www.naturalearthdata.com/about/terms-of-use/ . Source: https://github.com/nvkelso/natural-earth-vector/blob/master/geojson/ne_110m_land.geojson . The dot is an approximate GeoNames point, not a route, boundary or entrance.