README.md

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
• neighbors - list of neighbor countries (ISO 3166-1 alpha-2 codes)

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. Load _wcc_ Package
   const wcc = require('world-countries-capitals')
  
   // 2. Use any _wcc_ Method
   const randomCountryName = wcc.getRandomCountry()
  
   // 3. Play with returned data
   console.log(randomCountryName) // Possible output: 'poland'

↑ Back to menu

---

Data model

Type definition of each Country {Object}:

/**
 * @typedef {Object} Country
 * @property {String} country - Country name
 * @property {String} capital - Capital city name
 * @property {String} currency - Currency name
 * @property {String[]} native_language - Array or native languages
 * @property {String} famous_for - Comma separated favourites
 * @property {String} phone_code - Phone prefix
 * @property {String} flag - Flag image
 * @property {String} drive_direction - Drive direction
 * @property {String} alcohol_prohibition - Alcohol prohibition status
 * @property {Object} area - Country size
 * @property {Number} area.km2 - Country size in square kilometers
 * @property {Number} area.mi2 - Country size in square miles
 * @property {String} continent - Continent that country belong to
 * @property {Object} iso - ISO 3166-1 standard codes
 * @property {String} iso.numeric - 3-digit code
 * @property {String} iso.alpha_2 - 2-letter code
 * @property {String} iso.alpha_3 - 3-letter code
 * @property {String} tld - Country code top-level domain
 * @property {String} constitutional_form - Name of official political system
 * @property {String[]} language_codes - Array of language codes
 * @property {Boolean} is_landlocked - Is country surrounded by one or more countries
 * @property {String[]} neighbors - Array of neighbor countries
 */

Sample Country {Object}:

{
	country: 'poland',
	capital: 'warsaw',
	currency: 'zloty',
	native_language: ['polish'],
	famous_for: 'pierogi and potatoes',
	phone_code: '+48',
	flag: 'https://flagpedia.net/data/flags/h80/pl.png',
	drive_direction: 'right',
	alcohol_prohibition: 'none',
	area: {
		km2: 312696,
		mi2: 120733,
	},
	continent: 'eu',
	iso: {
		numeric: '616',
		alpha_2: 'pl',
		alpha_3: 'pol',
	},
	tld: '.pl',
	constitutional_form: 'republic',
	language_codes: ['pl-PL'],
	is_landlocked: false,
	neighbors: ['by', 'cz', 'de', 'lt', 'ru', 'sk', 'ua'],
}

↑ Back to menu

---

Available methods

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

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

/*
 * Get all countries with details
 * @returns {Country[]}
*/
wcc.getAllCountryDetails()

/*
 * Get random country name
 * @returns {String}
*/
wcc.getRandomCountry()

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

/*
 * Get country details by its name
 * @param {String} name - country name
 * @returns {Country}
*/
wcc.getCountryDetailsByName(name)
// Example: wcc.getCountryDetailsByName('poland')

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

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

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

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

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

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

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

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

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

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

/**
 * Get list of neighbor countries
 * @param {String} country - name (or one of ISO 3166-1 code) of country
 * @returns {Country[]}
 */
wcc.getCountryNeighbors(country)
// Example: wcc.getCountryNeighbors('poland')

❗️ 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

---