countries-db

1.2.0 • Public • Published

countries-db

This is a minimalistic library to work with countries data.

Usage

NodeJS

Install with npm or yarn:

npm install --save countries-db

Browser

Add the following script to your project (only ~9kb):

<!-- Latest version -->
<script src="https://cdn.jsdelivr.net/gh/manuelmhtr/countries-db@latest/dist/index.js" type="text/javascript"></script>
 
<!-- Or specify a version -->
<script src="https://cdn.jsdelivr.net/gh/manuelmhtr/countries-db@v1.2.0/dist/index.js" type="text/javascript"></script>
 
<!-- This will export a variable named "countriesDb": -->
<script type="text/javascript">
  var data = countriesDb.getCountry('US');
  console.log(data);
</script> 

API

.getCountry(id, [property])

Returns a country referenced by its id.

If the property argument is specified, it will only return the value of that property.

Example

const countriesDB = require('countries-db');
 
const population = countriesDB.getCountry('MX', 'population');
console.log(population);
 
/*
Prints: 112468855
*/
 
const country = countriesDB.getCountry('MX');
console.log(country);
 
/*
Prints:
 
{
  id: 'MX',
  name: 'Mexico',
  officialName: 'The United Mexican States',
  emoji: '🇲🇽',
  emojiUnicode: 'U+1F1F2 U+1F1FD',
  iso2: 'MX',
  iso3: 'MEX',
  isoNumeric: '484',
  geonameId: 3996063,
  continentId: 'NA',
  population: 112468855,
  elevation: 2062,
  areaSqKm: 1972550,
  coordinates: {
    latitude: 23,
    longitude: -102
  },
  timezones: [
    'America/Bahia_Banderas',
    'America/Cancun',
    'America/Chihuahua',
    'America/Ensenada',
    'America/Hermosillo',
    'America/Matamoros',
    'America/Mazatlan',
    'America/Merida',
    'America/Mexico_City',
    'America/Monterrey',
    'America/Ojinaga',
    'America/Santa_Isabel',
    'America/Tijuana'
  ],
  domain: '.mx',
  currencyCode: 'MXN',
  currencyName: 'Peso',
  postalCodeFormat: '#####',
  postalCodeRegex: '^(\\d{5})$',
  phoneCode: '+52',
  neighborCountryIds: [ 'GT', 'US', 'BZ' ],
  languages: [ 'es' ],
  locales: [ 'es-MX' ]
}
*/

.getAllCountries()

Returns an object with the data of all countries.

Example

const countriesDB = require('countries-db');
 
const countries = countriesDB.getAllCountries();
console.log(countries);
 
/*
Prints:
 
{
  AD: {
    id: 'AD',
    name: 'Andorra',
    officialName: 'The Principality of Andorra',
    emoji: '🇦🇩',
    ...
  },
  AE: {
    id: 'AE',
     name: 'United Arab Emirates',
     officialName: 'The United Arab Emirates',
     emoji: '🇦🇪',
     ...
  },
  AF: {
    id: 'AF',
     name: 'Afghanistan',
     officialName: 'The Islamic Republic of Afghanistan',
     emoji: '🇦🇫',
     ...
  },
  AG: {
    id: 'AG',
     name: 'Antigua and Barbuda',
     officialName: 'Antigua and Barbuda',
     emoji: '🇦🇬',
     ...
  },
  ...
}
 
*/

Data models

Country

A country is defined by the following parameters:

Parameter Type Description
id String The country ISO 3166-1 code.
name String Preferred name of the country.
officialName String The offcial name of the country.
emoji String The Emoji flag of the country .
emojiUnicode String The Emoji flag Unicode of the country .
iso2 String ISO 3166-1 Alpha-2 code of the country.
iso3 String ISO 3166-1 Alpha-3 code of the country.
isoNumeric String ISO 3166-1 Numeric code of the country.
geonameId Integer Unique identifier given by GeoNames.
continentId String Id of the continent where the country is located. Valids are AF (Africa), AS (Asia), EU (Europe), NA (North America), OC (Oceania), SA (South America) and AN (Antarctica).
population Integer The approximate population living in the place.
elevation Float The approximate elevation from sea level. Value is expressed in meters.
areaSqKm Integer Total area of the country. Expressed in squared kilometers.
coordinates Object The geographic coordinates where the place is located.
coordinates.latitude Float Latitude component from the geographic coordinates of the place.
coordinates.longitude Float Longitude component from the geographic coordinates of the place.
timezones Array[String] The list of timezones used in the country.
domain String Top-level domain of the country.
currencyCode String Code of the official currency of the country.
currencyName String Name of the official currency of the country.
postalCodeFormat String Format of the postal codes used in the country.
postalCodeRegex String Regular expression to validate the postal codes used in the country.
phoneCode String The international phone code to call a number in the country.
neighborCountryIds Array[String] A list of ids of the countries that share border with it (neighbors).
languages Array[String] A list of languages spoken in the country.
locales Array[String] A list of locales (language + region) used in the country.
{
  id: 'DE',
  name: 'Germany',
  officialName: 'The Federal Republic of Germany',
  emoji: '🇩🇪',
  emojiUnicode: 'U+1F1E9 U+1F1EA',
  iso2: 'DE',
  iso3: 'DEU',
  isoNumeric: '276',
  geonameId: 2921044,
  continentId: 'EU',
  population: 81802257,
  elevation: 303,
  areaSqKm: 357021,
  coordinates: {
    latitude: 51.5,
    longitude: 10.5
  },
  timezones: [ 'Europe/Berlin', 'Europe/Busingen' ],
  domain: '.de',
  currencyCode: 'EUR',
  currencyName: 'Euro',
  postalCodeFormat: '#####',
  postalCodeRegex: '^(\\d{5})$',
  phoneCode: '+49',
  neighborCountryIds: [ 'CH', 'PL', 'NL', 'DK', 'BE', 'CZ', 'LU', 'FR', 'AT' ],
  languages: [ 'de' ],
  locales: [ 'de' ]
}

Related projects

Working on something more complex?

Meet Spott:

  • Search any city, country or administrative division in the world. By full strings or autocompletion.
  • Find a place by an IP address.
  • Access to more than 240,000 geographical places. In more than 20 languages.

Spott API for cities, countries and administrative divisions

License

MIT

Package Sidebar

Install

npm i countries-db

Weekly Downloads

474

Version

1.2.0

License

MIT

Unpacked Size

208 kB

Total Files

19

Last publish

Collaborators

  • manuelmhtr