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):
<!-- Latest version -->
<script
src="https://cdn.jsdelivr.net/gh/manuelmhtr/countries-and-timezones@latest/dist/index.min.js"
type="text/javascript"
></script>
<!-- Or specify a version -->
<script
src="https://cdn.jsdelivr.net/gh/manuelmhtr/countries-and-timezones@v3.7.1/dist/index.min.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, options = {})
Returns a country referenced by its id.
Accepts a parameter with options.
Example
const ct = require("countries-and-timezones");
const country = ct.getCountry("DE");
console.log(country);
/*
Prints:
{
id: 'DE',
name: 'Germany',
timezones: [ 'Europe/Berlin', 'Europe/Zurich' ]
}
*/
.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',
countries: [ 'US' ],
utcOffset: -480,
utcOffsetStr: '-08:00',
dstOffset: -420,
dstOffsetStr: '-07:00',
aliasOf: null
}
*/
.getAllCountries(options = {})
Returns an object with the data of all countries.
Accepts a parameter with options.
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/Puerto_Rico' ]
},
...
}
*/
.getAllTimezones(options = {})
Returns an object with the data of all timezones.
Accepts a parameter with options.
Example
const ct = require("countries-and-timezones");
const timezones = ct.getAllTimezones();
console.log(timezones);
/*
Prints:
{
"Africa/Abidjan": {
"name": "Africa/Abidjan",
"countries": [
"CI", "BF", "GH",
"GM", "GN", "ML",
"MR", "SH", "SL",
"SN", "TG"
],
"utcOffset": 0,
"utcOffsetStr": "+00:00",
"dstOffset": 0,
"dstOffsetStr": "+00:00",
"aliasOf": null
},
"Africa/Algiers": {
"name": "Africa/Algiers",
"countries": [
"DZ"
],
"utcOffset": 60,
"utcOffsetStr": "+01:00",
"dstOffset": 60,
"dstOffsetStr": "+01:00",
"aliasOf": null
},
"Africa/Bissau": {
"name": "Africa/Bissau",
"countries": [
"GW"
],
"utcOffset": 0,
"utcOffsetStr": "+00:00",
"dstOffset": 0,
"dstOffsetStr": "+00:00",
"aliasOf": null
},
...
}
*/
.getTimezonesForCountry(id, options = {})
Returns an array with all the timezones of a country given its id.
Accepts a parameter with options.
Example
const ct = require("countries-and-timezones");
const timezones = ct.getTimezonesForCountry("MX");
console.log(timezones);
/*
Prints:
[
{
"name": "America/Bahia_Banderas",
"countries": [ "MX" ],
"utcOffset": -360,
"utcOffsetStr": "-06:00",
"dstOffset": -300,
"dstOffsetStr": "-05:00",
"aliasOf": null
},
{
"name": "America/Cancun",
"countries": [ "MX" ],
"utcOffset": -300,
"utcOffsetStr": "-05:00",
"dstOffset": -300,
"dstOffsetStr": "-05:00",
"aliasOf": null
},
{
"name": "America/Chihuahua",
"countries": [ "MX" ],
"utcOffset": -420,
"utcOffsetStr": "-07:00",
"dstOffset": -360,
"dstOffsetStr": "-06:00",
"aliasOf": null
},
...
}
*/
.getCountriesForTimezone(name, options = {})
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.
Accepts a parameter with options.
Example
const ct = require("countries-and-timezones");
const timezone = ct.getCountriesForTimezone("Europe/Zurich");
console.log(timezone);
/*
Prints:
[
{
"id": "CH",
"name": "Switzerland",
"timezones": [
"Europe/Zurich"
]
},
{
"id": "DE",
"name": "Germany",
"timezones": [
"Europe/Berlin",
"Europe/Zurich"
]
},
{
"id": "LI",
"name": "Liechtenstein",
"timezones": [
"Europe/Zurich"
]
}
]
*/
.getCountryForTimezone(name, options = {})
Returns a the most relevant country (due to its geographical location) that uses a timezone given its name.
Accepts a parameter with options.
Example
const ct = require("countries-and-timezones");
const timezone = ct.getCountryForTimezone("Europe/Zurich");
console.log(timezone);
/*
Prints:
{
"id": "CH",
"name": "Switzerland",
"timezones": [
"Europe/Zurich"
]
}
*/
options
Available options for functions are:
| Parameter | Type | Description |
| ------------ | ------- | -------------------------------------------------------------------------------------------------------------------- |
| deprecated | Boolean | Indicates if the result should include deprecated timezones or not. By default no deprecated timezones are included. |
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: [
'America/Bahia_Banderas',
'America/Cancun',
'America/Chihuahua',
'America/Hermosillo',
'America/Matamoros',
'America/Mazatlan',
'America/Merida',
'America/Mexico_City',
'America/Monterrey',
'America/Ojinaga',
'America/Tijuana'
]
}
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. |
| deprecated | Boolean | true when the timezone has been deprecated, otherwise this property is not returned. |
{
name: 'Asia/Tel_Aviv',
countries: [ 'IL' ],
utcOffset: 120,
utcOffsetStr: '+02:00',
dstOffset: 180,
dstOffsetStr: '+03:00',
aliasOf: 'Asia/Jerusalem',
deprecated: true
}
Related projects
Support
Consider sponsoring this project.
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
