node-location-timezone
v1.1.0
Published
A performant library to get information about capitals, countries, locations (cities), states ANSI (USA) and get the timezone of a city, capital, coordinates, country, province or even state
Downloads
320
Maintainers
elysiumphaseReadme
node-location-timezone
Table of Contents
- Presentation
- Installation
- Technical information
- Requirements
- Usage
- Import
- Lib
- Capitals and Countries
- Capital interface
- Country interface
- findCapitalOfCountryIso(code: string)
- findCapitalOfCountryName(name: string)
- findCountryByCapitalName(name: string)
- findCountryByIso(code: string)
- findCountryByName(name: string)
- getCapitals()
- getCountries()
- getCountryIso2CodeByIso3(iso3: string)
- getCountryIso2Codes()
- getCountryIso3CodeByIso2(iso2: string)
- getCountryIso3Codes()
- isValidCountryIso(code: string)
- Locations
- States ANSI
- Timezones
- Capitals and Countries
- Errors
- Development
- Known issues
- Code of Conduct
- Contributing
- Support
- Security
- License
Presentation
A performant library to get information about capitals, countries, locations (cities), states ANSI (USA) and get the timezone of a city, capital, coordinates, country, province or even state.
Inspired by city-timezones and countries-capitals.
What differentiates this library from the ones mentioned above is:
- data compressed using zipson
- its quality of data controlled and updated:
- country names and list come from the United Nations and the World Factbook
- all alpha-2 and alpha-3 ISO 3166-1 country codes are referenced and fixed from original data
- all ANSI (American National Standards Institute) codes are referenced in the data
- only
Intlnative library's supported timezones are used and fixed from original data (please seeIntl.supportedValuesOf('timeZone')using the latest version of Node.js)
- multiple ways of getting information about:
- capitals
- countries and ISO codes
- locations (cities)
- states ANSI (USA)
- the different ways of getting a timezone, by:
- city
- capital
- coordinates
- country
- province
- state
- using TypeScript, clear interfaces and documentation
- tested.
Important notes:
- 3 non-official countries have been added special codes not referenced in the ISO 3166-1:
Northern Cyprus:XC/CYNKosovo:XK/KOSSomaliland:XS/SOL
- coordinates are in decimals.
Please feel free to contribute by adding or fixing locations, country ISO 3166 alpha-2 codes, country ISO 3166-1 alpha-3 codes or capitals in the corresponding file.
Installation
npm install --save node-location-timezone
Technical information
Stack
- Language: JavaScript ES6/ES7
- Node.js >= 14.5.0
- TypeScript >= 5 (for development)
Code quality
Code style follows Airbnb JavaScript Best Practices using ESLint.
Tests
Jest for unit testing.
Security
- Code security and most precisely module dependencies can be audited running
npm audit.
Requirements
- See Stack
Usage
Import
import locationTimezone from 'node-location-timezone';
const locationTimezone = require('node-location-timezone');Lib
locationTimezone<Object> with the following properties.
NOTE:
- each attribute as defined in the interfaces has the empty string
''set if the data is unavailable meaning nonullvalues can be found.
Capitals and Countries
Capital interface
name<String>nameAscii<String>latitude<Number>longitude<Number>province<String>state<String> Official United States Postal Service (USPS) code for the US.timezone<String>country?<Country>
Country interface
name<String>officialName<String>iso2<String>iso3<String>timezones<String[]>capital?<Capital>
findCapitalOfCountryIso(code: string)
Find the capital of a country by its country ISO 3166-1 alpha-2 or alpha-3 code.
code<String> Country ISO code (case insensitive).- Returns: <Capital> | undefined
Examples:
locationTimezone.findCapitalOfCountryIso('US');
/*{
name: 'Washington, D.C.',
nameAscii: 'Washington, D.C.',
country: {
name: 'United States of America',
officialName: 'The United States of America',
iso2: 'US',
iso3: 'USA',
timezones: [
'America/Adak', 'America/Anchorage',
'America/Boise', 'America/Chicago',
'America/Denver', 'America/Detroit',
'America/Indianapolis', 'America/Juneau',
'America/Los_Angeles', 'America/Louisville',
'America/Menominee', 'America/New_York',
'America/Nome', 'America/Phoenix',
'America/Sitka', 'America/Yakutat',
'Pacific/Honolulu'
]
},
latitude: 38.89954938,
longitude: -77.00941858,
province: 'District of Columbia',
state: 'DC',
timezone: 'America/New_York'
*/
locationTimezone.findCapitalOfCountryIso('Jpn');
/*{
name: 'Tokyo',
nameAscii: 'Tokyo',
country: {
name: 'Japan',
officialName: 'Japan',
iso2: 'JP',
iso3: 'JPN',
timezones: [ 'Asia/Tokyo' ]
},
latitude: 35.68501691,
longitude: 139.7514074,
province: 'Tokyo',
state: '',
timezone: 'Asia/Tokyo'
}*/
locationTimezone.findCapitalOfCountryIso(); // undefinedfindCapitalOfCountryName(name: string)
Find the capital of a country by its name.
name<String> Country name (case insensitive).- Returns: <Capital> | undefined
Examples:
locationTimezone.findCapitalOfCountryName('Türkiye');
/*{
name: 'Ankara',
nameAscii: 'Ankara',
country: {
name: 'Türkiye',
officialName: 'The Republic of Türkiye',
iso2: 'TR',
iso3: 'TUR',
timezones: [ 'Europe/Istanbul' ]
},
latitude: 39.92723859,
longitude: 32.86439164,
province: 'Ankara',
state: '',
timezone: 'Europe/Istanbul'
}*/
locationTimezone.findCapitalOfCountryName('the Republic of Tunisia');
/*{
name: 'Tunis',
nameAscii: 'Tunis',
country: {
name: 'Tunisia',
officialName: 'The Republic of Tunisia',
iso2: 'TN',
iso3: 'TUN',
timezones: [ 'Africa/Tunis' ]
},
latitude: 36.80277814,
longitude: 10.1796781,
province: 'Tunis',
state: '',
timezone: 'Africa/Tunis'
}*/
locationTimezone.findCapitalOfCountryName(); // undefinedfindCountryByCapitalName(name: string)
Find a country by its capital name.
name<String> Capital name (case insensitive, utf-8 or ascii).- Returns: <Country> | undefined
Examples:
locationTimezone.findCountryByCapitalName('Lomé');
/*{
name: 'Togo',
officialName: 'The Togolese Republic',
iso2: 'TG',
iso3: 'TGO',
timezones: [ 'Africa/Lome' ],
capital: {
name: 'Lomé',
nameAscii: 'Lome',
latitude: 6.131937072,
longitude: 1.222757119,
province: 'Maritime',
state: '',
timezone: 'Africa/Lome'
}
}*/
locationTimezone.findCountryByCapitalName('lome');
/*{
name: 'Togo',
officialName: 'The Togolese Republic',
iso2: 'TG',
iso3: 'TGO',
timezones: [ 'Africa/Lome' ],
capital: {
name: 'Lomé',
nameAscii: 'Lome',
latitude: 6.131937072,
longitude: 1.222757119,
province: 'Maritime',
state: '',
timezone: 'Africa/Lome'
}
}*/
locationTimezone.findCountryByCapitalName(); // undefinedfindCountryByIso(code: string)
Find a country by its country ISO 3166-1 alpha-2 or alpha-3 code.
code<String> Country ISO code (case insensitive).- Returns: <Country> | undefined
Examples:
locationTimezone.findCountryByIso('th');
/*{
name: 'Thailand',
officialName: 'The Kingdom of Thailand',
iso2: 'TH',
iso3: 'THA',
timezones: [ 'Asia/Bangkok' ],
capital: {
name: 'Bangkok',
nameAscii: 'Bangkok',
latitude: 13.74999921,
longitude: 100.5166447,
province: 'Bangkok Metropolis',
state: '',
timezone: 'Asia/Bangkok'
}
}*/
locationTimezone.findCountryByIso('Gab');
/*{
name: 'Gabon',
officialName: 'The Gabonese Republic',
iso2: 'GA',
iso3: 'GAB',
timezones: [ 'Africa/Libreville', 'Africa/Malabo' ],
capital: {
name: 'Libreville',
nameAscii: 'Libreville',
latitude: 0.38538861,
longitude: 9.457965046,
province: 'Estuaire',
state: '',
timezone: 'Africa/Libreville'
}
}*/
locationTimezone.findCountryByIso(); // undefinedfindCountryByName(name: string)
Find a country by its name.
name<String> Country name (case insensitive).- Returns: <Country> | undefined
Examples:
locationTimezone.findCountryByName('Haiti');
/*{
name: 'Haiti',
officialName: 'The Republic of Haiti',
iso2: 'HT',
iso3: 'HTI',
timezones: [ 'America/Port-au-Prince' ],
capital: {
name: 'Port-au-Prince',
nameAscii: 'Port-au-Prince',
latitude: 18.5410246,
longitude: -72.33603459,
province: 'Ouest',
state: '',
timezone: 'America/Port-au-Prince'
}
}*/
locationTimezone.findCountryByName('iceland');
/*{
name: 'Iceland',
officialName: 'Iceland',
iso2: 'IS',
iso3: 'ISL',
timezones: [ 'Atlantic/Reykjavik' ],
capital: {
name: 'Reykjavík',
nameAscii: 'Reykjavik',
latitude: 64.15002362,
longitude: -21.95001449,
province: 'Suðurnes',
state: '',
timezone: 'Atlantic/Reykjavik'
}
}*/
locationTimezone.findCountryByName(); // undefinedgetCapitals()
Get all country capitals.
NOTE:
Countries without a capital have
cityandcityAsciiset to the empty string.Returns: <Capital[]> Sorted by country name ascendant.
Examples:
locationTimezone.getCapitals();
/*
[
// ...
{
name: 'Bissau',
nameAscii: 'Bissau',
country: {
name: 'Guinea-Bissau',
officialName: 'The Republic of Guinea-Bissau',
iso2: 'GW',
iso3: 'GNB',
timezones: [ 'Africa/Bissau' ]
},
latitude: 11.86502382,
longitude: -15.59836084,
province: 'Bissau',
state: '',
timezone: 'Africa/Bissau'
},
{
name: 'Georgetown',
nameAscii: 'Georgetown',
country: {
name: 'Guyana',
officialName: 'The Co-operative Republic of Guyana',
iso2: 'GY',
iso3: 'GUY',
timezones: [ 'America/Guyana' ]
},
latitude: 6.801973693,
longitude: -58.16702865,
province: 'Demerara-Mahaica',
state: '',
timezone: 'America/Guyana'
},
// ...
]
*/getCountries()
Get all countries.
NOTE:
Countries without a capital have the capital
capital.nameandcapital.nameAsciiset to the empty string and thecapital.latitudeandcapital.longituderepresenting the country's coordinates.Returns: <Country[]> Sorted by country name ascendant.
Examples:
locationTimezone.getCountries();
/*
[
// ...
{
name: 'Faroe Islands',
officialName: 'The Faroe Islands',
iso2: 'FO',
iso3: 'FRO',
timezones: [ 'Atlantic/Faeroe' ],
capital: {
name: 'Tórshavn',
nameAscii: 'Torshavn',
latitude: 62.03002382,
longitude: -6.820033611,
province: 'Eysturoyar',
state: '',
timezone: 'Atlantic/Faeroe'
}
},
{
name: 'Fiji',
officialName: 'The Republic of Fiji',
iso2: 'FJ',
iso3: 'FJI',
timezones: [ 'Pacific/Fiji' ],
capital: {
name: 'Suva',
nameAscii: 'Suva',
latitude: -18.13301593,
longitude: 178.4417073,
province: 'Central',
state: '',
timezone: 'Pacific/Fiji'
}
},
// ...
]
*/getCountryIso2CodeByIso3(iso3: string)
Get the country ISO 3166-1 alpha-2 code related to an alpha-3 code.
iso3<String> Country ISO 3166-1 alpha-3 code (case insensitive).- Returns: <String> | undefined
Examples:
locationTimezone.getCountryIso2CodeByIso3('usa'); // US
locationTimezone.getCountryIso2CodeByIso3('GEO'); // GE
locationTimezone.getCountryIso2CodeByIso3('And'); // AD
locationTimezone.getCountryIso2CodeByIso3(); // undefinedgetCountryIso2Codes()
Get all country ISO 3166-1 alpha-2 codes.
- Returns: <String[]> Sorted by code ascendant.
Examples:
locationTimezone.getCountryIso2Codes();
/*
[
'AD', 'AE', 'AF', 'AG', 'AI', 'AL', 'AM', 'AO', 'AQ', 'AR',
'AS', 'AT', 'AU', 'AW', 'AX', 'AZ', 'BA', 'BB', 'BD', 'BE',
// ...
]
*/getCountryIso3CodeByIso2(iso2: string)
Get the country ISO 3166-1 alpha-3 code related to an alpha-2 code.
iso2<String> Country ISO 3166-1 alpha-2 code (case insensitive).- Returns: <String> | undefined
Examples:
locationTimezone.getCountryIso3CodeByIso2('us'); // USA
locationTimezone.getCountryIso3CodeByIso2('GE'); // GEO
locationTimezone.getCountryIso3CodeByIso2('Ad'); // AND
locationTimezone.getCountryIso3CodeByIso2(); // undefinedgetCountryIso3Codes()
Get all country ISO 3166-1 alpha-3 codes.
- Returns: <String[]> Sorted by code ascendant.
Examples:
locationTimezone.getCountryIso3Codes();
/*
[
'AFG', 'ALA', 'ALB', 'DZA', 'ASM', 'AND', 'AGO', 'AIA',
'ATA', 'ATG', 'ARG', 'ARM', 'ABW', 'AUS', 'AUT', 'AZE',
// ...
]
*/isValidCountryIso(code: string)
Whether the country ISO code is a valid ISO 3166-1 alpha-2 or alpha-3 code.
code<String> ISO code (case sensitive).- Returns: <Boolean>
Examples:
locationTimezone.isValidCountryIso('us'); // false
locationTimezone.isValidCountryIso('usa'); // false
locationTimezone.isValidCountryIso(''); // false
locationTimezone.isValidCountryIso(); // false
locationTimezone.isValidCountryIso('US'); // true
locationTimezone.isValidCountryIso('USA'); // trueLocations
Location interface
city<String>cityAscii<String>country<Country>latitude<Number>longitude<Number>province<String>state<String> Official United States Postal Service (USPS) code for the US.timezone<String>
findLocationsByCoordinates(coordinates: object)
Find locations based on coordinates.
NOTE:
At least one of each latitude/longitude boundary value is necessary.
coordinates<Object>latitudeFrom?<Number> Default:Number.NEGATIVE_INFINITY.latitudeTo?<Number> Default:Number.POSITIVE_INFINITY.longitudeFrom?<Number> Default:Number.NEGATIVE_INFINITY.longitudeTo?<Number> Default:Number.POSITIVE_INFINITY.
Returns: <Location[]> Sorted by city name ascendant.
Examples:
locationTimezone.findLocationsByCoordinates({
latitudeFrom: 5,
latitudeTo: 8,
longitudeFrom: 0,
longitudeTo: 1,
});
/*
[
{
city: 'Ho',
cityAscii: 'Ho',
country: {
name: 'Ghana',
officialName: 'The Republic of Ghana',
iso2: 'GH',
iso3: 'GHA',
timezones: [
'Africa/Accra'
]
},
latitude: 6.600409769,
longitude: 0.46998653,
province: 'Volta',
state: '',
timezone: 'Africa/Accra'
},
{
city: 'Tema',
cityAscii: 'Tema',
country: {
name: 'Ghana',
officialName: 'The Republic of Ghana',
iso2: 'GH',
iso3: 'GHA',
timezones: [
'Africa/Accra'
]
},
latitude: 5.640365009,
longitude: 0.010014606,
province: 'Greater Accra',
state: '',
timezone: 'Africa/Accra'
},
{
city: 'Kpalime',
cityAscii: 'Kpalime',
country: {
name: 'Togo',
officialName: 'The Togolese Republic',
iso2: 'TG',
iso3: 'TGO',
timezones: [
'Africa/Lome'
]
},
latitude: 6.900391458,
longitude: 0.630028441,
province: 'Platitudeeaux',
state: '',
timezone: 'Africa/Lome'
}
]
*/
// valid
locationTimezone.findLocationsByCoordinates({
latitudeFrom: 5,
longitudeTo: 1,
});
locationTimezone.findLocationsByCoordinates({}); // []findLocationsByCountryIso(code: string)
Find locations based on a country ISO 3166-1 alpha-2 or alpha-3 code.
code<String> Country ISO code (case insensitive).- Returns: <Location[]> Sorted by city name ascendant.
Examples:
locationTimezone.findLocationsByCountryIso('US');
/*
[
// ...
{
city: 'Wheeling',
cityAscii: 'Wheeling',
country: {
name: 'United States of America',
officialName: 'The United States of America',
iso2: 'US',
iso3: 'USA',
timezones: [
'America/Adak',
'America/Anchorage',
'America/Boise',
'America/Chicago',
'America/Denver',
'America/Detroit',
'America/Indianapolis',
'America/Juneau',
'America/Los_Angeles',
'America/Louisville',
'America/Menominee',
'America/New_York',
'America/Nome',
'America/Phoenix',
'America/Sitka',
'America/Yakutat',
'Pacific/Honolulu'
]
},
latitude: 40.06431032,
longitude: -80.72107833,
province: 'West Virginia',
state: 'WV',
timezone: 'America/New_York'
},
{
city: 'White Sulphur Springs',
cityAscii: 'White Sulphur Springs',
country: {
name: 'United States of America',
officialName: 'The United States of America',
iso2: 'US',
iso3: 'USA',
timezones: [
'America/Adak',
'America/Anchorage',
'America/Boise',
'America/Chicago',
'America/Denver',
'America/Detroit',
'America/Indianapolis',
'America/Juneau',
'America/Los_Angeles',
'America/Louisville',
'America/Menominee',
'America/New_York',
'America/Nome',
'America/Phoenix',
'America/Sitka',
'America/Yakutat',
'Pacific/Honolulu'
]
},
latitude: 37.79388043,
longitude: -80.30348108,
province: 'West Virginia',
state: 'WV',
timezone: 'America/New_York'
},
// ...
]
*/
locationTimezone.findLocationsByCountryIso(''); // []findLocationsByCountryName(name: string, partialMatch: boolean)
Find locations based on a country name.
name<String> Country name (case insensitive).partialMatch<Boolean> Whether to include partial matches. Default:false- Returns: <Location[]> Sorted by city name ascendant.
Examples:
locationTimezone.findLocationsByCountryName('French polynesia', true);
/*
[
{
city: 'Papeete',
cityAscii: 'Papeete',
country: {
name: 'French Polynesia',
officialName: 'French Polynesia',
iso2: 'PF',
iso3: 'PYF',
timezones: [ 'Pacific/Tahiti' ]
},
latitude: -17.53336261,
longitude: -149.5666694,
province: 'Tahiti',
state: '',
timezone: 'Pacific/Tahiti'
}
]
*/
locationTimezone.findLocationsByCountryName('Arab', true);
/*
[
// ...
{
city: 'Tartus',
cityAscii: 'Tartus',
country: {
name: 'Syrian Arab Republic',
officialName: 'The Syrian Arab Republic',
iso2: 'SY',
iso3: 'SYR',
timezones: [ 'Asia/Damascus' ]
},
latitude: 34.88463448,
longitude: 35.88658405,
province: 'Tartus',
state: '',
timezone: 'Asia/Damascus'
},
{
city: 'Abu Dhabi',
cityAscii: 'Abu Dhabi',
country: {
name: 'United Arab Emirates',
officialName: 'The United Arab Emirates',
iso2: 'AE',
iso3: 'ARE',
timezones: [ 'Asia/Dubai' ]
},
latitude: 24.46668357,
longitude: 54.36659338,
province: 'Abu Dhabi',
state: '',
timezone: 'Asia/Dubai'
},
// ...
]
*/
locationTimezone.findLocationsByCountryName(''); // []findLocationsByProvince(name: string, partialMatch: boolean)
Find locations based on a province (not recommended, unreliable data).
name<String> Province name (case insensitive).partialMatch<Boolean> Whether to include partial matches. Default:false- Returns: <Location[]> Sorted by city name ascendant.
Examples:
locationTimezone.findLocationsByProvince('Hokkaido', false);
/*
[
{
city: 'Asahikawa',
cityAscii: 'Asahikawa',
country: {
name: 'Japan',
officialName: 'Japan',
iso2: 'JP',
iso3: 'JPN',
timezones: [ 'Asia/Tokyo' ]
},
latitude: 43.75501528,
longitude: 142.3799808,
province: 'Hokkaido',
state: '',
timezone: 'Asia/Tokyo'
},
{
city: 'Hakodate',
cityAscii: 'Hakodate',
country: {
name: 'Japan',
officialName: 'Japan',
iso2: 'JP',
iso3: 'JPN',
timezones: [ 'Asia/Tokyo' ]
},
latitude: 41.79497988,
longitude: 140.7399776,
province: 'Hokkaido',
state: '',
timezone: 'Asia/Tokyo'
},
// ...
]
*/
locationTimezone.findLocationsByProvince(''); // []findLocationsByState(name: string, partialMatch: boolean)
Find locations based on the state name.
name<String> State name (case insensitive, official United States Postal Service (USPS) code for the US).partialMatch<Boolean> Whether to include partial matches. Default:false- Returns: <Location[]> Sorted by city name ascendant.
Examples:
locationTimezone.findLocationsByState('ct', true);
/*
[
{
city: 'Bridgeport',
cityAscii: 'Bridgeport',
country: {
name: 'United States of America',
officialName: 'The United States of America',
iso2: 'US',
iso3: 'USA',
timezones: [
'America/Adak', 'America/Anchorage',
'America/Boise', 'America/Chicago',
'America/Denver', 'America/Detroit',
'America/Indianapolis', 'America/Juneau',
'America/Los_Angeles', 'America/Louisville',
'America/Menominee', 'America/New_York',
'America/Nome', 'America/Phoenix',
'America/Sitka', 'America/Yakutat',
'Pacific/Honolulu'
]
},
latitude: 41.17997866,
longitude: -73.19996118,
province: 'Connecticut',
state: 'CT',
timezone: 'America/New_York'
},
{
city: 'Hartford',
cityAscii: 'Hartford',
country: {
name: 'United States of America',
officialName: 'The United States of America',
iso2: 'US',
iso3: 'USA',
timezones: [
'America/Adak', 'America/Anchorage',
'America/Boise', 'America/Chicago',
'America/Denver', 'America/Detroit',
'America/Indianapolis', 'America/Juneau',
'America/Los_Angeles', 'America/Louisville',
'America/Menominee', 'America/New_York',
'America/Nome', 'America/Phoenix',
'America/Sitka', 'America/Yakutat',
'Pacific/Honolulu'
]
},
latitude: 41.77002016,
longitude: -72.67996708,
province: 'Connecticut',
state: 'CT',
timezone: 'America/New_York'
},
// ...
]
*/
locationTimezone.findLocationsByState(''); // []getLocations()
Get all locations.
- Returns: <Location[]> Sorted by city name ascendant.
Examples:
locationTimezone.getLocations();
/*
[
// ...
{
city: 'Vlore',
cityAscii: 'Vlore',
country: {
name: 'Albania',
officialName: 'The Republic of Albania',
iso2: 'AL',
iso3: 'ALB',
timezones: [ 'Europe/Tirane' ]
},
latitude: 40.47736005,
longitude: 19.49823075,
province: 'Vlorë',
state: '',
timezone: 'Europe/Tirane'
},
{
city: 'Abadla',
cityAscii: 'Abadla',
country: {
name: 'Algeria',
officialName: "The People's Democratic Republic of Algeria",
iso2: 'DZ',
iso3: 'DZA',
timezones: [ 'Africa/Algiers' ]
},
latitude: 31.01708478,
longitude: -2.733306317,
province: 'Béchar',
state: '',
timezone: 'Africa/Algiers'
},
// ...
]
*/States ANSI
StateAnsi interface
American National Standards Institute (ANSI), USA states only.
fipsCode<String> Federal Information Processing Standard (FIPS) code.gnisid<String> Geographic Names Information System Identifier (GNISID).name<String>uspsCode<String> Official United States Postal Service (USPS) code.
findStateAnsiByFipsCode(code: string)
Find the state's information based on the Federal Information Processing Standard (FIPS) State Code ANSI (American National Standards Institute, USA states only).
code<String> FIPS ANSI code (case insensitive, 2 chars).- Returns: <StateAnsi> | undefined
Examples:
locationTimezone.findStateAnsiByFipsCode('05');
/*
{
fipsCode: '05',
uspsCode: 'AR',
name: 'Arkansas',
gnisid: '00068085'
}
*/
locationTimezone.findStateAnsiByFipsCode(''); // undefinedfindStateAnsiByGnisid(id: string)
Find the state's information based on the Geographic Names Information System Identifier (GNISID) ANSI (American National Standards Institute, USA states only).
id<String> GNISID ANSI (case insensitive).- Returns: <StateAnsi> | undefined
Examples:
locationTimezone.findStateAnsiByGnisid('01779779');
/*
{
fipsCode: '08',
uspsCode: 'CO',
name: 'Colorado',
gnisid: '01779779'
}
*/
locationTimezone.findStateAnsiByGnisid(''); // undefinedfindStateAnsiByName(name: string)
Find the state's information by its name ANSI (American National Standards Institute, USA states only).
name<String> Name ANSI (case insensitive).- Returns: <StateAnsi> | undefined
Examples:
locationTimezone.findStateAnsiByName('Wyoming');
/*
{
fipsCode: '56',
uspsCode: 'WY',
name: 'Wyoming',
gnisid: '01779807'
}
*/
locationTimezone.findStateAnsiByName(''); // undefinedfindStateAnsiByUspsCode(code: string)
Find the state's information based on the official United States Postal Service (USPS) Code ANSI (American National Standards Institute, USA states only).
code<String> USPS ANSI code (case insensitive, 2 chars).- Returns: <StateAnsi> | undefined
Examples:
locationTimezone.findStateAnsiByUspsCode('NY');
/*
{
fipsCode: '36',
uspsCode: 'NY',
name: 'New York',
gnisid: '01779796'
}
*/
locationTimezone.findStateAnsiByUspsCode(''); // undefinedgetStatesAnsi()
Get all states ANSI (American National Standards Institute, USA states only).
- Returns: <StateAnsi[]> Sorted by name ascendant.
Examples:
locationTimezone.getStatesAnsi();
/*
[
// ...
{
fipsCode: '69',
uspsCode: 'MP',
name: 'Northern Mariana Islands',
gnisid: '01779809'
},
{
fipsCode: '72',
uspsCode: 'PR',
name: 'Puerto Rico',
gnisid: '01779808'
},
{
fipsCode: '74',
uspsCode: 'UM',
name: 'U.S. Minor Outlying Islands',
gnisid: '01878752'
},
{
fipsCode: '78',
uspsCode: 'VI',
name: 'U.S. Virgin Islands',
gnisid: '01802710'
}
]
*/Timezones
findTimezoneByCapitalOfCountryIso(code: string)
Find a timezone based on the capital of a country ISO 3166-1 alpha-2 or alpha-3 code.
code<String> Country ISO code (case insensitive).- Returns: <String> | undefined
Examples:
locationTimezone.findTimezoneByCapitalOfCountryIso('mx'); // 'America/Mexico_City'
locationTimezone.findTimezoneByCapitalOfCountryIso(''); // undefinedfindTimezoneByCapitalOfCountryName(name: string)
Find a timezone based on the capital of a country (name).
name<String> Country name (case insensitive).- Returns: <String> | undefined
Examples:
locationTimezone.findTimezoneByCapitalOfCountryName('new zealand'); // 'Pacific/Auckland'
locationTimezone.findTimezoneByCapitalOfCountryName(''); // undefinedfindTimezoneByCityName(name: string)
Find a timezone based on a city name.
name<String> City name (case insensitive, utf-8 or ascii).- Returns: <String> | undefined
Examples:
locationTimezone.findTimezoneByCityName('moscow'); // 'Europe/Moscow'
locationTimezone.findTimezoneByCityName('Göteborg'); // 'Europe/Stockholm'
locationTimezone.findTimezoneByCityName('goteborg'); // 'Europe/Stockholm'
locationTimezone.findTimezoneByCityName(''); // undefinedfindTimezonesByCountryIso(code: string)
Find timezones based on a country ISO 3166-1 alpha-2 or alpha-3 code.
code<String> Country ISO code (case insensitive).- Returns: <String[]> Sorted by name ascendant.
Examples:
locationTimezone.findTimezonesByCountryIso('mr');
/*
[
'Africa/Dakar',
'Africa/Nouakchott'
]
*/
locationTimezone.findTimezonesByCountryIso('KAZ');
/*
[
'Asia/Almaty',
'Asia/Aqtau',
'Asia/Aqtobe',
'Asia/Atyrau',
'Asia/Oral',
'Asia/Qyzylorda'
]
*/
locationTimezone.findTimezonesByCountryIso(''); // []findTimezonesByCountryName(name: string)
Find timezones based on a country name.
name<String> Country name (case insensitive).- Returns: <String[]> Sorted by name ascendant.
Examples:
locationTimezone.findTimezonesByCountryName('Nepal'); // [ 'Asia/Katmandu' ]
locationTimezone.findTimezonesByCountryName('The Republic of Peru');
/*
[
'America/Guayaquil',
'America/Lima'
]
*/
locationTimezone.findTimezonesByCountryName(''); // []getTimezones()
Get all timezones as per Intl native library.
- Returns: <String[]> Sorted by name ascendant.
Examples:
locationTimezone.getTimezones();
/*
[
'Africa/Abidjan',
'Africa/Accra',
'Africa/Addis_Ababa',
'Africa/Algiers',
'Africa/Asmera',
'Africa/Bamako',
'Africa/Bangui',
'Africa/Banjul',
'Africa/Bissau',
'Africa/Blantyre',
'Africa/Brazzaville',
// ...
]
*/Errors
None.
Development
Linting
npm run lint
Unit test
npm test
Building lib files from data
It is highly recommended to use the latest version of Node.js.
npm run build:files
Known issues
/
Code of Conduct
This project has a Code of Conduct. By interacting with this repository, organization, or community you agree to abide by its terms.
Contributing
Please take a moment to read our Contributing Guidelines if you haven't done so yet.
Some help is needed to improve the data:
- regarding the locations' province and state.
Support
Please see our Support page if you have any questions or for any help needed.
Security
For any security concerns or issues, please visit our Security Policy page.
License
MIT.