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:
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! 🤗
Here are demos/examples created by community ❤️
Install with NPM:
npm install world-countries-capitals
Install with Yarn:
yarn add world-countries-capitals
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'
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'],
}
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.
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.
If you'd like to see everyone who contributed to this project,
view the contributions page!
Thank you to everyone who contributes! 🙌
Copyright © 2020 Vikrant Bhat.
This project is MIT licensed.