iso3166-helper
v1.0.2
Published
Provides utilities to work with regions, states, and sub-regions. It allows fetching regions and sub-regions by their codes and offers functionality to retrieve all sub-regions belonging to a specific region or state.
Downloads
26
Maintainers
Readme
iso3166-helper
This NPM module provides utilities to work with regions, states, and subregions using the ISO 3166 standard.
it's a set of utilities to work with regions, states, and subregions. Bundled with a dataset containing 250 Countries, 3766 Regions and 1301 Subregions
Installation
To install the module, run:
npm install iso3166-helper
Usage
Below are examples of how to use the functions provided by this module.
Importing the Module
import {getRegion, getCountry, getCountryName, getSubRegion, getSubRegionsby} from 'iso3166-helper';
Functions
- validateCode()
- getTree()
- isChildOf()
- getCountry()
- getRegion()
- getSubRegion()
- getSubRegionsby()
- getCountryName()
validateCode
This function checks if a code is valid.
validateCode(code: string)
Returns:
- The type of code (country, region, subregion) or false if the code is invalid.
Parameters:
code
(string): The code to validate.
Example:
console.log(validateCode("IT")); // Output: "country"
console.log(validateCode("IT-45")); // Output: "region"
console.log(validateCode("IT-RA")); // Output: "subregion"
console.log(validateCode("IT-ABCDE")); // Output: false
isChildOf
This function checks if a code is a child of another code.
isChildOf(code: string, parent: string)
Returns:
- True if both codes are valid and if the code is a child of the parent code; otherwise, false.
Parameters:
code
(string): The code to be compared with the parent.parent
(string): The parent code.
Example:
console.log(isChildOf("IT-BO", "IT-45")); // Output: true
console.log(isChildOf("IT-45", "IT")); // Output: true
console.log(isChildOf("IT-45", "ABC")); // Output: false
getTree
This function retrieves a tree of regions and subregions.
getTree()
Returns:
- An object containing the tree of regions and subregions.
- Each region is represented as an object with the following properties:
code
(string): The code of the region.
int
(string): The name of the country.
original
(string): The original name of the country.
region
(object): The code of the parent region.
code
(string): The code of the region.
subregions
(object): an object of subregions, code and name as key and value pairs.
Example:
const tree = getTree();
/* {
...
IT: {
code: "IT",
int: "Italy",
original: "Italy",
region: {
name: 'Emilia-Romagna',
code: 'IT-45',
subregions: {
'IT-BO': 'Bologna',
'IT-FC': 'Forlì-Cesena',
'IT-FE': 'Ferrara',
'IT-MO': 'Modena',
'IT-PC': 'Piacenza',
'IT-PR': 'Parma',
'IT-RA': 'Ravenna',
'IT-RE': 'Reggio Emilia',
'IT-RN': 'Rimini'
}
},
...
}
...
}
*/
getCountry
This function retrieves the details for the regions of a country given its iso2 code.
getCountry(code: string)
Parameters:
code
(string): The ISO2 code of the country.
Returns:
- An array of objects containing the code and the name of the regions in the country as key-value pairs.
Example:
const regions = getCountry("IT");
console.log(Object.values(regions));
// Output: [ 'Piemonte', "Valle d'Aosta, Val d'Aoste", 'Lombardia', 'Trentino-Alto Adige, Trentino-Südtirol', 'Veneto', 'Friuli Venezia Giulia', 'Liguria', 'Emilia-Romagna', 'Toscana', 'Umbria', 'Marche', 'Lazio', 'Abruzzo', 'Molise', 'Campania', 'Puglia', 'Basilicata', 'Calabria', 'Sicilia', 'Sardegna' ]
getRegion
This function retrieves the name of a region given its code.
getRegion(code: string)
Parameters:
code
(string): The code of the region (e.g., "IT-45").
Returns:
- The name of the region.
Example:
const region = getRegion("IT-45");
console.log(region); // Output: "Emilia-Romagna"
getSubRegion
This function retrieves the details of a sub-region given its code.
getSubRegion(code: string)
Parameters:
code
(string): The code of the sub-region (e.g., "IT-BO").
Returns:
- An object containing the dataset of the sub-region (e.g., { countryName: 'Italy', name: "Bologna", region: "IT-45", regionName: 'Emilia-Romagna', country: "IT" }).
Example:
const subRegion = getSubRegion("IT-BO");
console.log(subRegion); // Output: { countryName: 'Italy', name: "Bologna", region: "IT-45", regionName: 'Emilia-Romagna', country: "IT" }
getSubRegionsby
This function retrieves all sub-regions belonging to a specific region or state.
getSubRegionsby(code: string, type: "region" | "state")
Parameters:
code
(string): The code of the region or state.type
("region" | "state"): The type of code provided.
Returns:
- An array of sub-region details.
Example:
const subRegions = getSubRegionsby("IT-45", "region");
console.log(subRegions);
/* Output:
[
{ code: 'IT-BO', name: "Bologna", region: "IT-45", state: "IT" },
{ code: 'IT-FC', name: "Forlì-Cesena", region: "IT-45", state: "IT" },
...
]
*/
const ItalianRegions = getSubRegionsby("IT", "state").map((value) => value.name);
console.log(ItalianRegions);
/* Output:
[
'Agrigento', 'Alessandria', 'Ancona',
'Ascoli Piceno', "L'Aquila", 'Arezzo',
...
]
*/
const subRegionsCodes = getSubRegionsby("IT", "country").map((value) => value.subregionCode.slice(3))
console.log(subRegionsCodes);
/* Output:
[
'AG', 'AL', 'AN', 'AP', 'AQ', 'AR', 'AT', 'AV', 'BA', 'BG',
'BI', 'BL', 'BN', 'BO', 'BR', 'BS', 'BT', 'BZ', 'CA', 'CB',
...
]
*/
getCountryName
This function retrieves the name of a country given its code.
getCountryName(code: string)
Parameters:
code
(string): The code of the country (e.g., "IT").type
("int" | "original"): optional. Whenever the name is returned in international format (e.g., "Italy") or in the original format (e.g., "Italia").
Returns:
- The name of the country.
Example:
const countryName = getCountryName("IT", "original");
console.log(countryName); // Output: "Italia"
Running Tests
To run the tests for this module, use the following command:
npm test
License
This module is licensed under the MIT License.
Contributing
Contributions are welcome! Please create a pull request or open an issue to discuss any changes.