npmpackage.info

Gathering detailed insights and metrics for iso3166-2-db

Other packages similar to iso3166-2-db

@lineto/countries

5.0.0

'Iso3166-2-db/i18n/dispute/UN/en', converted to the format used by https://lineto.com

the-country-names

2.2.0

this is a small (40-120kb gziped) part of [iso3166-2-db](https://github.com/esosedi/3166) library. Contains only English names for the world from UN point of view

iso3166-2-db

This is the best source for iso3166 codes you can found. I am sure.

2.3.11

128

MIT

JavaScript

489.60 kB

1,324,958 2.1

Installations

npm install iso3166-2-db

Developer Guide

BETA

Typescript

No

Module System

CommonJS

Node Version

16.20.2

NPM Version

8.19.4 Score

92.8

Supply Chain

100

Quality

77.1

Maintenance

100

Vulnerability

100

License

Pull Requests

Open

2

Total

38

Closed

17

Merged

19

Issues

Open

9

Total

18

Closed

9

Releases

Unable to fetch releases

Contributors

Unable to fetch Contributors

View all 10 contributors

Languages

JavaScript

JavaScript (100%)

Developer

esosedi

Download Statistics

Total Downloads

1,324,958

Last Day

1,495

Last Week

6,903

Last Month

30,086

Last Year

292,287

GitHub Statistics

128 Stars

98 Commits

28 Forks

9 Watching

3 Branches

10 Contributors

Bundle Size

1.97 MB

Minified

489.60 kB

Minified + Gzipped

Bundlephobia

Maintainers

Package Meta Information

Latest Version

2.3.11

Package Id

iso3166-2-db@2.3.11

Unpacked Size

169.08 MB

Size

17.25 MB

File Count

42,268

NPM Version

8.19.4

Node Version

16.20.2

Publised On

11 Jul 2024

Total Downloads

Cumulative downloads

Total Downloads

1,324,958

Last day

-19.8%

1,495

Compared to previous day

Last week

-31.8%

6,903

Compared to previous week

Last month

20.5%

30,086

Compared to previous month

Last year

7.2%

292,287

Compared to previous year

Daily Downloads

Weekly Downloads

Monthly Downloads

Yearly Downloads

Dev Dependencies

babel-cli babel-eslint babel-preset-latest babel-preset-stage-1 chai eslint eslint-plugin-mocha mocha node-fetch proxyquire-webpack-alias

Versions

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

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

try it online.

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

1    // to get both states and countries in an English from UN prospective
2    import data from 'iso3166-2-db/i18n/dispute/UN/en';
3
4    // to get only list countries in an English from UN prospective
5    import data from 'iso3166-2-db/countryList/UN/en';
6    
7    // to get only list stated for the country in an %Lang% from UN prospective
8    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

1   // to get country list.
2   import data from 'iso3166-2-db/countryList/dispute/UN/{lang}'
3   // to get states(regions) for selected country.
4   import data from 'iso3166-2-db/regions/{iso3166-1}/dispute/UN/{lang}'
5   // to get both states and countries.
6   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:

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

PS: import ..._ref, to get data with external references. It has a bit bigger size.

1   import data from 'iso3166-2-db/i18n/{lang}_ref'

Example

1 // just import what you want - /countryList/{lang}
2 import countryList from 'iso3166-2-db/countryList/en';
3
4 // or, to have foreignKeys to wikipedia, geonames and so on
5 import countryListWithForeignKeys from 'iso3166-2-db/countryList/en_ref';
6
7 // import states for a country /countryList/{iso1}/{lang}
8 // import states for a country /countryList/{iso1}/dispute/{source}/{lang}
9
10 //  will import RU states for point of view of United Nations - without Crimea
11 import US from 'iso3166-2-db/regions/RU/dispute/UN/en';
12 //  will import RU states for point of view of Russia - including Crimea
13 import US from 'iso3166-2-db/regions/RU/dispute/RU/en';

Advanced usage

Import unprocessed, pure data

1// you can import `default` dataset
2import US from 'iso3166-2-db/regions/US/en';
3// or, import with foreignKeys
4import US from 'iso3166-2-db/regions/US/en_ref';
5import DE from 'iso3166-2-db/regions/DE/de_ref';// use other lang for other country? Simple! 
6
7//import combine function
8import { combine } 'iso3166-2-db/combine';
9
10// join country dataset with states
11const dataSet = combine(countryList, { US }) ;// !!!! region object key MUST match iso code.
12// dataSet is similar to i18n, but contains regions only for US, not for a whole world.   
13

To process pure data you should call getDataSet command.

1
2// you can also import only function from library, with out data 
3import { getDataSet, getRegionsFor, changeDispute, changeNameProvider, findCountryByName, findRegionByCode } from 'iso3166-2-db/api';
4
5const fixedDataSet = getDataSet('en', combine(countryList, { US }));
6// this command will move some disputed regions across countries.
7// 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 -

1import RU from 'iso3166-2-db/regions/RU/dispute/UN/en' // - will NOT contain Crimea
2import RU from 'iso3166-2-db/regions/RU/en'            // - will NOT contain Crimea
3import RU from 'iso3166-2-db/regions/RU/dispute/RU/en' // - will CONTAIN Crimea
4const 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

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!
- 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.
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

1{
2    "iso": "AD",   //iso3166-1 `two` letter code
3    "iso3": "AND", //iso3166-1 `three` letter code
4    "numeric": 20, //iso3166-1 `numeric` code
5    "fips": "AN",  //FIPS code
6    // next key is exist only in `_ref` exports
7    "reference": { // external reference to
8        "geonames": 3041565,      // geonames.org 
9        "openstreetmap": 9407,    // openstreetmap releation id
10        "wikipedia": "en:Andorra" // wikipedia article
11    },
12    // next key is not exist in full pack
13    name: "Andorra",
14    // next key is not exist in language-reduced pack 
15    "names": {                    // names in different languages
16        "geonames": "Andorra",
17        "en": "Andorra",
18        "ar": "أندورا",
19        "de": "Andorra",
20        "es": "Andorra",
21        "fr": "Andorre",
22        "it": "Andorra",
23        "ru": "Андорра",
24        "zh": "Chinese"
25    },
26    regions:[ /* set of regions */]
27  }

Regions is an array of

1{
2    // next keys will contain name in selected language
3    "name": "Sant Julià de Lòria",
4    // next keys is not exists in language-reduced pack
5    "names": {
6        "geonames": "Parroquia de Sant Julia de Loria",
7        "ru": "Сан-Жулиа-де-Лория",
8        "en": "Sant Julià de Lòria",
9        "de": "Sant Julià de Lòria",
10        "es": "San Julián de Loria",
11        "fr": "Sant Julià de Lòria",
12        "it": "Parrocchia di Sant Julià de Lòria",
13        "zh": "圣胡利娅-德洛里亚"
14    },                 
15    "iso": "06",    // iso3166-2 code
16    "fips": "06",   // FIPS code
17    // next key is exist only in `_ref` exports
18    "reference": {
19        "geonames": 3039162,                   // geonames.org
20        "openstreetmap": 2804759,              // openstreetmap relation id
21        "openstreetmap_level": 7,              // openstreetmap administrative division level
22        "wikipedia": "en:Sant_Julià_de_Lòria", // wikipedia article
23        "wof": null                            // WOF code 
24    }
25},

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.

No vulnerabilities found.

10

License

Determines if the project has defined a license.

10

Binary-Artifacts

Determines if the project has generated executable (binary) artifacts in the source repository.

3

Code-Review

Determines if the project requires human code review before pull requests (aka merge requests) are merged.

0

Maintained

Determines if the project is "actively maintained".

0

CII-Best-Practices

Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.

0

Security-Policy

Determines if the project has published a security policy.

0

Fuzzing

Determines if the project uses fuzzing.

0

Branch-Protection

Determines if the default and release branches are protected with GitHub's branch protection settings.

0

SAST

Determines if the project uses static code analysis.

0

Vulnerabilities

Determines if the project has open, known unfixed vulnerabilities.

Reason

39 existing vulnerabilities detected

Details

Warn: Project is vulnerable to: GHSA-6chw-6frg-f759
Warn: Project is vulnerable to: GHSA-v88g-cgmw-v5xw
Warn: Project is vulnerable to: GHSA-93q8-gq69-wqmw
Warn: Project is vulnerable to: GHSA-67hx-6x53-jw92
Warn: Project is vulnerable to: GHSA-cwfw-4gq5-mrqx
Warn: Project is vulnerable to: GHSA-g95f-p29q-9xw4
Warn: Project is vulnerable to: GHSA-grv7-fg5c-xmjg
Warn: Project is vulnerable to: GHSA-9vvw-cc9w-f27h
Warn: Project is vulnerable to: GHSA-gxpj-cx7g-858c
Warn: Project is vulnerable to: GHSA-w573-4hg7-7wgq
Warn: Project is vulnerable to: GHSA-h6ch-v84p-w6p9
Warn: Project is vulnerable to: GHSA-4gmj-3p3h-gm8h
Warn: Project is vulnerable to: GHSA-8r6j-v8pm-fqw3
Warn: Project is vulnerable to: MAL-2023-462
Warn: Project is vulnerable to: GHSA-qh2h-chj9-jffq
Warn: Project is vulnerable to: GHSA-qqgx-2p2h-9c37
Warn: Project is vulnerable to: GHSA-9c47-m6qq-7p4h
Warn: Project is vulnerable to: GHSA-282f-qqgm-c34q
Warn: Project is vulnerable to: GHSA-6c8f-qphg-qjgp
Warn: Project is vulnerable to: GHSA-jf85-cpcp-j695
Warn: Project is vulnerable to: GHSA-p6mc-m468-83gw
Warn: Project is vulnerable to: GHSA-29mw-wpgm-hmr9
Warn: Project is vulnerable to: GHSA-35jh-r3h4-6jhm
Warn: Project is vulnerable to: GHSA-952p-6rrq-rcjv
Warn: Project is vulnerable to: GHSA-f8q6-p94x-37v3
Warn: Project is vulnerable to: GHSA-vh95-rmgr-6w4m
Warn: Project is vulnerable to: GHSA-xvch-5gv4-984h
Warn: Project is vulnerable to: GHSA-w7rc-rwvf-8q5r
Warn: Project is vulnerable to: GHSA-r683-j2x4-v87g
Warn: Project is vulnerable to: GHSA-hj48-42vr-x3v9
Warn: Project is vulnerable to: GHSA-c2qf-rxjj-qqgw
Warn: Project is vulnerable to: GHSA-4rq4-32rv-6wp6
Warn: Project is vulnerable to: GHSA-64g7-mvw6-v9qj
Warn: Project is vulnerable to: GHSA-3jfq-g458-7qm9
Warn: Project is vulnerable to: GHSA-r628-mhmh-qjhw
Warn: Project is vulnerable to: GHSA-9r2w-394v-53qc
Warn: Project is vulnerable to: GHSA-5955-9wpr-37jh
Warn: Project is vulnerable to: GHSA-qq89-hq3f-393p
Warn: Project is vulnerable to: GHSA-f5x3-32g6-xq36

Score

2.1

/10

Last Scanned on 2025-01-27

The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.

Learn More