node-location-timezone
Table of Contents
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
Intl
native library's supported timezones are used and fixed from original data (please see Intl.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
/CYN
Kosovo
: XK
/KOS
Somaliland
: 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
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 no null
values 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');
locationTimezone.findCapitalOfCountryIso('Jpn');
locationTimezone.findCapitalOfCountryIso();
findCapitalOfCountryName(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');
locationTimezone.findCapitalOfCountryName('the Republic of Tunisia');
locationTimezone.findCapitalOfCountryName();
findCountryByCapitalName(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é');
locationTimezone.findCountryByCapitalName('lome');
locationTimezone.findCountryByCapitalName();
findCountryByIso(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');
locationTimezone.findCountryByIso('Gab');
locationTimezone.findCountryByIso();
findCountryByName(name: string)
Find a country by its name.
name
<String> Country name (case insensitive).- Returns: <Country> | undefined
Examples:
locationTimezone.findCountryByName('Haiti');
locationTimezone.findCountryByName('iceland');
locationTimezone.findCountryByName();
getCapitals()
Get all country capitals.
NOTE:
Examples:
locationTimezone.getCapitals();
getCountries()
Get all countries.
NOTE:
-
Countries without a capital have the capital capital.name
and capital.nameAscii
set to the empty string and the capital.latitude
and capital.longitude
representing the country's coordinates.
-
Returns: <Country[]> Sorted by country name ascendant.
Examples:
locationTimezone.getCountries();
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');
locationTimezone.getCountryIso2CodeByIso3('GEO');
locationTimezone.getCountryIso2CodeByIso3('And');
locationTimezone.getCountryIso2CodeByIso3();
getCountryIso2Codes()
Get all country ISO 3166-1 alpha-2 codes.
- Returns: <String[]> Sorted by code ascendant.
Examples:
locationTimezone.getCountryIso2Codes();
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');
locationTimezone.getCountryIso3CodeByIso2('GE');
locationTimezone.getCountryIso3CodeByIso2('Ad');
locationTimezone.getCountryIso3CodeByIso2();
getCountryIso3Codes()
Get all country ISO 3166-1 alpha-3 codes.
- Returns: <String[]> Sorted by code ascendant.
Examples:
locationTimezone.getCountryIso3Codes();
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');
locationTimezone.isValidCountryIso('usa');
locationTimezone.isValidCountryIso('');
locationTimezone.isValidCountryIso();
locationTimezone.isValidCountryIso('US');
locationTimezone.isValidCountryIso('USA');
Locations
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:
Examples:
locationTimezone.findLocationsByCoordinates({
latitudeFrom: 5,
latitudeTo: 8,
longitudeFrom: 0,
longitudeTo: 1,
});
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');
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);
locationTimezone.findLocationsByCountryName('Arab', true);
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);
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);
locationTimezone.findLocationsByState('');
getLocations()
Get all locations.
- Returns: <Location[]> Sorted by city name ascendant.
Examples:
locationTimezone.getLocations();
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');
locationTimezone.findStateAnsiByFipsCode('');
findStateAnsiByGnisid(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');
locationTimezone.findStateAnsiByGnisid('');
findStateAnsiByName(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');
locationTimezone.findStateAnsiByName('');
findStateAnsiByUspsCode(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');
locationTimezone.findStateAnsiByUspsCode('');
getStatesAnsi()
Get all states ANSI (American National Standards Institute, USA states only).
- Returns: <StateAnsi[]> Sorted by name ascendant.
Examples:
locationTimezone.getStatesAnsi();
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');
locationTimezone.findTimezoneByCapitalOfCountryIso('');
findTimezoneByCapitalOfCountryName(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');
locationTimezone.findTimezoneByCapitalOfCountryName('');
findTimezoneByCityName(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');
locationTimezone.findTimezoneByCityName('Göteborg');
locationTimezone.findTimezoneByCityName('goteborg');
locationTimezone.findTimezoneByCityName('');
findTimezonesByCountryIso(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');
locationTimezone.findTimezonesByCountryIso('KAZ');
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');
locationTimezone.findTimezonesByCountryName('The Republic of Peru');
locationTimezone.findTimezonesByCountryName('');
getTimezones()
Get all timezones as per Intl
native library.
- Returns: <String[]> Sorted by name ascendant.
Examples:
locationTimezone.getTimezones();
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.