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
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/static/img/play-codesandbox.svg)
Supported languages
en, ru, de, fr, es, zh, hi, pt, ja, ar, it, he
Any country, and language and any set could be loaded separate
FYI
- iso3166-1 is a country list
- iso3166-2 is states, regions, provinces and so on.
Fast onboarding
import data from 'iso3166-2-db/i18n/dispute/UN/en';
import data from 'iso3166-2-db/countryList/UN/en';
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
- This library provides both iso3166-1 and iso3166-2 codes
- This library is capable to generate data for different
points of view
(ie 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 largest cartographical site in the World. And in the past.
Usage
npm install iso3166-2-db
You have 2 ways to use this library:
-
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.
-
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
import data from 'iso3166-2-db/countryList/dispute/UN/{lang}'
import data from 'iso3166-2-db/regions/{iso3166-1}/dispute/UN/{lang}'
import data from 'iso3166-2-db/i18n/dispute/UN/{lang}'
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}'
import data from 'iso3166-2-db/regions/{iso3166-1}/*'
import data from 'iso3166-2-db/i18n/{lang}'
PS: import ..._ref, to get data with external references. It has a bit bigger size.
import data from 'iso3166-2-db/i18n/{lang}_ref'
Example
import countryList from 'iso3166-2-db/countryList/en';
import countryListWithForeignKeys from 'iso3166-2-db/countryList/en_ref';
import US from 'iso3166-2-db/regions/RU/dispute/UN/en';
import US from 'iso3166-2-db/regions/RU/dispute/RU/en';
Advanced usage
- Import unprocessed,
pure
data
import US from 'iso3166-2-db/regions/US/en';
import US from 'iso3166-2-db/regions/US/en_ref';
import DE from 'iso3166-2-db/regions/DE/de_ref';
import { combine } 'iso3166-2-db/combine';
const dataSet = combine(countryList, { US }) ;
To process pure
data you should call getDataSet command.
import { getDataSet, getRegionsFor, changeDispute, changeNameProvider, findCountryByName, findRegionByCode } from 'iso3166-2-db/api';
const fixedDataSet = getDataSet('en', combine(countryList, { US }));
I hope you did not understand, what dispute
means, and why you should run getDataSet.
it is very simple -
import RU from 'iso3166-2-db/regions/RU/dispute/UN/en'
import RU from 'iso3166-2-db/regions/RU/en'
import RU from 'iso3166-2-db/regions/RU/dispute/RU/en'
const fixedDataSet = getDataSet('ru', combine(countryList, { RU }));
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
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, and you will understand.
So we have some simple things:
-
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.
-
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.
-
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
-
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!
Just call changeNameProvider('geonames|osm|wikipedia')
(yup, by default we use wikipedia article names)
Working only for backend way
.
-
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
Country list is a hash.
Key is a iso3166-1 code
Value
{
"iso": "AD",
"iso3": "AND",
"numeric": 20,
"fips": "AN",
"reference": {
"geonames": 3041565,
"openstreetmap": 9407,
"wikipedia": "en:Andorra"
},
name: "Andorra",
"names": {
"geonames": "Andorra",
"en": "Andorra",
"ar": "أندورا",
"de": "Andorra",
"es": "Andorra",
"fr": "Andorre",
"it": "Andorra",
"ru": "Андорра",
"zh": "Chinese"
},
regions:[ ]
}
Regions is an array of
{
"name": "Sant Julià de Lòria",
"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",
"fips": "06",
"reference": {
"geonames": 3039162,
"openstreetmap": 2804759,
"openstreetmap_level": 7,
"wikipedia": "en:Sant_Julià_de_Lòria",
"wof": null
}
},
Used sources:
- geolocated.org – as primary source.
- Geonames.org – as main information source
- Wikipedia.org – as main information source
- Esosedi.org – as main information source
- OpenStreetMap.org – as secondary source
- Whosonfirst-data – as external links for region information (as long Pelias return region code as WOF entity]
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.