Nomadic People Migration

    @locale-tools/countries
    TypeScript icon, indicating that this package has built-in type declarations

    0.2.5 • Public • Published

    @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 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.

    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

    Install

    npm i @locale-tools/countries

    DownloadsWeekly Downloads

    1

    Version

    0.2.5

    License

    MIT

    Unpacked Size

    7.2 MB

    Total Files

    23

    Last publish

    Collaborators

    • gretzky