iso 3166

iso3166, iso3166-1, iso3166-2

(ISO standard about N-letter codes of administrative divisions and subdivisions)
In other words - Administrative Divisions of Countries (aka "Statoids" or "Country names").

The country codes are mainly 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 you need alpha-2.

>This world is small enough.
But not everyone knows all countries and all states.
List of countries is known as iso3166-1 and lists of states or regions is known as iso3166-2.
And lets extend information withexternal 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';
`
![Try it online ](https://codesandbox.io/s/LgBN3qy5j)
- try it online.

$3

// to get only list countries in an English from UN prospective
import data from 'iso3166-2-db/countryList/UN/en';

// to get only list stated for the country in an %Lang% from UN prospective
import data from 'iso3166-2-db/regions/{COUNTRYISOCODE}/UN/{lang}';
`
Yep. Did not forget to add /dispute/UN/. It is the main difference between this library and any other - it knows that world is not united, yet.

About

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, pack of languages, with different dispute models and name sources.
But - full database has a 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

// will import RU states for point of view of United Nations - without Crimea
import US from 'iso3166-2-db/regions/RU/dispute/UN/en';
// will import RU states for point of view of Russia - including Crimea
import US from 'iso3166-2-db/regions/RU/dispute/RU/en';
`

### Advanced usage
1. Import unprocessed, pure data
`javascript
// you can import default dataset
import US from 'iso3166-2-db/regions/US/en';
// or, import with foreignKeys
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 } 'iso3166-2-db/combine';

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

`
To process pure data you should call getDataSet command.
`javascript

// you can also import only function from library, with out data
import { getDataSet, getRegionsFor, changeDispute, changeNameProvider, findCountryByName, findRegionByCode } 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.
`

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.





$3

* 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, and you will understand.

So we have some simple things:
1. data/iso3166-2.json – main datafile. It containtains all counties and all regions.
Just keep in mind - this is not a stupid list of names. We provide all information for any entity:

* iso3166-1(alpha2, alpha3, numeric, FIPS) for a country
* iso3166-2(alpha2, FIPS) for a region
* links to geonames, openstreetmap relation, wikipedia article, WOF. So you can merge this data, to everything else!
* names in main languages

Best option is to use this file directly.
2. src/disputedBorders.js – set of pure functions to transform main data file for "your" country. As long all countries have their own mind.
Only UN001(US), RU, UA, TR schemes supported.

Remember – main data file is wrong by default. You HAVE to apply some filter to data.
Or you will get TW as country and Crimea as part of Russia (use 'ru' dispute mode to have it :P).

Remember – to add one region to one place, you have to remove it from other place
Ie, to add Crimea into Russian states you have to have US states.

3. src/iso3166.js – library logic (main entry point)

We have a simply command for it(2.) getDataSet(dispute='en') for it.

* changeDispute(string) – change default dispute.
* getDataSet([dispute], [dataSet]) - returns transformed iso3166 data.
* getRegionsFor(country) - returns states for a country.
* findCountryByName(countryName) - perform lookup via all possible names
* findRegionByCode(string(iso3166-2 code)) - returns region for a code. AU-NSW for example

4. And every one have their own knowlege about naming. And every one have different.
What is why we create this library – to bring a peace (and foreign keys).

But, you really might wish to use different names from different sources. And we have a tools for it!

* data/names_geonames.json – all region names from geonames.org
* data/names_osm.json – same from openstreetmap.org

Just call changeNameProvider('geonames|osm|wikipedia') _(yup, by default we use wikipedia article names)_

Working only for backend way.

5. And do not forget THIS THING IS FOR BACKEND!
Datafiles are VERY large. But you can reduce them.
Call reduce(dataSet, lng, listOfCountries) to get data ONLY for one language and selected countries.
_name will be filled into .name field of entity. .names will be dropped._

example: reduce(getDataSet(), 'en', ['US','CA','AU'])

And be aware - some states are not the states. Until they have iso3166-2(iso) code.
Some of them contain only FIPS.

Also be aware about operstreetmap_level. Most of regions have 4. Some of them (in Slovenia) have 6. But.. there is regions with 7.
I am not sure about them.

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

As result - iso3166-2-db is best best free source for countries divisions. With incomparable to Statoids(1000$ btw) quality. I mean - this one is better.

All sources used as external dictionaries, for ability to link and merge data.
Countries and states exists by themselves and have their own names.
You dont have to refer to us, to wikipedia, to osm, geonames or everything else in cases you showing our list of countries.

This is not our or their` list. This is ground truth, and it cannot be licensed.
We are on the same planet.