countrily

Inspired by the work of the authors of countryjs, this is a Node.js module for returning data about countries but can also be run in the browser unlike the original project. Use this to get a list of countries (country list) and their corresponding meta data

Table of Contents

• Install
• Usage
• API
  • .info()
  • .states()
  • .provinces()
  • .name()
  • .altSpellings()
  • .area()
  • .borders()
  • .callingCodes()
  • .capital()
  • .currencies()
  • .demonym()
  • .flag()
  • .geoJSON()
  • .ISOcodes()
  • .languages()
  • .latlng()
  • .nativeName()
  • .population()
  • .region()
  • .subregion()
  • .timezones()
  • .tld()
  • .translations()
  • .wiki()
• Static methods
  • .all()
  • .shortnamesofall()
  • .lean()
• Disclaimer
• License (ISC)

Install

npm install countrily

Usage

To access one of the country properties available, you'll need to use one of the API methods listed below and pass a country in either way:

• Using the ISO-alpha2 code: var country = new Country('NG', 'ISO2') or var country = new Country('NG') (defaults)
• Using the ISO-alpha3 code: var country = new Country('NG', 'ISO3')
• From this you can just use any of the methods: country.states().

API

.info()

Returns all available information for a specified country.

var Countrily = require('countrily');
var nigeria = new Countrily('NGA', 'ISO3'); // 'ISO2', 'ISO3', 'name'
var nigeria = new Countrily('NG');  // Defaults to ISO2
nigeria.info();
// returns object,
// {
//     "name": "Nigeria",
//     "altSpellings": ["NG", "NGA", "Federal Republic of Nigeria"],
//     "area": 923768,
//     "borders": ["BEN","CMR","TCD","NER"],
//     "callingCodes": ["234"],
//     "capital": "Abuja",
//     "currencies": ["NGN"],
//     "demonym": "Nigerian",
//     ...
// }

.states()

Returns all states/provinces for a specified country.

var Countrily = require('countrily');
var nigeria = Countrily('NG', 'ISO2'); // 'ISO2', 'ISO3', 'name'.
var nigeria = Countrily('NG')
nigeria.states();
// returns array of states,
// [
//  "Adamawa",
//  ...
// ]

.provinces()

Alias of .states()

.name()

Returns name for a specified country

var Countrily = require('countrily');
var nigeria = Countrily('NGA', 'ISO3'); // 'ISO2', 'ISO3', 'name'
var nigeria = Countrily('NG'); // Defaults to 'ISO2'
country.name() // Defaults to 'ISO2'
// returns string
// "Nigeria"

.altSpellings()

Returns alternate spellings for the name of a specified country

nigeria.altSpellings()
// returns array of strings, alternate names
// ["NG","Nijeriya","Naíjíríà","Federal Republic of Nigeria"]

.area()

Returns area (km²) for a specified country

nigeria.area()
// returns number of square kilometer area
// 923768

.borders()

Returns bordering countries (ISO3) for a specified country

nigeria.borders() // Defaults to 'ISO2'
// returns array of strings, ISO3 codes of countries that border the given country
// ["BEN","CMR","TCD","NER"]

.callingCodes()

Returns international calling codes for a specified country

nigeria.callingCodes() // Defaults to 'ISO2'
// returns array of calling code strings
// ["234"]

.capital()

Returns capital city for a specified country

nigeria.capital()
// returns string
// "Abuja"

.currencies()

Returns official currencies for a specified country

nigeria.currencies()
// returns array of strings, currencies
// ["NGN"]

.demonym()

Returns the demonyms for a specified country

nigeria.demonym()
// returns string, name of residents
// "Nigerian"

.flag() - INCOMPLETE

Returns SVG link of the official flag for a specified country

nigeria.flag()
// returns string URL of CC licensed svg flag

.geoJSON()

Returns geoJSON for a specified country

nigeria.geoJSON()
// returns object of GeoJSON data

.ISOcodes()

Returns ISO codes for a specified country

nigeria.ISOcodes()
// returns object of ISO codes
// {
//   "alpha2": "NG",
//   "alpha3": "NGA"
// }

.languages()

Returns official languages for a specified country

nigeria.languages()
// returns array of language codes
// ["en"]

.latlng()

Returns approx latitude and longitude for a specified country

nigeia.latlng();
// returns array, approx latitude and longitude for country
// [10,8]

.nativeName()

Returns the name of the country in its native tongue

nigeria.nativeName();
// returns string, name of country in native language
// "Nigeria"

.population()

Returns approximate population for a specified country

nigeria.population();
// returns number, approx population
// 178517000

.region()

Returns general region for a specified country

nigeria.region();
// returns string
// "Africa"

.subregion()

Returns a more specific region for a specified country

nigeria.subregion();
// returns string
// "West Africa"

.timezones()

Returns all timezones for a specified country

nigeria.timezones();
// returns array of timezones

.tld()

Returns official top level domains for a specified country

nigeria.tld();
// returns array of top level domains specific to the country
// [".ng"]

.translations()

Returns translations for a specified country name in popular languages

nigeria.translations();
// returns object of translations of country name in major languages
// {
//   "de": "Nigeria",
//   "es": "Nigeria",
//   "fr": "Nigeria",
//   "ja": "ナイジェリア",
//   "it": "Nigeria"
// }

.wiki()

Returns link to wikipedia page for a specified country

nigeria.wiki();
// returns string URL of wikipedia article on country
// "http://en.wikipedia.org/wiki/Nigeria"

Static methods

Two static methods are exposed to return all data and shortnames

.all()

Return all country data. This will be super big. Not recommended.

var Countrily = require('countrily');
Countrily.all();
// returns array of objects,
// [{
//     "name": "Nigeria",
//     "altSpellings": ["NG", "NGA", "Federal Republic of Nigeria"],
//     "area": 923768,
//     "borders": ["BEN","CMR","TCD","NER"],
//     "callingCodes": ["234"],
//     "capital": "Abuja",
//     "currencies": ["NGN"],
//     "demonym": "Nigerian",
//     ...
// },
// ...]

.shortnamesofall()

Return an array of all the shortnames (ISO2) of all the countries.

var Countrily = require('countrily');
Countrily.shortnamesofall();

.lean(field)

Return an array of field entered.

const Countrily = require('countrily');
Countrily.lean('name');

['Afghanistan',
  'Albania',
  'Algeria',
  'American Samoa',
  'Angola',
  'Anguilla',
  'Antigua and Barbuda',
  'Argentina',
  'Armenia',
  'Aruba',
  ...]

Test

1. Make the changes you desire
2. Ensure all changes have a new test in the test/ folder, and run:

npm test

Disclaimer

This is being maintained in the contributor's free time, and as such, may contain minor errors in regards to some countries. Most of the information included in this library is what is listed on Wikipedia. If there is an error, please let me know and I will do my best to correct it.

License (ISC)

Copyright (c) 2017, Timi Aiyemo [email protected]

Please see licence file.