world-country-utils

A lightweight, TypeScript-first utility library for fetching country-specific data like currency codes, symbols, languages, calling codes, and more using ISO codes.

Installation

npm install world-country-utils

Usage

Importing

import { countryUtils, getCountryByISO, formatAmountByISO } from 'world-country-utils';

Functions

All functions require a mandatory ISO country code (case-insensitive). If the ISO code is not found in our database, an error will be thrown.

1. Get Country Name

getCountryByISO('IN'); // "India"

2. Get Currency Code

getCurrencyByISO('US'); // "USD"

3. Get Currency Symbol

getCurrencySymbolByISO('GB'); // "£"

4. Format Amount

Formats a numeric amount with the country's currency symbol and standard grouping.

formatAmountByISO(1234.56, 'IN'); // "₹1,234.56"
formatAmountByISO(500, 'US');     // "$500.00"

5. Get Language

getLanguageByISO('FR'); // "French"

6. Get Area Code (Calling Code)

getAreaCodeByISO('AE'); // "+971"

7. Get Phone Number Placeholder

getPlaceholderByISO('US'); // "e.g. +1 1234567890"

8. Get Pincode/Postal Code Regex

getPincodeRegexByISO('IN'); // /^[1-9][0-9]{5}$/

9. Get Map Center Coordinates

getCenterByISO('IN'); // { lat: 20.593684, lng: 78.96288 }

10. Get Timezone

getTimezoneByISO('IN'); // "Asia/Kolkata"

11. Get UTC Offset

getUTCOffsetByISO('IN'); // 5.5

12. Get All ISO Codes

getAllISOCodes(); // ["AF", "AL", "DZ", ...]

11. Find ISO by Country Name

getISOByName('India'); // "IN"

12. Validate ISO

isValidISO('US'); // true
isValidISO('XX'); // false

Error Handling

If you provide an invalid or unsupported ISO code, the functions will throw an error:

try {
  getCountryByISO('INVALID');
} catch (error) {
  console.error(error.message); // "Country with ISO code "INVALID" not found"
}

API Reference

| Function | Returns | Description | | --- | --- | --- | | getCountryByISO(iso) | string | Returns the full country name. | | getCurrencyByISO(iso) | string | Returns the ISO currency code (e.g., USD). | | getLanguageByISO(iso) | string | Returns the primary language. | | getCurrencySymbolByISO(iso) | string | Returns the currency symbol (e.g., $). | | getAreaCodeByISO(iso) | string | Returns the international calling code. | | getPlaceholderByISO(iso) | string | Returns a sample phone number placeholder. | | getPincodeRegexByISO(iso) | RegExp | Returns a Regex for postal code validation. | | getPhoneRegexByISO(iso) | RegExp | Returns a Regex for phone validation (if available). | | getCenterByISO(iso) | object | Returns { lat: number, lng: number }. | | getTimezoneByISO(iso) | string | Returns the country's primary timezone. | | getUTCOffsetByISO(iso) | number | Returns the UTC offset in hours. | | formatAmountByISO(amt, iso) | string | Returns formatted currency string. | | getAllISOCodes() | string[] | Returns all supported ISO codes. | | getISOByName(name) | string \| null | Returns ISO code for a country name. | | isValidISO(iso) | boolean | Checks if an ISO code is supported. | | getAllCountries() | object | Returns the entire country dataset. |

License

ISC