world-countries-capitals

---

Table of Contents

1. Introduction
2. Demos
3. Installation
4. How to use
5. Data model
6. Available methods
7. Contributing
8. Core Team
9. License

---

Introduction

World-Countries-Capitals is JavaScript Library that give access to static data of all countries in the world.

Currently available data for each country is:

• country - country name
• capital - capital city
• currency - currency that is used
• native_language - list of official languages that are used in country
• famous_for - list of things that makes country famous for
• phone_code - country dial-in (calling) code
• flag - image of country flag
• drive_direction - drive direction
• alcohol_prohibition - status of alcohol prohibition
• area - country size (square kilometers and square miles)
• continent - 2-letter code of continent where the country is
• iso - country ISO 3166-1 code (numeric, alpha-2, alpha-3)
• tld - country code top-level domain
• constitutional_form - official political system
• language_codes - list of langauge codes (combination of ISO 639-1 and ISO 3166-1 alpha-2)
• is_landlocked - information whether country is surrounded by one or more countries

You can check all changes in the project at releases page on Github or in changelog.

Feel free to give this project a ⭐️  if it helped you! 🤗

↑ Back to menu

---

Demos

Here are demos/examples created by community ❤️

• Vue.js demo
  • Search countries by a selected field
  • Created by @leodrk

↑ Back to menu

---

Installation

Install with NPM:

npm install world-countries-capitals

Install with Yarn:

yarn add world-countries-capitals

↑ Back to menu

---

How to use

Depends which way you choose to install this package, there might be a different way to use it.

• CommonJS:

  1// 1. Load _wcc_ Package
  2const wcc = require('world-countries-capitals')
  3
  4// 2. Use any _wcc_ Method
  5const randomCountryName = wcc.getRandomCountry()
  6
  7// 3. Play with returned data
  8console.log(randomCountryName) // Possible output: 'poland'

↑ Back to menu

---

Data model

Type definition of each Country {Object}:

1/**
2 * @typedef {Object} Country
3 * @property {String} country - Country name
4 * @property {String} capital - Capital city name
5 * @property {String} currency - Currency name
6 * @property {String[]} native_language - Array or native languages
7 * @property {String} famous_for - Comma separated favourites
8 * @property {String} phone_code - Phone prefix
9 * @property {String} flag - Flag image
10 * @property {String} drive_direction - Drive direction
11 * @property {String} alcohol_prohibition - Alcohol prohibition status
12 * @property {Object} area - Country size
13 * @property {Number} area.km2 - Country size in square kilometers
14 * @property {Number} area.mi2 - Country size in square miles
15 * @property {String} continent - Continent that country belong to
16 * @property {Object} iso - ISO 3166-1 standard codes
17 * @property {String} iso.numeric - 3-digit code
18 * @property {String} iso.alpha_2 - 2-letter code
19 * @property {String} iso.alpha_3 - 3-letter code
20 * @property {String} tld - Country code top-level domain
21 * @property {String} constitutional_form - Name of official political system
22 * @property {String[]} language_codes - Array of language codes
23 * @property {Boolean} is_landlocked - Is country surrounded by one or more countries
24 */

Sample Country {Object}:

1{
2	country: 'poland',
3	capital: 'warsaw',
4	currency: 'zloty',
5	native_language: ['polish'],
6	famous_for: 'pierogi and potatoes',
7	phone_code: '+48',
8	flag: 'https://flagpedia.net/data/flags/h80/pl.png',
9	drive_direction: 'right',
10	alcohol_prohibition: 'none',
11	area: {
12		km2: 312696,
13		mi2: 120733,
14	},
15	continent: 'eu',
16	iso: {
17		numeric: '616',
18		alpha_2: 'pl',
19		alpha_3: 'pol',
20	},
21	tld: '.pl',
22	constitutional_form: 'republic',
23	language_codes: ['pl-PL'],
24	is_landlocked: false
25}

↑ Back to menu

---

Available methods

After importing world-countries-capitals Package, you have access to methods listed below:

1/*
2 * Get list of all country names
3 * @returns {String[]}
4*/
5wcc.getAllCountries()

1/*
2 * Get all countries with details
3 * @returns {Country[]}
4*/
5wcc.getAllCountryDetails()

1/*
2 * Get random country name
3 * @returns {String}
4*/
5wcc.getRandomCountry()

1/*
2 * Get specific amount of random countries
3 * @param {Number} amount - amount of countries to get
4 * @returns {Country[]}
5*/
6wcc.getNRandomCountriesData(amount)
7// Example: wcc.getNRandomCountriesData(3)
8

1/*
2 * Get country details by its name
3 * @param {String} name - country name
4 * @returns {Country}
5*/
6wcc.getCountryDetailsByName(name)
7// Example: wcc.getCountryDetailsByName('poland')

1/*
2 * Get country details by its capital city
3 * @param {String} capital - name of capital city
4 * @returns {Country}
5*/
6wcc.getCountryDetailsByCapital(capital)
7// Example: wcc.getCountryDetailsByCapital('warsaw')

1/*
2 * Get all countries by specific language
3 * @param {String} language - language name
4 * @returns {Country[]}
5*/
6wcc.getCountriesByLanguage(language)
7// Example: wcc.getCountriesByLanguage('polish')

1/*
2 * Get all countries that are famous for specific thing
3 * @param {String} famousThing - thing that makes country famous for
4 * @returns {Country[]}
5*/
6wcc.getCountriesByFamousFor(famousThing)
7// Example: wcc.getCountriesByFamousFor('pierogi')

1/*
2 * Get all countries by specific drive direction
3 * @param {String} direction - drive direction (one of: 'left', 'right')
4 * @returns {Country[]}
5*/
6wcc.getCountriesByDriveDirection(direction)
7// Example: wcc.getCountriesByDriveDirection('left')

1/*
2 * Get all countries by alcohol prohibition type
3 * @param {String} type - prohibition type (one of: 'none', 'limited', 'regional', 'nationwide')
4 * @returns {Country[]}
5*/
6wcc.getCountriesByAlcoholProhibition(type)
7// Example: wcc.getCountriesByAlcoholProhibition('nationwide')

1/*
2 * Get all countries that are located on specific continent
3 * @param {String} code - 2-letter continent code (one of: 'AF', 'AN', 'AS', 'EU', 'NA', 'OC', 'SA')
4 * @returns {Country[]}
5*/
6wcc.getCountriesByContinent(code)
7// Example: wcc.getCountriesByContinent('eu')

1/*
2 * Get country found by one of _ISO 3166-1_ code type
3 * @param {String} isoType - ISO type (one of: 'numeric', 'alpha-2', 'alpha-3')
4 * @param {String} isoValue - ISO code of specific country that match to `isoType`
5 * @returns {Country}
6*/
7wcc.getCountryDetailsByISO(isoType, isoValue)
8// Example: wcc.getCountryDetailsByISO('numeric', '616')

1/*
2 * Get all countries by specific _ccTLD_
3 * @param {String} tld - name of the _country code top-level domain_ (including `.` character)
4 * @returns {Country[]}
5*/
6wcc.getCountriesByTLD(tld)
7// Example: wcc.getCountriesByTLD('.pl')

1/*
2 * Get all countries by specific constitutional form
3 * @param {String} form - name of country constitutional form
4 * @returns {Country[]}
5*/
6wcc.getCountriesByConstitutionalForm(form)
7// Example: wcc.getCountriesByConstitutionalForm('republic')

1/*
2 * Get all countries that are surrounded by one or more countries
3 * @param {Boolean} isLandLocked - is country landlocked
4 * @returns {Country[]}
5*/
6wcc.getCountriesByLandLock(isLandLocked)
7// Example: wcc.getCountriesByLandLock(true)

❗️ All params are NOT case sensitive so no matter how argument looks, the response will remain the same.

↑ Back to menu

---

Contributing

Contributions, issues and feature requests are always welcome!

Feel free to check our issues page to see all open issues. If this is your first time contributing to Open Source project, check out the contributing guidelines first.

You can also suggest a new feature by creating an issue. Please wait for confirmation before working on it.

↑ Back to menu

---

Core team

Vikrant Bhat

Damian Szczypka

If you'd like to see everyone who contributed to this project, view the contributions page!
Thank you to everyone who contributes! 🙌

↑ Back to menu

---

License

Copyright © 2020 Vikrant Bhat.
This project is MIT licensed.

↑ Back to menu

---