countries-and-timezones

A minimalistic library to work with countries and timezones data. Updated with the IANA timezones database.

Usage

NodeJS

Install with npm or yarn:

npm install --save countries-and-timezones

Browser

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

<!-- Latest version -->
<script src="https://cdn.jsdelivr.net/gh/manuelmhtr/countries-and-timezones@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 "ct": -->
<script type="text/javascript">
  var data = ct.getCountry('MX');
  console.log(data);
</script>

API

.getCountry(id)

Returns a country referenced by its id.

Example

const ct = require('countries-and-timezones');

const country = ct.getCountry('DE');
console.log(country);

/*
Prints:

{
  id: 'DE',
  name: 'Germany',
  timezones: [ 'Europe/Busingen', 'Europe/Berlin' ]
}

*/

.getTimezone(name)

Returns a timezone referenced by its name.

Example

const ct = require('countries-and-timezones');

const timezone = ct.getTimezone('America/Los_Angeles');
console.log(timezone);

/*
Prints:

{
  name: 'America/Los_Angeles',
  country: 'US',
  utcOffset: -480,
  utcOffsetStr: '-08:00',
  dstOffset: -420,
  dstOffsetStr: '-07:00',
  aliasOf: null
}

*/

.getAllCountries()

Returns an object with the data of all countries.

Example

const ct = require('countries-and-timezones');

const countries = ct.getAllCountries();
console.log(countries);

/*
Prints:

{
  AD: {
    id: 'AD',
    name: 'Andorra',
    timezones: [ 'Europe/Andorra' ]
  },
  AE: {
    id: 'AE',
    name: 'United Arab Emirates',
    timezones: [ 'Asia/Dubai' ]
  },
  AF: {
    id: 'AF',
    name: 'Afghanistan',
    timezones: [ 'Asia/Kabul' ]
  },
  AG: {
    id: 'AG',
    name: 'Antigua and Barbuda',
    timezones: [ 'America/Antigua' ]
  },
  ...
}

*/

.getAllTimezones()

Returns an object with the data of all timezones.

Example

const ct = require('countries-and-timezones');

const timezones = ct.getAllTimezones();
console.log(timezones);

/*
Prints:

{
  'Africa/Bamako': {
    name: 'Africa/Bamako',
    country: 'ML',
    utcOffset: 0,
    utcOffsetStr: '+00:00',
    dstOffset: 0,
    dstOffsetStr: '+00:00',
    aliasOf: 'Africa/Abidjan'
  },
  'Africa/Banjul': {
    name: 'Africa/Banjul',
    country: 'GM',
    utcOffset: 0,
    utcOffsetStr: '+00:00',
    dstOffset: 0,
    dstOffsetStr: '+00:00',
    aliasOf: 'Africa/Abidjan'
  },
  'Africa/Conakry': {
    name: 'Africa/Conakry',
    country: 'GN',
    utcOffset: 0,
    utcOffsetStr: '+00:00',
    dstOffset: 0,
    dstOffsetStr: '+00:00',
    aliasOf: 'Africa/Abidjan'
  },
  ...
}

*/

.getTimezonesForCountry(id)

Returns an array with all the timezones of a country given its id.

Example

const ct = require('countries-and-timezones');

const timezones = ct.getTimezonesForCountry('MX');
console.log(timezones);

/*
Prints:

[
  {
    name: 'Mexico/BajaSur',
    country: 'MX',
    utcOffset: -420,
    utcOffsetStr: '-07:00',
    dstOffset: -360,
    dstOffsetStr: '-06:00',
    aliasOf: 'America/Mazatlan'
  },
  {
    name: 'Mexico/General',
    country: 'MX',
    utcOffset: -360,
    utcOffsetStr: '-06:00',
    dstOffset: -300,
    dstOffsetStr: '-05:00',
    aliasOf: 'America/Mexico_City'
  },
  {
    name: 'America/Ensenada',
    country: 'MX',
    utcOffset: -480,
    utcOffsetStr: '-08:00',
    dstOffset: -420,
    dstOffsetStr: '-07:00',
    aliasOf: 'America/Tijuana'
  },
  ...
}

*/

.getCountryForTimezone(name)

Returns the country that uses a timezone given its name.

Example

const ct = require('countries-and-timezones');

const timezone = ct.getCountryForTimezone('Asia/Tokyo');
console.log(timezone);

/*
Prints:

{
  id: 'JP',
  name: 'Japan',
  timezones: [ 'Asia/Tokyo' ]
}

*/

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.| |timezones|Array[String]|The list of timezones used in the country.|

{
  id: 'MX',
  name: 'Mexico',
  timezones: [
    'Mexico/BajaSur',
    'Mexico/General',
    'America/Ensenada',
    'America/Santa_Isabel',
    'Mexico/BajaNorte',
    'America/Bahia_Banderas',
    'America/Cancun',
    'America/Chihuahua',
    'America/Tijuana',
    'America/Hermosillo',
    'America/Matamoros',
    'America/Mazatlan',
    'America/Merida',
    'America/Mexico_City',
    'America/Monterrey',
    'America/Ojinaga'
  ]
}

Timezone

A timezone is defined by the following parameters:

| Parameter | Type | Description | | --------- | ---- | ----------- | |name|String|The name of the timezone, from tz database.| |country|String|The ISO 3166-1 code of the country where it's used. Etc/*, GMT and UTC timezones don't have and associated country.| |utcOffset|Number|The difference in minutes between the timezone and UTC.| |utcOffsetStr|String|The difference in hours and minutes between the timezone and UTC, expressed as string with format: ±[hh]:[mm].| |dstOffset|Number|The difference in minutes between the timezone and UTC during daylight saving time (DST). When utcOffset and dstOffset are the same, means that the timezone does not observe a daylight saving time.| |dstOffsetStr|String|The difference in hours and minutes between the timezone and UTC during daylight saving time (DST, expressed as string with format: ±[hh]:[mm].| |aliasOf|String|The name of a primary timezone in case this is an alias. null means this is a primary timezone.|

{
  name: 'Asia/Tel_Aviv',
  country: 'IL',
  utcOffset: 120,
  utcOffsetStr: '+02:00',
  dstOffset: 180,
  dstOffsetStr: '+03:00',
  aliasOf: 'Asia/Jerusalem'
}

Related projects

• countries-db: Minimalistic lib with countries data.
• location-by-ip: Get the location of any IP address.

Help

This project is maintained by a single person, considering supporting by:

• Sharing your feedback.
• Becoming a sponsor.

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