What data to add next?

[mledoze]

I would like to discuss here the data that should be added to this repository.

A similar project like 0xJS [1] contains a lot more data such as the land area or the latitude/longitude coordinates of each country.

Is it interesting/useful to have this kind of data too?

Data that can be added:

• land (land mass in square kilometers [3])
• latitude (latitude coordinate of the capital [2])
• longitude (longitude coordinate of the capital [2])
• east (longitude of the country's eastern boundary [3])
• north (latitude of the country's northern boundary [3])
• south (latitude of the country's southern boundary [3])

What would you like to be added?

Please let me know in the comments.

[1] http://oxjs.org/#doc/Ox.COUNTRIES
[2] source: http://opengeocode.org/
[3] source: https://oxjs.org/#doc/Ox.COUNTRIES

---

From the comments

• add the type of the country (country, sovereign state, public body, territory, etc.)
• add the land borders (done, see https://github.com/mledoze/countries/tree/v1.3)
• add regions, provinces and cities

[scento]

It might be useful to provide the country name in the native language of the country itself (e.g. {"name": "Germany", "name_native": "Deutschland"}...

[scento]

The CLDR database of the unicode project contains Country-To-Language data, including the percent of speakers: http://www.unicode.org/cldr/charts/latest/supplemental/territory_language_information.html

[mledoze]

It might be useful to provide the country name in the native language of the country itself

The native name of Germany is already in 'alt-spellings'. I recognize that the name 'alt-spellings' isn't good since it contains alternative spellings and the native name of the country. So there are two solutions here:

• either we change 'alt-spellings' to 'alt-names' and keep the native name here
• or we keep 'alt-spellings' just for alternative spellings and create 'name-native' as you suggested.

Initially, I created this dataset with a country selector in mind [1] but it would make more sense to be able to get the native names separately. So I would choose the second option.

But the second option raises the question of how to write the native name of the country. German uses latin characters so it's easy to know that it's Germany, but what about Armenia for example which is written Հայաստան in armenian [2]? For some people it might be difficult to know that it's Armenia.

What do you think?

I know that alternative spellings and native names are missing for many countries, I'm currently working on adding them. Also, I'll add the native/official language(s) of each country.

[1] https://github.com/JamieAppleseed/selectToAutocomplete
[2] http://en.wikipedia.org/wiki/Armenia

[scento]

Not all people speak English, so they might be confused while selecting their locale. It might be useful if it is possible to see the English and native version of the country name parallel in the selector.

I would recommend to provide both versions for different individual usecases.

[mledoze]

Right, it's valid for non english speakers.

If you want, feel free to start working on adding the native names as I'll be off for a few days.

[stephenpaulger]

I think it would be great to have a way to make Countries Hierarchical and have meta data describing whether they are countries or sovereign states.

For the UK currently it says "alt-spellings":"GB,Great Britain,England,UK,Wales,Scotland,Northern Ireland".

The full name of the UK is "The United Kingdom of Great Britain and Northern Ireland". It is not a country, it is a sovereign state.

Great Britain also isn't a country, it's an island.

There are three countries in Great Britain: England, Scotland and Wales.

So the types I think needed are: Country, State, Sovereign State and potentially Nation and Union as well.

Then it would be good to have a way to specify that England is within the UK and if you also have unions that it is within the EU.

Another nice feature would be to list what land borders a country has. So you could specify that England borders Scotland and Wales for example.

[fayderflorez]

From https://github.com/ProGNOMmers

It would be wonderful if it would be possible to retrieve regions, provinces and cities.

Something like:

// Regions of country
// /rest/alpha2/it/regions ->
{ regions:  [ "Abruzzi e Molise",
              "Basilicata",
              "Calabria",
              "Campania",
              "Emilia-Romagna",
              "Friuli-Venezia Giulia",
              "Lazio",
              "Liguria",
              "Lombardia",
              "Marche",
              "Piemonte",
              "Puglia",
              "Sardegna",
              "Sicilia",
              "Toscana",
              "Trentino-Alto Adige",
              "Umbria",
              "Valle d'Aosta",
              "Veneto" ] }

// Provinces of region
// /rest/alpha2/it/regions/Veneto/provinces ->
{ provinces: [ "Verona", "Venezia", ... ] }

// Cities of province
// /rest/alpha2/it/regions/Veneto/provinces/Venezia/cities ->
{ cities: [ { name: "Venezia", zip_codes: [ "30121", ... , "30176" ] }, 
            { name: "Chioggia", zip_codes: [ "30015" ] },
            { name: "San Donà di Piave", zip_codes: [ "30027" ] }, 
            ... ] }

// Cities of country by name
// /rest/alpha2/it/regions/Veneto/provinces/Venezia/cities ->
{ cities: [ { name: "Venezia", zip_codes: [ "30121", ... , "30176" ] }, 
            { name: "Chioggia", zip_codes: [ "30015" ] },
            { name: "San Donà di Piave", zip_codes: [ "30027" ] }, 
            ... ] }

Cities could have metadata like f.i. zip codes, which are very useful.

It is a huge work because recording and maintaining the whole list of regions, provinces and cities for every world country is hard, but it is a good target to be accomplished by an open source project.

[mledoze]

@stephenpaulger

I think it would be great to have a way to make Countries Hierarchical and have meta data describing whether they are countries or sovereign states.

I agree, I'll add this to the todo. I know that many entries in the dataset are not actual contries. I wanted to provide simple and factual data about world countries but I understand that more accuracy is needed.

[mledoze]

@fayder

It would be wonderful if it would be possible to retrieve regions, provinces and cities.

Yes it is a huge work. First I want to continue to add more data at the country level (native and official names, official language, etc.) and add the master file as soon as possible (#12) to ease the contributions.

Thank you for your help/feedback, I appreciate it!

[mledoze]

For the UK currently it says "alt-spellings":"GB,Great Britain,England,UK,Wales,Scotland,Northern Ireland".

@stephenpaulger in bd22b4a I have removed most of the names in altSpellings, now it's just GB,UK,Great Britain.

[mledoze]

We can also add time zone data from http://timezonedb.com/download.

[shanti2530]

It would be really nice if there would be also a list of states per country such as the United States states. http://en.wikipedia.org/wiki/List_of_states_and_territories_of_the_United_States

[mledoze]

@shanti2530 yes, this has been suggested #6 (comment) but it has not been done yet because the work is pretty huge.
Do you know a source where we can find the states for every country?

[shanti2530]

@mledoze don't know if this is what you were looking for http://vikku.info/programming/geodata/geonames-get-country-state-city-hierarchy.htm

[mledoze]

@shanti2530 this seems very good, thank you. I'll create an issue for this. Would you like to work on this?

[mledoze]

Well in that case, the translations have to be exact :)

There is no list of targeted languages, any language can be added to the list of translations.

[marc-ed-raffalli]

Good to know, I'll look for better translation sources :)

[marc-ed-raffalli]

Hi @mledoze
I found translations for a good number country names and capitals e.g. London => Londres.
In #263 (comment) you said planning for 2.0. I would propose to change capital to a multi dimensional array too, will send a PR once ok.

capital:{
  en: 'London',
  fr: 'Londres'
}

[mledoze]

I would propose to change capital to a multi dimensional array

@marc-ed-raffalli this change was already made by @blumk in d9e81cc. But translations for countries capital(s) are welcome :)

[marc-ed-raffalli]

@mledoze The change allows to support multiple capitals as an array of strings, does not allow a mapping to multiple languages. I would propose something like:

capital: {
  en: ['Pretoria', 'Cape Town', 'Bloemfontein'],
  fr: ['Pretoria', 'Le Cap', 'Bloemfontein'],
  ru: ['Претория', 'Кейптаун', 'Блумфонтейн'],
  zh: ['比勒陀利亚', '开普敦', '布隆方丹']
}

edited with better example

[blumk]

Looking at the current countries.json implementation I'd suggest refactoring translations into separate *.json files, e.g. fra.json:

{
  "cca3": "ZAF",
  "name": {"official": "R\u00e9publique d'Afrique du Sud", "common": "Afrique du Sud"},
  "capital": ['Pretoria', 'Le Cap', 'Bloemfontein'],
  "demonym": "Sud-Africain"
},
...

Creating separate language files brings the following benefits:

• Current implementation has a "translations" property. Adding capitals would lead to the following confusion: translation of what? (Name, capital?). Dedicated files solves this problem (see example above)
• Languages shouldn't pollute the main countries.json file since there are 6000+ languages. Adding a new language is difficult (see Arabic translations PR)
• You can give a single language file to a native speaker and she can confirm the correctness without knowing too much about the countries.json file
• Better support for lazy loading (e.g. two supported languages means loading two *.json files)

@marc-ed-raffalli @mledoze What do you guys think of this approach?

[marc-ed-raffalli]

@blumk

Better support for lazy loading (e.g. two supported languages means loading two *.json files)

Do you mean 3 files? one pure data (language agnostic), and two translation files

[blumk]

@marc-ed-raffalli

Do you mean 3 files? one pure data (language agnostic), and two translation files

Yes. Adding support for for two additional languages (countries.json defaults to English) means that you'll have to load countries.json and e.g. fra.json and slk.json in order to support ENG, FRA, SLK.

[marc-ed-raffalli]

@blumk
I like the idea of separate language files. I would even push the idea and have all languages into dedicated files (including ENG) since not all apps necessarily support English :)

Let's see what's the feedback from the other contributors

[mledoze]

@blumk

Looking at the current countries.json implementation I'd suggest refactoring translations into separate *.json files

I find this idea interesting, but what would be your proposal for the directories/files structure? Given your example, would the fra.json file be in a data/zaf folder?

[blumk]

@mledoze

I find this idea interesting, but what would be your proposal for the directories/files structure? Given your example, would the fra.json file be in a data/zaf folder?

I guess there are two options:

• one translation file per language containing all 250 records: you can use a folder like data | translations | i18n containing all translation files
• one translation file per language and record: in that case subfolders like data/zaf might be the way to go. However you end up having n*250 files

I might prefer one file per language containing all 250 records for the following reasons:

• it use case driven: e.g. drop down list of all countries in French, a map with all capitals in Dutch.
• one language, one location: you can give a single language file to a translator, you'll only need to load one file

E.g.

{
  "cca3": "ZAF",
  "name": {"official": "R\u00e9publique d'Afrique du Sud", "common": "Afrique du Sud"},
  "capital": ['Pretoria', 'Le Cap', 'Bloemfontein'],
  "demonym": "Sud-Africain"
},
{
  "cca3": "FRA",
  "name": ...
},
...

[ColinH]

My suggestion on "what to add next" would be NDD and IDD prefixes.

[mledoze]

My suggestion on "what to add next" would be NDD and IDD prefixes.

Thank your for your suggestion, I'll look into it.

[mledoze]

@blumk I would like to move forward with your proposal to refactor translations to separate files; could you please open a new issue with your proposal? Thank you very much.

[lupinitylabs]

One thing I would really like to see added is the most commonly used native language / administrative language used in the country.

For example, Norway has three different, unweighted native names:
"native":{"nno":{"official":"Kongeriket Noreg","common":"Noreg"},"nob":{"official":"Kongeriket Norge","common":"Norge"},"smi":{"official":"Norgga gonagasriika","common":"Norgga"}}

And there is no way to tell which one of the three is the commonly used, for example in language or country choosers. In this example, Norge would obviously be the way to go, not Noreg or Norgga.

Can we either have a key for the official native name or a weighted/ranked list of languages in the country?

Also, there are altSpellings:
"altSpellings":["NO","Norge","Noreg","Kingdom of Norway","Kongeriket Norge","Kongeriket Noreg"]

But I don't feel comfortable trusting on the first items in the list to be the most common, also it's pretty much a mix of abbreviations and languages, which is generally not very helpful in this case. Also, Norgga from the native array above is missing in the altSpellings array, which is confusing?