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/[email protected]/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

• countries-and-timezones
• location-by-ip

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