@locale-tools/countries

World countries

Installation

Install a given package with npm or yarn.

npm install @locale-tools/countries

yarn add @locale-tools/countries

Usage

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

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 km²
  • 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.

Types

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"

Methods

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

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