Skip to content

Commit

Permalink
2.1.0 version. + precalculated terrotorial disputes
Browse files Browse the repository at this point in the history
  • Loading branch information
@theKashey
theKashey committed May 11, 2017
1 parent 48ca5a9 commit 35c9792
Show file tree
Hide file tree
Showing 17 changed files with 608 additions and 283 deletions.
6 changes: 5 additions & 1 deletion .eslintrc
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,13 @@
{
"parser": "babel-eslint",
"extends": "eslint:recommended",
"plugins": [
"mocha"
],
"env": {
"browser": true,
"node": true,
"es6": true
"es6": true,
"mocha": true
}
}
180 changes: 160 additions & 20 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,48 +1,125 @@
# 3166 (iso standart about 2-3 letter codes of administrative divisions)
This world is small enough. But not everyone knows all countries and all states. So, lets just create a list of countries as iso3166-1 and lists of states or regions as iso3166-2. And include external references to all sources, you may use (GeoNames, OpenStreetMap, Wikipedia, WOF)
# iso3166, iso3166-1, iso3166-2
(iso standart about N-letter codes of administrative divisions and subdivisions)
The country codes in the data are in the ISO 3166-1 alpha 2 format (US, SE ...),
it also possible to use alpha 3 codes (USA, SWE ...) or alpha-numeric codes. In most cases one use alpha-2.

* How to get list of all countries: call `getDataSet` and traverse look for .name in every object inside
* How to get states of country: call getRegionsFor(countryIsoCode) and do the same.
[![Build Status](https://secure.travis-ci.org/esosedi/3361.svg)](http://travis-ci.org/esosedi/3166)

> npm install iso3166-2-db
[![NPM](https://nodei.co/npm/iso3166-2-db.png?downloads=true&stars=true)](https://nodei.co/npm/iso3166-2-db/)

>This world is small enough.
But not everyone knows all countries and all states.
So, lets just create a list of countries as iso3166-1 and lists of states or regions as iso3166-2.
And include external references to all sources, you may use (GeoNames, OpenStreetMap, Wikipedia, WOF)
This is nodejs/javascript module, but you can use it as set of json files from other languages

```javascript
import worldDatabase from 'iso3166-2-db/i18n/dispute/UN/en';
import listOfCountries from 'iso3166-2-db/countryList/dispute/UN/en';
import USregions from 'iso3166-2-db/regions/US/dispute/UN/en';
```

Just look at json file, and you will understand.
# FYI
* iso3166-1 is a country list
* iso3166-2 is a states, regions, provinces and so on list.

# About
* This library provides both iso3166-1 and iso3166-2 codes
* This library is capable to generate different `point of view` (ie [Territorial dispute](https://en.wikipedia.org/wiki/Territorial_dispute))
* This library is both modular and functional. Fits both for frontend and backend
* This library contain external references to a `trusted` sources
* This library is brought to you by esosedi – one of lagest cartographical site in the World. Not hipsters.

# Usage
> npm install iso3166-2-db
You have 2 ways to use this library:
1. Use it at `backend`. Just import few function from 'iso3166-2-db' and go on.
You will have everything - all data, in pack of languages, with different dispute models and name sources.
But - full database has size of few megabytes.

2. Use it as data files, ie modular format - this way is preferred for `frontend`.
Result will produce much smaller code.

# Modular API
* There is two versions on `modular` API - `pure` and `compiled`.
In 99% cases you need - compiled

2. Use it as data files - this way is preferred for `frontend`.
* Import data from 'iso3166-2-db/countryList/dispute/UN/{lang}' to get country list.
* Import data from 'iso3166-2-db/regions/{iso3166-1}/dispute/UN/{lang}' to get states(regions) for selected country.
* Import data from 'iso3166-2-db/i18n/dispute/UN/{lang}' to get both states and countries.

Where UN - is United Nations. World from United Nations point of view. We call this - `dispute`.
Possible values - UN, UA, TR, RU. IF you need more - open a pull request.

You can also load `pure` data:

* Import data from 'iso3166-2-db/countryList/{lang}' to get country list.
* Import data from 'iso3166-2-db/regions/{iso3166-1}/*' to get states(regions) for selected country.
* Import data from 'iso3166-2-db/i18n/{lang}' to get both states and countries.

PS: import ..._ref, to get data with external references.

### example
```javascript
// just import what you want - /countryList/{lang}
import countryList from 'iso3166-2-db/countryList/en';

// or, to have countryListWithForeignKeys.US.CA.reference.wikipedia and so on
import countryListWithForeignKeys from 'iso3166-2-db/countryList/en_ref';


//import states of FEW countries /countryList/{iso1}/{lang}

// import states for a country /countryList/{iso1}/{lang}
// import states for a country /countryList/{iso1}/dispute/{source}/{lang}

// next will import US states for point of view of United Nations.
import US from 'iso3166-2-db/regions/US/dispute/UN/en';

// or you can import `default` dataset
import US from 'iso3166-2-db/regions/US/en';
//or, to have keys
// or, import with keys
import US from 'iso3166-2-db/regions/US/en_ref';
import DE from 'iso3166-2-db/regions/DE/de_ref';// use other lang for other country? Simple!

//import combine function
import { combine, use } 'iso3166-2-db/combine';
import { combine } 'iso3166-2-db/combine';

// join country dataset with states
const dataSet = combine(countryList, { US }) ;// !!!! region object key MUST match iso code.
use(dataSet); // prepopulate data into library
// dataSet is similar to i18n, but contains regions only for US, not for a whole world.
```

//you can also import only function from library, with out data
import { getDataSet, getRegionsFor, changeDispute, changeNameProvider, findCountryByName, findRegionByCode } from 'iso3166-2-db/api';
To process `pure` data you should call getDataSet command.
```javascript

//if you are going to use `dataSet` outside, it will require one more state..
// you can also import only function from library, with out data
import { getDataSet, getRegionsFor, changeDispute, changeNameProvider, findCountryByName, findRegionByCode } from 'iso3166-2-db/api';

import { combine, getDataSet } from 'iso3166-2-db/api';
const fixedDataSet = getDataSet('en', combine(countryList, { US }));
// this command will move some disputed regions across countries.
// without this command few things can be wrong. See below.

// see bellow for API help
// without this command few things can be wrong. See below.
```

I hope you did not understand, what `dispute` means, and why you should run getDataSet.
it is very simple -
```js
import RU from 'iso3166-2-db/regions/RU/dispute/UN/en' // - will NOT contain Crimea
import RU from 'iso3166-2-db/regions/RU/en' // - will NOT contain Crimea
import RU from 'iso3166-2-db/regions/RU/dispute/RU/en' // - will CONTAIN Crimea
const fixedDataSet = getDataSet('ru', combine(countryList, { RU })); // - will CONTAIN Crimea
```
Also some countries are not exists, or exists not as counties, but as stated by point of view of some different countries.



### creating country selector with React
See [example](//esosedi/3166/examples/react.countrySelector.js)

#Functional API

* How to get list of all countries: call `getDataSet` and traverse look for .name in every object inside
* How to get states of country: call getRegionsFor(countryIsoCode) and do the same.

Just look at source json file(data/iso3166-2.json), and you will understand.

So we have some simple things:
1. data/iso3166-2.json – main datafile. It containtains all counties and all regions.
Expand Down Expand Up @@ -102,6 +179,69 @@ This is open source made from open source. Everything can be wrong. And will be.

Main datafile is auto generated from free sources.

# Data format
Country list is a hash.
Key is a iso3166-1 code
Value
```js
{
"iso": "AD", //iso3166-1 `two` letter code
"iso3": "AND", //iso3166-1 `three` letter code
"numeric": 20, //iso3166-1 `numeric` code
"fips": "AN", //FIPS code
// next key is exist only in `_ref` exports
"reference": { // external reference to
"geonames": 3041565, // geonames.org
"openstreetmap": 9407, // openstreetmap releation id
"wikipedia": "en:Andorra" // wikipedia article
},
// next key is not exist in full pack
name: "Andorra",
// next key is not exist in language-reduced pack
"names": { // names in different languages
"geonames": "Andorra",
"en": "Andorra",
"ar": "أندورا",
"de": "Andorra",
"es": "Andorra",
"fr": "Andorre",
"it": "Andorra",
"ru": "Андорра",
"zh": "Chinese"
},
regions:[ /* set of regions */]
}
```

Regions is an array of
```js
{
// next keys will contain name in selected language
"name": "Sant Julià de Lòria",
// next keys is not exists in language-reduced pack
"names": {
"geonames": "Parroquia de Sant Julia de Loria",
"ru": "Сан-Жулиа-де-Лория",
"en": "Sant Julià de Lòria",
"de": "Sant Julià de Lòria",
"es": "San Julián de Loria",
"fr": "Sant Julià de Lòria",
"it": "Parrocchia di Sant Julià de Lòria",
"zh": "圣胡利娅-德洛里亚"
},
"iso": "06", // iso3166-2 code
"fips": "06", // FIPS code
// next key is exist only in `_ref` exports
"reference": {
"geonames": 3039162, // geonames.org
"openstreetmap": 2804759, // openstreetmap relation id
"openstreetmap_level": 7, // openstreetmap administrative division level
"wikipedia": "en:Sant_Julià_de_Lòria", // wikipedia article
"wof": null // WOF code
}
},
```

Used sources:
1. [geolocated.org](http://geolocated.org/) – as primary source.
2. [Geonames.org](http://geonames.org/) – as main information source
Expand Down
108 changes: 66 additions & 42 deletions bin/prepublish.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,53 +16,77 @@ mkdirSync('./i18n');

// get list of languages

const dataset = require('../data/iso3166-2.json');
const listOfDisputes = {
'': '',
'UN': 'en',
'TR': 'tr',
'UA': 'ua',
'RU': 'ru'
};

const i18n = {};
const langs = {};
const regions = {};
const pure_dataset = require('../data/iso3166-2.json');

Object.keys(dataset).forEach(iso1 => {
Object.keys(dataset[iso1].names).forEach(lang => {
if (lang && !langs[lang]) {
const subset = lib.reduce(dataset, lang);
const countrySet = {};
const regionSet = {};
Object.keys(subset).forEach(iso1 => {
countrySet[iso1] = Object.assign({}, subset[iso1], {regions: []});
regionSet[iso1] = subset[iso1].regions.map(region => Object.assign({}, region))
});
i18n[lang] = subset;
langs[lang] = countrySet;
regions[lang] = regionSet;
}
});
});
Object.keys(listOfDisputes).forEach(disputeName => {

const mmap = (x, f) => {
const result = {};
Object.keys(x).forEach(key => {
result[key] = f(x[key]);
});
return result;
};
let dataset = pure_dataset;
let DPrefix = '';
if (listOfDisputes[disputeName]) {
dataset = lib.getDataSet(listOfDisputes[disputeName], pure_dataset);
DPrefix = `dispute/${disputeName}/`;
}

const i18n = {};
const langs = {};
const regions = {};

Object.keys(langs).forEach(lang => {
fs.writeFileSync('./i18n/' + lang + '.json', JSON.stringify(i18n[lang]));
fs.writeFileSync('./countryList/' + lang + '_ref.json', JSON.stringify(langs[lang]));
fs.writeFileSync('./countryList/' + lang + '.json', JSON.stringify(
mmap(langs[lang], x => Object.assign({}, x, {
reference: {
openstreetmap: x.reference.openstreetmap
Object.keys(dataset).forEach(iso1 => {
Object.keys(dataset[iso1].names).forEach(lang => {
if (lang && !langs[lang]) {
const subset = lib.reduce(dataset, lang);
const countrySet = {};
const regionSet = {};
Object.keys(subset).forEach(iso1 => {
countrySet[iso1] = Object.assign({}, subset[iso1], {regions: []});
regionSet[iso1] = subset[iso1].regions.map(region => Object.assign({}, region))
});
i18n[lang] = subset;
langs[lang] = countrySet;
regions[lang] = regionSet;
}
}))
));
const langRegions = regions[lang];
Object.keys(langRegions).forEach(iso1 => {
mkdirSync('./regions/' + iso1);
fs.writeFileSync('./regions/' + iso1 + '/' + lang + '.json', JSON.stringify(
langRegions[iso1].map(x => Object.assign({}, x, {reference: {}}))
});
});

const mmap = (x, f) => {
const result = {};
Object.keys(x).forEach(key => {
result[key] = f(x[key]);
});
return result;
};

Object.keys(langs).forEach(lang => {
mkdirSync('./i18n//dispute');
mkdirSync('./i18n/' + DPrefix);
mkdirSync('./countryList/dispute');
mkdirSync('./countryList/' + DPrefix);
fs.writeFileSync('./i18n/' + DPrefix + lang + '.json', JSON.stringify(i18n[lang]));
fs.writeFileSync('./countryList/' + DPrefix + lang + '_ref.json', JSON.stringify(langs[lang]));
fs.writeFileSync('./countryList/' + DPrefix + lang + '.json', JSON.stringify(
mmap(langs[lang], x => Object.assign({}, x, {
reference: {
openstreetmap: x.reference.openstreetmap
}
}))
));
fs.writeFileSync('./regions/' + iso1 + '/' + lang + '_ref.json', JSON.stringify(langRegions[iso1]));
const langRegions = regions[lang];
Object.keys(langRegions).forEach(iso1 => {
mkdirSync('./regions/' + iso1);
mkdirSync('./regions/' + iso1 + '/dispute');
mkdirSync('./regions/' + iso1 + '/' + DPrefix);
fs.writeFileSync('./regions/' + iso1 + '/' + DPrefix + lang + '.json', JSON.stringify(
langRegions[iso1].map(x => Object.assign({}, x, {reference: {}}))
));
fs.writeFileSync('./regions/' + iso1 + '/' + DPrefix + lang + '_ref.json', JSON.stringify(langRegions[iso1]));
});
});
});
Loading

0 comments on commit 35c9792

Please sign in to comment.