$ show dr5hn/countries-states-cities-database
This repository is a curated, comprehensive geographic database of countries, states, cities, and postcodes, with a strong emphasis on ISO 3166 compliance and data quality. It is primarily a data_research project, though it includes supporting application code (export pipelines, validation tools, CI/CD) that enables multi-format distribution (JSON, CSV, SQL, Parquet, etc.). The raw data lives in the `contributions/` directory as JSON files, which are the source of truth. A rich ecosystem of Python, PHP, and Node.js scripts handles ingestion from community and official sources, idempotent correction, enrichment (timezones, translations), and export to 12+ formats. The repository is actively maintained by a community of contributors and automated bots, with rigorous PR validation (schema, coordinates, duplicates, cross-references) and extensive fix documentation. It answers questions like 'What are the administrative divisions of a country?' and 'What postcodes exist for a given locality?' and is used as a reference data source for applications worldwide.
The LLM identified 5 files worth highlighting for reuse:
Exemplary postcode import script that demonstrates the project's standard pattern: fetch from authoritative source, parse, resolve state foreign keys via name/ISO2 lookup, deduplicate by (code, locality_name), merge idempotently with existing file, and write JSON. Supports --dry-run for preview. The structure is reusable across any hierarchical geographic data import.
A modular Node.js validation script that checks JSON files against a defined schema for required fields, data types, and constraints. Used in GitHub Actions for PR validation. Reusable in any project that needs automated schema enforcement on JSON data files.
Idempotent fix script that corrects administrative division types for US settlements. Demonstrates a robust pattern: load data, validate preconditions, compute changes, log each modification, and only write on real run (not dry-run). Reusable for any data correction workflow that requires safe, auditable transformations.
A clean conversion script that transforms JSON geographic data into Parquet format using PyArrow. Supports optional global IDs and enhanced mode. Reusable as a template for converting any structured JSON dataset to Parquet for analytical use.
Timezone enrichment script that uses the timezonefinder library to assign IANA timezone identifiers to cities based on coordinates. Includes logic for multi-timezone countries (predefined lists) and manual overrides. Reusable for any geographic dataset that needs timezone assignment from lat/lon.