@locale-tools/countries

World countries

Installation

Install a given package with npm or yarn.

``bash
npm install @locale-tools/countries

yarn add @locale-tools/countries
`

Usage

There are 2 exports of the countries list, full and truncated (see above).

`ts
import {
countriesExpanded, // full list
countries // truncated list
} from "@locale-tools/countries";
`

The full JSON array of all world countries and information about them lives in the countries-expanded.

Each country is represented as an object.

- name
- common: common name (in English)
- official: officially recognized name (in English)
- native: list of names in the country's recognized languages
- [key: ISO_639_3]: ISO 639-3 language code
- common: common name (in native language)
- official: officially recognized name (in native language)
- alternates: array of alternate name spellings
- flag: unicode string flag
- cca2: ISO 3166-1 alpha-2 code
- cca3: ISO 3166-1 alpha-3 code
- ccn3: ISO 3166-1 numeric code
- ioc: International Olympic Committee code
- governance
- isSovereign: whether or not the country is independent (i.e. is self-governing)
- governingBody: the country that governs the dependency (undefined if isSovereign is true)
- isUNMember: whether or not the country is a member of the UN (undefined if isSovereign is false)
- isEU: (european countries only) whether or not the country is a member of the EU
- isSchengen: (european countries only) whether or not the country is a member of the Schengen Area
- isEurozone: (european countries only) whether or not the country is a part of the Eurozone, i.e. whether or not they use the Euro currency
- languages
- official: an array of officially recognized languages
- name:
- common: the name of the language in English
- native: the name of the language in that language
- iso639_3: ISO639-3 language code
- bcp47: BCP47 tag
- iso14924: ISO15924 script tag
- iana: array of assigned IANA tags
- isExtinct: whether or not the language is no longer spoken
- isSpurious: whether or not the language is spurious, i.e. questioned if it ever existed
- spoken: list of ISO639-3 language tags of languages spoken in the country, but are not recognized as 'official' languages
- geography
- coordinates: numeric coordinates of the center of the country
- latitude
- longitude
- isLandlocked: whether or not the country is landlocked (not bordering the ocean)
- capitalCity: a list of capital cities
- landArea: size of the country in km2
- region: the region the country is in (e.g. 'americas', 'europe')
- subregion: the subregion of the country (e.g. carribbean)
- borderCountries: list of countries by their ISO 3166-1 alpha-3 codes that border the country
- locale
- ietf: a list of IETF locale codes (e.g. en-US)
- measurementSystem: system of measurement in use
- drivingSide: driving side
- hourClock: type of clock used
- timezones: list of tz database timezones
- name: name of timezone
- type: the type of timezone (primary or alias)
- linkedTo: (if alias) the primary timezone this timezone links to
- utcOffset: hours offset from UTC
- dstOffset: hours offset from UTC during DST (if country doesn't observe DST, this is the same value as UTC offset)
- dateFormats: date formats for each IETF locale
- key is the IETF locale name
- value is the date format, where:
- G = era
- y = year
- M = month
- d = day
- weekStartsOn: which day is the first day of the week on the calendar
- distanceUnit: the unit of distance used (kilometer or mile)
- temperatureMeasurement: the unit of temperature (celsius or fahrenheit)
- currencies: list of accepted currencies
- name: official currency name (in English)
- shortName: the name of the currency itself (e.g. 'dollar' as opposed to 'US Dollar')
- iso4217: ISO 4217 code
- isoNumeric: ISO 4217 numeric code
- symbol: unicode symbol (e.g. '\$')
- subunit: subunit to whole value (e.g. 'cent')
- subunitToUnit: number of subunits to reach a whole unit value (e.g. 100 cents = 1 dollar)
- prefix: symbol that prefixes a currency amount (e.g. '\$1')
- suffix: symbol that suffixes a currency amonut (e.g. '1€')
- decimalMark: symbol that denotes a decimal place
- decimalPlaces: number of decimal places rounded to
- thousansSeparator: symbol to denote thousands separation
- tld: list of top-level domains used
- idd: international dialing direct info
- prefix: geographical code prefix (e.g. +1 for US)
- suffixes: list of suffixes assigned (e.g. 201 in US)
- callingCodes: list of calling codes (combinations of the prefix and each suffix - e.g. +1201)
- subdivisions: list of ISO 3166-2 subdivisions of each country
- name: name of the subdivision in the country's recognized languages
- [key: ISO_639_3]: ISO 639-3 language code
- official: official subdivison name
- common: locally used name variant
- native: official name in non-alphanumeric script language (e.g. arabic, cyrillic)

There is also a truncated list (src/data/countries.json) that abbreviates and filters out certain data to reduce file size.

Full country list vs. truncated country list

| Object | countries-expanded.json | countries.json |
| -------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------- |
| languages.official | A list of full language objects | A list of ISO639-3 language codes |
| currencies | A list of full currency objects | A list of ISO4217 currency codes |
| locale.timezones | A list of full timezone objects | A list of tz database timezone names |
| subdivisions | A list of subdivision objects | undefined |

Note: subdivisions is removed from countries.json because for most countries, it's a huge list and many times isn't needed.

$3

`ts
type Country = {
name: {
common: string;
official: string;
native: {
[key in ISO639_3]: {
official: string;
common: string;
};
};
alternates?: string[];
};
flag: string;
cca2: ISO3166_1_Alpha2;
cca3: ISO3166_1_Alpha3;
ccn3: ISO3166_1_Numeric; // enum is keyed by country name
ioc: IOC | null;
governance: {
isSovereign: boolean;
isUNMember?: boolean;
governingCountry?: ISO3166_1_Alpha3 | string; // Antarctica is the 'string' exception
isEU?: boolean;
isSchengen?: boolean;
isEurozone?: boolean;
};
languages: {
official: Language[] | ISO639_3[]; // language objects for full, iso639-3 codes for truncated
spoken: ISO639_3[];
};
geography: {
coordinates: {
latitude: number;
longitude: number;
};
isLandlocked: boolean;
capitalCity: string[];
landArea: number;
region: Region;
subregion: Subregion;
borderCountries: ISO3166_1_Alpha3[];
};
locale: {
ietf: IETF[];
measurementSystem: "metric" | "imperial"; // also available as an enum (MeasurementSystem)
drivingSide: "left" | "right"; // also available as an enum (DrivingSide)
hourClock: "12hr" | "24hr" | "mixed"; // also available as an enum (HourClock)
weekStartsOn: "friday" | "saturday" | "sunday" | "monday"; // also available as an enum (WeekStartsOn)
distanceUnit: "kilometer" | "mile"; // also available as an enum (DistanceUnit)
temperatureUnit: "celsius" | "fahrenheit"; // also available as an enum (TemperatureUnit)
timezones: Timezones[] | TZTimezone[]; // timezone objects on full, tz names for truncated
dateFormats: {
[key in ISO639_3]: string;
};
};
currencies: Currency[] | ISO4217[]; // currency objects on full, iso4217 strings for truncated
tld: TLD[];
idd: {
prefix: string;
suffixes: string[];
callingCodes: string[];
};
subdivisions: Subdivision[] | undefined; // only available on full list
};

// subdivision object
type Subdivision = {
isoCode: ISO3166_2;
type?: SubdivisionTypes;
name: {
[key in ISO639_3]: {
official: string;
common: string | null;
native: string | null;
};
};
};

// ISO3166-1 alpha2 (cca2) codes
enum ISO3166_1_Alpha2 {}
ISO3166_1_Alpha2.AX; // "AX"

// ISO3166-1 alpha2 codes keyed by country name
enum ISO3166_1_Alpha2ByCountry {}
ISO3166_1_Alpha2ByCountry.denmark; // "DK"

// ISO3166-1 alpha3 (cca3) codes
enum ISO3166_1_Alpha3 {}
ISO3166_1_Alpha3.ALA; // "ALA"

// ISO3166-1 alpha3 codes keyed by country name
enum ISO3166_1_Alpha3ByCountry {}
ISO3166_1_Alpha3ByCountry.denmark; // "DNK"

// ISO3166 numeric (ccn3) codes
// this enum is keyed by country name
enum ISO3166_1_Numeric {}
ISO3166_1_Numeric.british_virgin_islands; // "092"

// ISO3166-2 subdivision codes
enum ISO3166_2 {} // ISO3166-2 subdivision codes
ISO3166_2.BT_42; // "BT-42"

// regions
enum Regions {}
Regions.oceania; // "oceania"

// subregions
enum Subregions {}
Subregions.australia_new_zealand; // "Australia and New Zealand"
`

$3

#### getCountryNameKey(name: string): CountryKey

Country enum keys are 'simplified' versions of country names, e.g. 'Saint Vincent and the Grenadines' becomes 'st_vincent_grenadines'.

| Parameter | Type | Description | Default |
| --------- | -------- | ----------------------------------- | ------------ |
| name | string | The country name to get the key for | Required |

`ts
import { getCountryKey, ISO3166_1_Alpha2ByCountry } from "@locale-tools/countries";

const countryKey1 = getCountryKey("Aruba"); // aruba

// name does not have to be case sensitive
const countryKey2 = getCountryKey("new zealand"); // new_zealand

// partial country names will work too, if found
// in this case, the country name is technically 'Saint Helena, Ascension and Tristan da Cunha"
const countryKey3 = getCountryKey("St Helena"); // st_helena_ascension_tristan_da_cunha

// you can use the country key to read from the ISO3166 enums
ISO3166_1_Alpha2ByCountry[countryKey1]; // AW
ISO3166_1_Alpha2ByCountry[countryKey2]; // NZ
ISO3166_1_Alpha2ByCountry[countryKey3]; // SH
``