{"id":13488226,"url":"https://github.com/stefangabos/world_countries","last_synced_at":"2025-05-13T19:02:59.354Z","repository":{"id":37561670,"uuid":"50539767","full_name":"stefangabos/world_countries","owner":"stefangabos","description":"Constantly updated lists of world countries and their associated alpha-2, alpha-3 and numeric country codes as defined by the ISO 3166 standard, available in CSV, JSON , PHP, SQL and XML formats, in multiple languages and with national flags included; also available are the ISO 3166-2 codes of provinces/ states associated with the countries","archived":false,"fork":false,"pushed_at":"2025-02-06T09:06:18.000Z","size":13083,"stargazers_count":1443,"open_issues_count":14,"forks_count":382,"subscribers_count":49,"default_branch":"master","last_synced_at":"2025-04-27T23:58:43.574Z","etag":null,"topics":["countries","csv","flags","iso-3166-1","json","multilingual","mysql","national-flags","sql","xml"],"latest_commit_sha":null,"homepage":"http://stefangabos.github.io/world_countries/","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stefangabos.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":"FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"stefangabos"}},"created_at":"2016-01-27T21:41:04.000Z","updated_at":"2025-04-25T07:10:07.000Z","dependencies_parsed_at":"2023-02-02T07:16:28.248Z","dependency_job_id":"af0dc059-f805-427c-bd26-f18938671af2","html_url":"https://github.com/stefangabos/world_countries","commit_stats":{"total_commits":354,"total_committers":7,"mean_commits":50.57142857142857,"dds":"0.019774011299435013","last_synced_commit":"c07b7b2cda57ff4d5b736cdc4fb4a0bef10e82d0"},"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefangabos%2Fworld_countries","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefangabos%2Fworld_countries/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefangabos%2Fworld_countries/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefangabos%2Fworld_countries/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stefangabos","download_url":"https://codeload.github.com/stefangabos/world_countries/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254010792,"owners_count":21998993,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["countries","csv","flags","iso-3166-1","json","multilingual","mysql","national-flags","sql","xml"],"created_at":"2024-07-31T18:01:11.817Z","updated_at":"2025-05-13T19:02:59.294Z","avatar_url":"https://github.com/stefangabos.png","language":"PHP","funding_links":["https://github.com/sponsors/stefangabos","https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick\u0026hosted_button_id=BPBPYP293BRLC"],"categories":["PHP"],"sub_categories":[],"readme":"\u003cimg src=\"https://raw.githubusercontent.com/stefangabos/zebrajs/master/docs/images/logo.png\" alt=\"zebrajs\" align=\"right\"\u003e\n\n# World countries \u0026nbsp;[![Tweet](https://img.shields.io/twitter/url/http/shields.io.svg?style=social)](https://twitter.com/intent/tweet?text=Constantly+updated+lists+of+world+countries+with+associated+ISO+3166-1+alpha-2%2C+alpha-3+and+numeric+codes%2C+available+in+multiple+formats+and+languages%2C+with+national+flags+included\u0026url=https://github.com/stefangabos/world_countries\u0026via=stefangabos)\n\n*available in multiple languages, in CSV, JSON, PHP, SQL and XML formats, with associated codes as defined by the ISO 3166 standard, and with national flags included; also available are the ISO 3166-2 codes used for identifying the principal subdivisions (e.g., provinces or states) of all countries coded in ISO 3166-1*\n\n[![npm](https://img.shields.io/npm/v/world_countries_lists.svg)](https://www.npmjs.com/package/world_countries_lists) [![Total](https://img.shields.io/npm/dt/world_countries_lists.svg)](https://www.npmjs.com/package/world_countries_lists) [![Monthly](https://img.shields.io/npm/dm/world_countries_lists.svg)](https://www.npmjs.com/package/world_countries_lists) [![JSDelivr](https://data.jsdelivr.com/v1/package/npm/world_countries_lists/badge?style=rounded)](https://www.jsdelivr.com/package/npm/world_countries_lists) [![License](https://img.shields.io/github/license/stefangabos/world_countries.svg)](https://github.com/stefangabos/world_countries/blob/master/LICENSE.md)\n\nConstantly updated lists of world countries, territories and areas of geographical interest, with associated *alpha-2*, *alpha-3* and *numeric codes* as defined by the *ISO 3166-1* standard, published and maintained by the [International Organization for Standardization](https://www.iso.org/iso-3166-country-codes.html), available in `CSV`, `JSON`, `PHP`, `SQL` and `XML` formats, in multiple languages and with national flags included. Also available are the ISO 3166-2 codes used for identifying the principal subdivisions (e.g., provinces or states) of all countries coded in ISO 3166-1.\n\nIn the language folders (inside `data/countries`) you will find files named in two different ways.\u003cbr\u003eHere's what you will find in each of them:\n\n|File names | Content |\n|:---:|:---\n| \u003ca name=\"world\"\u003e\u003c/a\u003e*world.** | Files named like this contain all the **249** countries, territories, and areas of geographical interest that have an officially assigned *ISO 3166-1* code.\n| \u003ca name=\"countries\"\u003e\u003c/a\u003e*countries.** | Files named like this contain the **193** sovereign states (commonly referred to as *countries*) that are members of the [United\u0026nbsp;Nations (UN)](https://www.un.org/about-us/member-states) .\n\n\u003e Note that there are 206 sovereign states in the world, the 11 states that are missing from the *countries* list being the ones having their sovereignty disputed. See the list of [sovereign states](https://en.wikipedia.org/wiki/List_of_sovereign_states) with information on their status and recognition of their sovereignty.\n\nThe files contain:\n\n- the **ISO 3166-1 numeric** country codes\n- the **ISO 3166** official short names in *English*\u003csmall\u003e\u003csup\u003e[1](#footnote)\u003c/sup\u003e\u003c/small\u003e\n- the **ISO 3166-1 alpha-2** two-letter country codes\u003csmall\u003e\u003csup\u003e[2](#footnote2)\u003c/sup\u003e\u003c/small\u003e\n- the **ISO 3166-1 alpha-3** three-letter country codes\u003csmall\u003e\u003csup\u003e[2](#footnote2)\u003c/sup\u003e\u003c/small\u003e\n\n\u003csmall\u003e\u003ca name=\"footnote\"\u003e\u003csup\u003e1\u003c/sup\u003e\u003c/a\u003e for other languages the country names are in that particular language\u003c/small\u003e\n\u003cbr\u003e\u003csmall\u003e\u003ca name=\"footnote2\"\u003e\u003csup\u003e2\u003c/sup\u003e\u003c/a\u003e ISO 3166-1 alpha codes are uppercase but this library provides them in lowercase\u003c/small\u003e\n\nThe lists are currently available in **36 languages**:\n\n- Arabic\n- Armenian\n- Basque\n- Bulgarian\n- Chinese (Simplified)\n- Chinese (Traditional)\n- Croatian\n- Czech\n- Danish\n- Dutch\n- English\n- Esperanto\n- Estonian\n- Farsi\n- Finnish\n- French\n- German\n- Greek\n- Hungarian\n- Italian\n- Japanese\n- Korean\n- Lithuanian\n- Norwegian\n- Polish\n- Portuguese\n- Romanian\n- Russian\n- Serbian\n- Slovak\n- Slovenian\n- Spanish\n- Swedish\n- Thai\n- Turkish\n- Ukrainian\n\n\u003e The language folders are named based on the [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) standard.\n\n## ISO 3166-2 codes\n\nThe project also tries to be a comprehensive and up-to-date source for **ISO 3166-2** which defines codes for identifying the principal subdivisions (e.g., provinces or states) of all countries coded in ISO 3166-1.\n\nThe purpose of ISO 3166-2 is to establish an international standard of short and unique alphanumeric codes to represent the relevant administrative divisions and dependent territories of all countries in a more convenient and less ambiguous form than their full names. Each complete ISO 3166-2 code consists of two parts, separated by a hyphen:\n\n`US-TX` for Texas, USA\n\nThe first part is the ISO 3166-1 alpha-2 code of the country;\nThe second part is a string of up to three alphanumeric characters, which is usually obtained from national sources and stems from coding systems already in use in the country concerned, but may also be developed by the ISO itself.\nEach complete ISO 3166-2 code can then be used to uniquely identify a country subdivision in a global context.\n\nThe list is available in `CSV`, `JSON`, `PHP`, `SQL` and `XML` formats in the `data/subdivisions` folder and the CSV one looks like this:\n\n```csv\nUS,US-AL,Alabama\nUS,US-AK,Alaska\nUS,US-AZ,Arizona\nUS,US-AR,Arkansas\nUS,US-CA,California\nUS,US-CO,Colorado\n```\n\nThe starting point of this list was the ISO 3166-2 Subdivision Code list provided by [IP2Location](https://www.ip2location.com/free/iso3166-2) but this one will be maintained by the community.\n\n## 🎂 Support the development of this project\n\nYour support means a lot and it keeps me motivated to keep working on open source projects.\u003cbr\u003e\nIf you like this project please ⭐ it by clicking on the star button at the top of the page.\u003cbr\u003e\nIf you are feeling generous, you can buy me a coffee by donating through PayPal, or you can become a sponsor.\u003cbr\u003e\nEither way - **Thank you!** 🎉\n\n[\u003cimg src=\"https://img.shields.io/github/stars/stefangabos/world_countries?color=green\u0026label=star%20it%20on%20GitHub\" width=\"132\" height=\"20\" alt=\"Star it on GitHub\"\u003e](https://github.com/stefangabos/world_countries) [![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick\u0026hosted_button_id=BPBPYP293BRLC) [\u003cimg src=\"https://img.shields.io/badge/-Sponsor-fafbfc?logo=GitHub%20Sponsors\"\u003e](https://github.com/sponsors/stefangabos)\n\n## Installation\n\nThe lists are available as a [npm package](https://www.npmjs.com/package/world_countries_lists). To install it use:\n\n```bash\n# the \"--save\" argument adds the plugin as a dependency in packages.json\nnpm install world_countries_lists --save\n```\n\nYou can install the lists via [Composer](https://packagist.org/packages/stefangabos/world_countries)\n```shell\ncomposer require stefangabos/world_countries\n```\n\nAlternatively, you can load data from [JSDelivr CDN](https://www.jsdelivr.com/package/npm/world_countries_lists) like this:\n```html\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/world_countries_lists@latest/data/countries/en/countries.json\"\u003e\u003c/script\u003e\n```\n\nOr\n\u003e [download a customized build](http://stefangabos.github.io/world_countries/).\n\n## Data formats\n\n### SQL\n\nExcerpt from the `data/countries/en/countries.sql` file:\n\n```sql\n(250,'fr','fra','France'),\n(266,'ga','gab','Gabon'),\n(270,'gm','gmb','Gambia'),\n(268,'ge','geo','Georgia'),\n(276,'de','deu','Germany'),\n(288,'gh','gha','Ghana'),\n(300,'gr','grc','Greece'),\n(308,'gd','grd','Grenada'),\n```\n\n### CSV\n\nExcerpt from the `data/countries/en/countries.csv` file:\n\n```csv\n250,fr,fra,France\n266,ga,gab,Gabon\n270,gm,gmb,Gambia\n268,ge,geo,Georgia\n276,de,deu,Germany\n288,gh,gha,Ghana\n300,gr,grc,Greece\n308,gd,grd,Grenada\n```\n\n### JSON\n\nExcerpt from the `data/countries/en/countries.json` file:\n\n```json\n{\"id\":250,\"alpha2\":\"fr\",\"alpha3\":\"fra\",\"name\":\"France\"},\n{\"id\":266,\"alpha2\":\"ga\",\"alpha3\":\"gab\",\"name\":\"Gabon\"},\n{\"id\":270,\"alpha2\":\"gm\",\"alpha3\":\"gmb\",\"name\":\"Gambia\"},\n{\"id\":268,\"alpha2\":\"ge\",\"alpha3\":\"geo\",\"name\":\"Georgia\"},\n{\"id\":276,\"alpha2\":\"de\",\"alpha3\":\"deu\",\"name\":\"Germany\"},\n{\"id\":288,\"alpha2\":\"gh\",\"alpha3\":\"gha\",\"name\":\"Ghana\"},\n{\"id\":300,\"alpha2\":\"gr\",\"alpha3\":\"grc\",\"name\":\"Greece\"},\n{\"id\":308,\"alpha2\":\"gd\",\"alpha3\":\"grd\",\"name\":\"Grenada\"},\n```\n\nHere's a little helper function for searching for a specific country's data\n\n\u003e The helper function assumes that the JSON with the countries data is associated with a variable named `countries` which is in the same scope as the function\n\n\u003e The helper function is to be used with the *non-combined* data sets.\u003cbr\u003eFor the *combined* data sets you can write the function yourself.\n\n```js\n//  returns an object with the sought country's data if the search yields a result\n//  returns undefined if no results could be found or if argument is incorrect\nfunction search_country(query) {\n\n    // if argument is not valid return false\n    if (undefined === query.id \u0026\u0026 undefined === query.alpha2 \u0026\u0026 undefined === query.alpha3) return undefined;\n\n        // iterate over the array of countries\n\treturn countries.filter(function(country) {\n\n        // return country's data if\n        return (\n            // we are searching by ID and we have a match\n            (undefined !== query.id \u0026\u0026 parseInt(country.id, 10) === parseInt(query.id, 10))\n            // or we are searching by alpha2 and we have a match\n            || (undefined !== query.alpha2 \u0026\u0026 country.alpha2 === query.alpha2.toLowerCase())\n            // or we are searching by alpha3 and we have a match\n            || (undefined !== query.alpha3 \u0026\u0026 country.alpha3 === query.alpha3.toLowerCase())\n        )\n\n    // since \"filter\" returns an array we use pop to get just the data object\n    }).pop()\n\n}\n```\n\nUsage\n\n```js\nsearch_country({id: 250})\nsearch_country({alpha2: 'fr'})\nsearch_country({alpha3: 'fra'})\n```\n\n### TypeScript\n\nTypings are available ([source](types.d.ts)):\n\n```ts\nimport { Country, LanguageCode, TranslatedCountry } from 'world_countries_lists'\n```\n\n### PHP\n\nExcerpt from the `data/countries/en/countries.php` file:\n\n```php\n250 =\u003e array('id' =\u003e 250, 'alpha2' =\u003e 'fr', 'alpha3' =\u003e 'fra', 'name' =\u003e 'France'),\n266 =\u003e array('id' =\u003e 266, 'alpha2' =\u003e 'ga', 'alpha3' =\u003e 'gab', 'name' =\u003e 'Gabon'),\n270 =\u003e array('id' =\u003e 270, 'alpha2' =\u003e 'gm', 'alpha3' =\u003e 'gmb', 'name' =\u003e 'Gambia'),\n```\nHere's a little helper function for searching for a specific country's data\n\n\u003e The helper function is to be used with the *non-combined* data sets.\u003cbr\u003eFor the *combined* data sets you can write the function yourself.\n\n```php\n//  this function assumes that you have done this:\n$countries = require 'path/to/countries.php';\n\n//  returns an array with the sought country's data if the search yields a result\n//  returns false if no results could be found or if argument is incorrect\nfunction search_country($query) {\n\n    // make the countries available in the function\n    global $countries;\n\n    // if argument is not valid return false\n    if (!isset($query['id']) \u0026\u0026 !isset($query['alpha2']) \u0026\u0026 !isset($query['alpha3'])) return false;\n\n    // iterate over the array of countries\n    $result = array_filter($countries, function($country) use ($query) {\n\n        // return country's data if\n        return (\n            // we are searching by ID and we have a match\n            (isset($query['id']) \u0026\u0026 $country['id'] == $query['id'])\n            // or we are searching by alpha2 and we have a match\n            || (isset($query['alpha2']) \u0026\u0026 $country['alpha2'] == strtolower($query['alpha2']))\n            // or we are searching by alpha3 and we have a match\n            || (isset($query['alpha3']) \u0026\u0026 $country['alpha3'] == strtolower($query['alpha3']))\n        );\n\n    });\n\n    // since \"array_filter\" returns an array we use pop to get just the data object\n    // we return false if a result was not found\n    return empty($result) ? false : array_pop($result);\n\n}\n```\nUsage\n\n```php\nsearch_country(array('id' =\u003e 250));\nsearch_country(array('alpha2' =\u003e 'fr'));\nsearch_country(array('alpha3' =\u003e 'fra'));\n```\n\n### XML\n\nExcerpt from the `data/countries/en/countries.xml` file:\n\n```xml\n\u003ccountry id=\"250\" alpha2=\"fr\" alpha3=\"fra\" name=\"France\"/\u003e\n\u003ccountry id=\"266\" alpha2=\"ga\" alpha3=\"gab\" name=\"Gabon\"/\u003e\n\u003ccountry id=\"270\" alpha2=\"gm\" alpha3=\"gmb\" name=\"Gambia\"/\u003e\n\u003ccountry id=\"268\" alpha2=\"ge\" alpha3=\"geo\" name=\"Georgia\"/\u003e\n\u003ccountry id=\"276\" alpha2=\"de\" alpha3=\"deu\" name=\"Germany\"/\u003e\n\u003ccountry id=\"288\" alpha2=\"gh\" alpha3=\"gha\" name=\"Ghana\"/\u003e\n\u003ccountry id=\"300\" alpha2=\"gr\" alpha3=\"grc\" name=\"Greece\"/\u003e\n\u003ccountry id=\"308\" alpha2=\"gd\" alpha3=\"grd\" name=\"Grenada\"/\u003e\n```\n\n## Flags\n\nThe package also contains the national flags of each country as a 16x16, 24x24, 32x32, 48x48, 64x64 and 128x128 PNG images. The image files are named using the ISO 3166-1-alpha-2 code of the country they represent, for easily pairing flags with countries.\n\n\u003e Flag images are also available as single `JSON` files, one for each of the available sizes, containing all flag images as `data-uri`\n\n## Data sources\n\nCountry names in all languages are taken from [Wikipedia](https://en.wikipedia.org/wiki/ISO_3166-1).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstefangabos%2Fworld_countries","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstefangabos%2Fworld_countries","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstefangabos%2Fworld_countries/lists"}