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. 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
 */

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
}

↑ 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)

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