countries-and-timezones
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):
<script src="https://cdn.jsdelivr.net/gh/manuelmhtr/countries-and-timezones@latest/dist/index.min.js" type="text/javascript"></script>
<script src="https://cdn.jsdelivr.net/gh/manuelmhtr/countries-and-timezones@v3.2.1/dist/index.min.js" type="text/javascript"></script>
<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);
.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);
.getAllCountries()
Returns an object with the data of all countries.
Example
const ct = require('countries-and-timezones');
const countries = ct.getAllCountries();
console.log(countries);
.getAllTimezones()
Returns an object with the data of all timezones.
Example
const ct = require('countries-and-timezones');
const timezones = ct.getAllTimezones();
console.log(timezones);
.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);
.getCountriesForTimezone(name)
Returns a list of the countries that uses a timezone given its name
. When a timezone has multiple countries the first element is more relevant due to its geographical location.
Example
const ct = require('countries-and-timezones');
const timezone = ct.getCountriesForTimezone('Europe/Zurich');
console.log(timezone);
.getCountryForTimezone(name)
Returns a the most relevant country (due to its geographical location) that uses a timezone given its name
.
Example
const ct = require('countries-and-timezones');
const timezone = ct.getCountryForTimezone('Europe/Zurich');
console.log(timezone);
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. |
countries | [String] | A list of ISO 3166-1 codes of the countries where it's used. Etc/* , GMT and UTC timezones don't have associated countries. |
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',
countries: [ 'IL' ],
utcOffset: 120,
utcOffsetStr: '+02:00',
dstOffset: 180,
dstOffsetStr: '+03:00',
aliasOf: 'Asia/Jerusalem'
}
Related projects
You / your company could be the first.
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