by mledoze

mledoze /countries

World countries in JSON, CSV, XML and Yaml. Any help is welcome!

5.0K Stars 1.1K Forks Last release: 6 months ago (v4.0.0) Other 658 Commits 23 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

World countries in JSON, CSV, XML and YAML.

Latest Stable Version Latest Stable Version License PHP from Packagist

Build Status Scrutinizer Code Quality Downloads

Countries data

This repository contains a list of world countries, as defined by ISO Standard 3166-1, in JSON, CSV, XML and YAML. Warning: not all entities in this project are independent countries; refer to the

property to know if the country is considered a sovereign state.

Each line contains the country:

  • name
    • common
      - common name in english
    • official
      - official name in english
    • native
      - list of all native names
      • key: three-letter ISO 639-3 language code
      • value: name object
        • key: official - official name translation
        • key: common - common name translation
  • country code top-level domain (
  • code ISO 3166-1 alpha-2 (
  • code ISO 3166-1 numeric (
  • code ISO 3166-1 alpha-3 (
  • code International Olympic Committee (
  • ISO 3166-1 independence status (
    ) (denotes the country is considered a sovereign state)
  • ISO 3166-1 assignment status (
  • UN Member status (
  • currencies
    - list of all currencies
    • key: ISO 4217 currency code
    • value: currency object
      • key:
        name of the currency
      • key:
        symbol of the currency
  • International Direct Dialing info (
    • root
      - the root geographical code prefix. e.g. +6 for New Zealand, +4 for UK.
    • suffixes
      - list of all suffixes assigned to this country. 4 for NZ, 809, 829, and 849 for Dominican Republic.
  • capital city(ies) (
  • alternative spellings (
  • region
  • subregion
  • list of official languages (
    • key: three-letter ISO 639-3 language code
    • value: name of the language in english
  • list of name translations (
    • key: three-letter ISO 639-3 language code
    • value: name object
      • key: official - official name translation
      • key: common - common name translation
  • latitude and longitude (
  • demonyms
    - name of residents, translated & genderized
    • key: three-letter ISO 639-3 language code
    • value: genderized demonym object
      • key:
        (female) or
      • value: genderized demonym translation
  • landlocked status (
  • land borders (
  • land area in km² (
  • Emoji flag (
  • calling codes (

Additional data

The data folder contains additional data such as the countries GeoJSON outlines and flags in SVG format.


    "name": {
        "common": "Austria",
        "official": "Republic of Austria",
        "native": {
            "bar": {
                "official": "Republik Österreich",
                "common": "Österreich"
    "tld": [".at"],
    "cca2": "AT",
    "ccn3": "040",
    "cca3": "AUT",
    "cioc": "AUT",
    "independent": true,
    "status": "officially-assigned",
    "currency": ["EUR"],
    "idd": {
        "root": "+4",
        "suffixes": ["3"]
    "capital": ["Vienna"],
    "altSpellings": ["AT", "Osterreich", "Oesterreich"],
    "region": "Europe",
    "subregion": "Western Europe",
    "languages": {
        "bar": "Austro-Bavarian German"
    "translations": {
        "cym": {"official": "Republic of Austria", "common": "Awstria"},
        "deu": {"official": "Republik Österreich", "common": "Österreich"},
        "fra": {"official": "République d'Autriche", "common": "Autriche"},
        "hrv": {"official": "Republika Austrija", "common": "Austrija"},
        "ita": {"official": "Repubblica d'Austria", "common": "Austria"},
        "jpn": {"official": "オーストリア共和国", "common": "オーストリア"},
        "nld": {"official": "Republiek Oostenrijk", "common": "Oostenrijk"},
        "por": {"official": "República da Áustria", "common": "Áustria"},
        "rus": {"official": "Австрийская Республика", "common": "Австрия"},
        "spa": {"official": "República de Austria", "common": "Austria"}
    "latlng": [47.33333333, 13.33333333],
    "demonym": "Austrian",
    "demonyms": {
        "fra": {
            "f": "Autrichienne",
            "m": "Autrichien"
        "spa": {
            "f": "Austriaco",
            "m": "Austriaca"
    "landlocked": true,
    "borders": ["CZE", "DEU", "HUN", "ITA", "LIE", "SVK", "SVN", "CHE"],
    "area": 83871,
    "flag": "\ud83c\udde6\ud83c\uddf9"
GeoJSON and TopoJSON outlines

See an example for Germany: GeoJSON or TopoJSON.

"Afghanistan,Islamic Republic of Afghanistan,جمهوری اسلامی افغانستان,افغانستان,د افغانستان اسلامي جمهوریت,افغانستان,Owganystan Yslam Respublikasy,Owganystan";".af";"AF";"004";"AFG";"AFG";"AFN";"+9,3";"Kabul";"AF,Afġānistān";"Asia";"Southern Asia";"Dari,Pashto,Turkmen";"Islamic Republic of Afghanistan,Affganistan,Islamischen Republik Afghanistan,Afghanistan,Afganistanin islamilainen tasavalta,Afganistan,République islamique d'Afghanistan,Afghanistan,Islamska Republika Afganistan,Afganistan,Repubblica islamica dell'Afghanistan,Afghanistan,アフガニスタン·イスラム共和国,アフガニスタン,Islamitische Republiek Afghanistan,Afghanistan,República Islâmica do Afeganistão,Afeganistão,Исламская Республика Афганистан,Афганистан,República Islámica de Afganistán,Afganistán";"33,65";"Afghan";"1";"IRN,PAK,TKM,UZB,TJK,CHN";"652230"
"Angola,Republic of Angola,República de Angola,Angola";".ao";"AO";"024";"AGO";"ANG";"AOA";"+2,44";"Luanda";"AO,República de Angola,ʁɛpublika de an'ɡɔla";"Africa";"Middle Africa";"Portuguese";"Republic of Angola,Angola,Republik Angola,Angola,Angolan tasavalta,Angola,République d'Angola,Angola,Republika Angola,Angola,Repubblica dell'Angola,Angola,アンゴラ共和国,アンゴラ,Republiek Angola,Angola,República de Angola,Angola,Республика Ангола,Ангола,República de Angola,Angola";"-12.5,18.5";"Angolan";"";"COG,COD,ZMB,NAM";"1246700"
- { name: { common: Aruba, official: Aruba, native: { nld: { official: Aruba, common: Aruba }, pap: { official: Aruba, common: Aruba } } }, tld: [.aw], cca2: AW, ccn3: '533', cca3: ABW, cioc: ARU, currency: [AWG], idd: { root: '+2', suffixes: ['97'] }, capital: Oranjestad, altSpellings: [AW], region: Americas, subregion: Caribbean, languages: { nld: Dutch, pap: Papiamento }, translations: { deu: { official: Aruba, common: Aruba }, fin: { official: Aruba, common: Aruba }, fra: { official: Aruba, common: Aruba }, hrv: { official: Aruba, common: Aruba }, ita: { official: Aruba, common: Aruba }, jpn: { official: アルバ, common: アルバ }, nld: { official: Aruba, common: Aruba }, por: { official: Aruba, common: Aruba }, rus: { official: Аруба, common: Аруба }, spa: { official: Aruba, common: Aruba } }, latlng: [12.5, -69.96666666], demonym: Aruban, landlocked: false, borders: {  }, area: 180 }
- { name: { common: Afghanistan, official: 'Islamic Republic of Afghanistan', native: { prs: { official: 'جمهوری اسلامی افغانستان', common: افغانستان }, pus: { official: 'د افغانستان اسلامي جمهوریت', common: افغانستان }, tuk: { official: 'Owganystan Yslam Respublikasy', common: Owganystan } } }, tld: [.af], cca2: AF, ccn3: '004', cca3: AFG, cioc: AFG, currency: [AFN], idd: { root: '+9', suffixes: ['3'] }, capital: Kabul, altSpellings: [AF, Afġānistān], region: Asia, subregion: 'Southern Asia', languages: { prs: Dari, pus: Pashto, tuk: Turkmen }, translations: { cym: { official: 'Islamic Republic of Afghanistan', common: Affganistan }, deu: { official: 'Islamischen Republik Afghanistan', common: Afghanistan }, fin: { official: 'Afganistanin islamilainen tasavalta', common: Afganistan }, fra: { official: 'République islamique d''Afghanistan', common: Afghanistan }, hrv: { official: 'Islamska Republika Afganistan', common: Afganistan }, ita: { official: 'Repubblica islamica dell''Afghanistan', common: Afghanistan }, jpn: { official: アフガニスタン·イスラム共和国, common: アフガニスタン }, nld: { official: 'Islamitische Republiek Afghanistan', common: Afghanistan }, por: { official: 'República Islâmica do Afeganistão', common: Afeganistão }, rus: { official: 'Исламская Республика Афганистан', common: Афганистан }, spa: { official: 'República Islámica de Afganistán', common: Afganistán } }, latlng: [33, 65], demonym: Afghan, landlocked: true, borders: [IRN, PAK, TKM, UZB, TJK, CHN], area: 652230 }
- { name: { common: Angola, official: 'Republic of Angola', native: { por: { official: 'República de Angola', common: Angola } } }, tld: [.ao], cca2: AO, ccn3: '024', cca3: AGO, cioc: ANG, currency: [AOA], idd: { root: '+2', suffixes: ['44'] }, capital: Luanda, altSpellings: [AO, 'República de Angola', 'ʁɛpublika de an''ɡɔla'], region: Africa, subregion: 'Middle Africa', languages: { por: Portuguese }, translations: { cym: { official: 'Republic of Angola', common: Angola }, deu: { official: 'Republik Angola', common: Angola }, fin: { official: 'Angolan tasavalta', common: Angola }, fra: { official: 'République d''Angola', common: Angola }, hrv: { official: 'Republika Angola', common: Angola }, ita: { official: 'Repubblica dell''Angola', common: Angola }, jpn: { official: アンゴラ共和国, common: アンゴラ }, nld: { official: 'Republiek Angola', common: Angola }, por: { official: 'República de Angola', common: Angola }, rus: { official: 'Республика Ангола', common: Ангола }, spa: { official: 'República de Angola', common: Angola } }, latlng: [-12.5, 18.5], demonym: Angolan, landlocked: false, borders: [COG, COD, ZMB, NAM], area: 1246700 }

Customising the output

The data files provided in the

directory include all available fields, but is also possible to build a custom version of the data with certain fields excluded.

To do this, you will first need a working PHP installation, composer and a local copy of this repository. Once you have these, open a terminal in your local version of this project's root directory and run this command to install the necessary dependencies:

composer install

After this finishes, run the following command (here we will exclude the

field from the output, but you can exclude any field you want):
php countries.php convert --exclude-field=tld

You can also exclude multiple fields:

php countries.php convert --exclude-field=tld --exclude-field=cca2

Or using the shorter -x syntax:

php countries.php convert -x tld -x cca2

If you prefer to include only some fields (this can not be combined with

php countries.php convert --include-field=name --include-field=area

or using the shorter -i syntax:

php countries.php convert -i=name -i=area

The generated files are put into the

directory, but you can change this to another existing directory:
mkdir foobar
php countries.php convert --output-dir=foobar

You can also choose to only generate some of the output formats:

mkdir foobar
php countries.php convert --format=json_unescaped --format=csv

or using the shorter -f syntax:

php countries.php convert -f json_unescaped -f csv


Projects using this dataset:

How to contribute?

Please refer to CONTRIBUTING.

To do

  • add the type of the country (country, sovereign state, public body, territory, etc.)
  • add missing translations
  • pull in data automatically from CLDR at build time (idea from @Munter, see #108)

Sources for currency codes.

Region and subregion are taken from

GeoJSON outlines come from

The rest comes from Wikipedia.


Thanks to: - @Glazz for his help with country calling codes - @hexorx for his work ( - @frederik-jacques for the capital cities - @fayer for the population, geolocation, demonym and area data - @ancosen for his help with the borders data - @herrjemand for country names and various fixes - all the contributors:



We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.