README

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.

License

MIT

Usage no npm install needed!