nazariitsubera/country-aliases

ISO 3166-1 alpha-2 lookup for thousands of dirty country spellings, plus a PHP helper.

v1.0.0 2025-11-21 16:04 UTC

Requires

• php: >=7.4

MIT

README

This bundle packages the country alias lookup generated from the GeoNames datasets plus a thin PHP wrapper you can ship as a Composer package.

Structure

• data/country_aliases.json – Map {normalized_name: "ISO2"} for every unambiguous alias.
• data/country_aliases.csv – Two-column CSV (normalized_name,iso2) mirroring the JSON.
• data/country_aliases_ambiguous.json – Optional file with aliases that match more than one ISO2 code so you can handle them manually.
• src/ – PHP wrapper exposing a simple runtime API.

Regenerate the data by rerunning the build_country_aliases.py script you used earlier (or fetch the latest GeoNames exports, then rebuild using the same normalization logic). The script should still trim, uppercase, strip accents, and ignore alternate names that look like URLs (strings starting with HTTP/HTTPS) so the output only contains actual country spellings. Once regenerated, drop the new files back into data/.

The JSON file is best suited for programmatic use (load once, look up millions of rows in-memory); the CSV is easier to scan manually.

PHP wrapper

The CountryAliasResolver class in src/ loads data/country_aliases.json and exposes a lookup($value) method that returns the ISO2 code (or null when no match exists). Example:

use CountryAliases\CountryAliasResolver;

$resolver = new CountryAliasResolver(__DIR__ . '/data/country_aliases.json');

var_dump($resolver->lookup('United States of America')); // "US"
var_dump($resolver->lookup('   republic   of   ireland  ')); // "IE"

Drop this repository into a Composer package (e.g., country-aliases/country-aliases), configure PSR-4 autoloading for src/, and you can normalize millions of dirty country strings with a single method call.