stefangabos/world_countries for ISO country and subdivision data

Why world_countries separates countries from territories

world_countries addresses a recurring data-import problem: developers need stable identifiers for countries, territories, and areas of geographical interest without assembling their own ISO 3166 tables. Each country record includes the ISO 3166-1 numeric code, official short name, alpha-2 code, and alpha-3 code. The alpha codes are provided in lowercase, even though the README says ISO 3166-1 alpha codes are uppercase, so consumers must preserve that documented casing or normalize it deliberately.

The repository draws an important boundary through its file names. Files under `data/countries` named like `world.*` contain 249 entries with officially assigned ISO 3166-1 codes. Files named like `countries.*` contain 193 United Nations member states. The README describes 206 sovereign states and explains that 11 are absent from the `countries` list because their sovereignty is disputed. That makes the naming practical but potentially confusing: a file called `countries` does not represent every place a product might reasonably classify as a country.

The intended users are developers building country selectors, import pipelines, address-related databases, localization systems, and administrative interfaces. A system that needs territories and geopolitical areas should examine `world`; a product whose definition of country follows UN membership has a reason to examine `countries`. This distinction should be decided before importing records, because changing it later can affect validation rules, labels, database constraints, and downstream analytics.

How the country and subdivision datasets are organized

The country files are organized by language beneath `data/countries`, with language folder names based on ISO 639-1. The README lists 37 languages, including Simplified and Traditional Chinese, English, French, German, Japanese, Korean, Spanish, and others. The same identifiers can therefore be paired with localized names without changing the underlying alpha-2, alpha-3, or numeric codes.

Subdivision data has a separate location under `data/subdivisions`. It represents ISO 3166-2 codes for principal subdivisions such as provinces and states. Each record contains the country code, complete subdivision code, subdivision name, English subdivision name where available, subdivision type, and parent for administrative hierarchies. A complete code combines the country alpha-2 code with a subdivision suffix, as illustrated by Texas as `US-TX`.

The English subdivision field is not guaranteed to be complete. The README also says it may be omitted when the original ISO 3166-2 name is already in English. That is sensible for avoiding duplicate values, but it means a missing English field does not always indicate missing localization data. Consumers requiring a non-empty English column should define an explicit fallback policy rather than treating every blank as an error.

The data is supplied in CSV, JSON, PHP, MySQL, MSSQL, and XML formats. Based on the repository layout, this is a repository of prebuilt reference files rather than a documented runtime validation library. The README does not describe a country lookup API, normalization service, or runtime updater.

Installing world_countries and locating the first dataset

The README does not provide installation commands for either Composer or npm, and it does not document a first programmatic API call. The repository includes `composer.json` and `package.json`, while the README exposes the `world_countries_lists` package through npm links. However, neither section supplies a confirmed installation command, so this article does not invent one.

A first practical use begins by selecting the correct source file. Clone or download the repository through the project source, then navigate to `data/countries` and choose a language folder. Decide whether the application needs a `world` file or a `countries` file, and select the format that matches the import process. The documented formats are CSV, JSON, PHP, MySQL, MSSQL, and XML. The project homepage is `http://stefangabos.github.io/world_countries/`, while the repository metadata identifies the GitHub repository as the source.

For an initial data-quality check, inspect the file header against the fields documented by the README: numeric country code, localized or official short name, alpha-2 code, and alpha-3 code. For subdivision data, inspect the CSV structure documented in the README:

US,US-AL,Alabama,,state,
US,US-AK,Alaska,,state,
US,US-AZ,Arizona,,state,
US,US-AR,Arkansas,,state,
US,US-CA,California,,state,
US,US-CO,Colorado,,state,

This excerpt confirms the six documented columns, but the README does not print a header row. An importer should therefore derive and verify column positions from the actual file rather than assuming that these six sample lines are the entire schema declaration.

CSV, JSON, PHP, and SQL import trade-offs

The range of formats is the repository's main engineering convenience. CSV is a practical choice for database loading and quick inspection, although values containing punctuation or commas still need a parser that follows the actual file syntax. JSON is suitable when an application already loads structured documents. PHP can serve PHP applications that prefer native language files. MySQL and MSSQL dumps can reduce manual schema creation, but the README does not document their table definitions, indexes, constraints, or transaction behavior.

XML is available for systems that already exchange XML documents. The project does not document an XSD, validation command, or canonicalization rule. If conformance validation matters, application owners must verify the generated files and schema expectations separately.

Format availability does not mean every record has the same linguistic completeness. Country names are localized in each selected language. Subdivision English names may be absent when unnecessary, and parent information exists specifically for countries with multiple administrative levels. Import code should therefore allow null or blank values where the source format represents them as empty, especially in subdivision CSV data.

This dataset is also a poor fit where live political-status changes must be inferred automatically. It represents ISO-coded places and administrative subdivisions, but the repository is not documented as a geopolitical monitoring service. Applications that need current sanctions, residency rules, tax jurisdictions, or recognized passport countries need separate authoritative sources.

Flag assets and the component licensing mismatch

National flags are bundled beneath `data/flags/default/`. The README identifies PNG sizes of 16x16, 24x24, 32x32, 48x48, 64x64, and 128x128, with filenames based on the ISO 3166-1 alpha-2 code. That naming convention makes pairing a flag with a country record direct, provided the importer accounts for the repository's lowercase alpha-code convention.

The licensing information needs careful handling. The README says the country and subdivision data is sourced from Wikipedia ISO 3166 pages and licensed under Creative Commons Attribution-ShareAlike 4.0 International. The repository description also names `CC-BY-SA-4.0`. In contrast, `package.json` declares `LGPL-3.0-or-later` for the `world_countries_lists` package. The flag provenance is described separately, with the default images said to have been available from the now defunct `icondrawer.com`, but the README does not give the flags a separate license statement.

This is not merely a metadata detail when package files, generated distributions, and image assets are combined. The stated licenses do not clearly cover every component under one documented grant. Engineers should inspect `LICENSE.txt`, `LICENSE.md`, `package.json`, and any package-specific attribution files before redistribution. This article does not provide legal advice, and it does not assume that the data license automatically applies to every flag image.

Release history, maintenance signals, and upgrade work

The repository is not archived. Its last push was on 2026-09-19, and the release list includes version 3.3.0 dated 2025-11-05, version 3.2.0 dated 2025-07-01, and version 3.1.0 dated 2025-05-31. These facts show recent repository activity and recent published versions, although the README does not describe a semantic-version compatibility policy.

The package manifest identifies version `3.3.0`, sets `main` to `index.js`, and supplies `types.d.ts`. The repository listing does not include an `index.js` file, and the README does not explain a supported JavaScript API. Engineers should not assume that installing the npm package exposes country lookup methods based only on the `main` field. The documented path for obtaining the data is the files under `data`.

An upgrade can affect translated names, added or retired ISO codes, subdivision records, file layout, and generated database imports. The repository includes `CHANGELOG.md`, but its contents are not documented in the README excerpt, so the concrete changes between the listed versions cannot be described. Before replacing imported data, compare record counts, alpha codes, numeric codes, subdivision hierarchies, nullable English names, and file schemas. A data update can therefore create application maintenance work even when no application code changes.

Why an official ISO feed may be a different choice

The practical alternative is to obtain ISO 3166 data directly from the International Organization for Standardization rather than importing this repository's prepared files. The README links the ISO 3166 country-code pages and identifies ISO as the publisher and maintainer of the standard. A direct ISO source would place responsibility for obtaining and interpreting the authoritative standard data on the adopter, but it can reduce questions about transformations performed by an intermediary package.

world_countries offers a different approach: it prepares country and subdivision data for direct consumption in common application and database formats, adds 37 localized language editions, and includes flag assets named by alpha-2 code. That convenience also creates an update boundary. Users consume the repository's packaged representation rather than querying ISO directly.

Another alternative for country selection is a locale or internationalization library, but only when that library actually carries ISO country identifiers and the exact translations or formats required. The README does not describe any specific competing library, so a stronger comparison would require separate verified documentation. Within the confirmed scope, the meaningful choice is prepared multi-format files versus maintaining a direct ISO data acquisition and import path.

Editorial conclusion

Adopt this repository when an application needs locally packaged ISO 3166-1 and ISO 3166-2 files in a specific format or language. Do not treat its 193-country view as a complete sovereignty model, and do not assume a single license covers every packaged component. Before integration, inspect the relevant data files, confirm the required country scope, and resolve the stated difference between CC-BY-SA-4.0 for the data and LGPL-3.0-or-later in package.json.

Frequently asked questions

Official sources

1. License: CC-BY-SA-4.0
2. Project website
3. README
4. Releases
5. stefangabos/world_countries on GitHub