or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-world-countries

List of world countries in JSON, CSV, XML and YAML with comprehensive metadata including names, codes, geography, currencies, and demographic information

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/world-countries@5.1.x

To install, run

npx @tessl/cli install tessl/npm-world-countries@5.1.0

index.mddocs/

World Countries

World Countries is a comprehensive dataset of world countries as defined by ISO Standard 3166-1, available in multiple data formats including JSON, CSV, XML, and YAML. The dataset contains detailed information for each country including names, ISO codes, geographic data, political information, currencies, languages, demographic data, and calling codes.

Package Information

  • Package Name: world-countries
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install world-countries

Core Imports

import countries from "world-countries";

For CommonJS:

const countries = require("world-countries");

Basic Usage

import countries from "world-countries";

// Access all countries data
console.log(`Total countries: ${countries.length}`);

// Find a specific country by ISO code
const usa = countries.find(country => country.cca2 === "US");
console.log(usa.name.common); // "United States"

// Filter by region
const europeanCountries = countries.filter(country => country.region === "Europe");

// Get all country names
const countryNames = countries.map(country => country.name.common);

Architecture

World Countries is organized around several key components:

  • Country Data Array: The main export is a typed array of country objects, each containing comprehensive metadata
  • ISO Standards Compliance: All country codes follow ISO 3166-1 standards (alpha-2, alpha-3, numeric)
  • Multi-format Support: The same dataset is available in JSON, CSV, XML, and YAML formats in the dist/ directory
  • Geographic Data: Individual country geographic outlines and flag SVGs are provided in the data/ directory
  • Type Safety: Full TypeScript definitions ensure compile-time validation of country data structure
  • Localization: Country names and demonyms are provided in multiple languages via the translations and demonyms properties

Capabilities

Countries Dataset

Access to the complete array of country objects containing comprehensive metadata for all world countries and territories.

declare const countries: Countries;
export default countries;

type Countries = Country[];

interface Country {
  name: CountryName;
  tld: string[];
  cca2: string;
  ccn3: string;
  cca3: string;
  cioc?: string;
  independent: boolean;
  status: string;
  unMember: boolean;
  unRegionalGroup: "African Group" | "Asia and the Pacific Group" | "Eastern European Group" | "Latin American and Caribbean Group" | "Western European and Others Group" | "";
  currencies: { [currencyCode: string]: Currency };
  idd: IntlDirectDialingCode;
  capital: string[];
  altSpellings: string[];
  region: string;
  subregion: string;
  languages: { [languageCode: string]: string };
  translations: { [languageCode: string]: OfficialAndCommon };
  latlng: [number, number];
  demonyms: { [languageCode: string]: Demonyms };
  landlocked: boolean;
  borders: string[];
  area: number;
  flag: string;
}

Types

interface CountryName extends OfficialAndCommon {
  native: {
    [languageCode: string]: OfficialAndCommon;
  };
}

interface OfficialAndCommon {
  common: string;
  official: string;
}

interface Currency {
  name: string;
  symbol: string;
}

interface IntlDirectDialingCode {
  root: string;
  suffixes: string[];
}

interface Demonyms {
  f: string;
  m: string;
}

Country Data Structure

Each country object contains the following properties:

  • name: Country names (common, official, native translations)
  • tld: Top-level domains (e.g., [".us"])
  • cca2: ISO 3166-1 alpha-2 code (e.g., "US")
  • ccn3: ISO 3166-1 numeric code (e.g., "840")
  • cca3: ISO 3166-1 alpha-3 code (e.g., "USA")
  • cioc: International Olympic Committee code (e.g., "USA")
  • independent: Independence status as sovereign state
  • status: ISO 3166-1 assignment status
  • unMember: UN membership status
  • unRegionalGroup: UN Regional Group membership
  • currencies: Currencies with names and symbols
  • idd: International Direct Dialing codes
  • capital: Capital city names
  • altSpellings: Alternative country name spellings
  • region: Geographic region (e.g., "Americas")
  • subregion: Geographic subregion (e.g., "Northern America")
  • languages: Official languages by ISO code
  • translations: Country name translations in multiple languages
  • latlng: Latitude and longitude coordinates [lat, lng]
  • demonyms: Resident names by language and gender
  • landlocked: Landlocked status (boolean)
  • borders: Bordering countries as ISO alpha-3 codes
  • area: Land area in square kilometers
  • flag: Unicode emoji flag

Usage Examples

Finding Countries by Criteria

import countries from "world-countries";

// Find by ISO codes
const france = countries.find(c => c.cca3 === "FRA");
const usa = countries.find(c => c.cca2 === "US");

// Filter by independence status
const independentCountries = countries.filter(c => c.independent);
const territories = countries.filter(c => !c.independent);

// Filter by UN membership
const unMembers = countries.filter(c => c.unMember);

// Filter by region
const asianCountries = countries.filter(c => c.region === "Asia");
const europeanCountries = countries.filter(c => c.region === "Europe");

Working with Country Data

import countries from "world-countries";

// Get all currencies used worldwide
const allCurrencies = countries.reduce((currencies, country) => {
  Object.entries(country.currencies || {}).forEach(([code, currency]) => {
    currencies[code] = currency;
  });
  return currencies;
}, {} as { [code: string]: Currency });

// Find landlocked countries
const landlockedCountries = countries.filter(c => c.landlocked);

// Get countries by language
const spanishSpeakingCountries = countries.filter(country => 
  Object.values(country.languages || {}).includes("Spanish")
);

// Find countries in specific UN regional group
const africanGroupCountries = countries.filter(c => 
  c.unRegionalGroup === "African Group"
);

Geographic Operations

import countries from "world-countries";

// Calculate distances or find nearby countries using coordinates
const getDistance = (lat1: number, lng1: number, lat2: number, lng2: number) => {
  // Haversine formula implementation
  // ... distance calculation logic
};

// Find countries within a region by coordinates
const findNearbyCountries = (targetLat: number, targetLng: number, maxDistanceKm: number) => {
  return countries.filter(country => {
    const [lat, lng] = country.latlng;
    const distance = getDistance(targetLat, targetLng, lat, lng);
    return distance <= maxDistanceKm;
  });
};

// Get countries by continent/region
const continentCountries = {
  africa: countries.filter(c => c.region === "Africa"),
  asia: countries.filter(c => c.region === "Asia"),
  europe: countries.filter(c => c.region === "Europe"),
  americas: countries.filter(c => c.region === "Americas"),
  oceania: countries.filter(c => c.region === "Oceania"),
};

Alternative Data Formats

The package also provides the same dataset in multiple formats located in the dist/ directory:

  • dist/countries.json - Standard JSON format
  • dist/countries-unescaped.json - JSON with unescaped Unicode characters
  • dist/countries.csv - Comma-separated values format
  • dist/countries.xml - XML format
  • dist/countries.yml - YAML format

These files can be accessed directly if you need the data in a specific format outside of JavaScript/TypeScript.

Geographic Data Files

Individual geographic data files are available in the data/ directory:

  • data/{cca3}.geo.json - GeoJSON geographic outlines
  • data/{cca3}.topo.json - TopoJSON geographic data
  • data/{cca3}.svg - SVG flag files

Where {cca3} is the three-letter ISO alpha-3 country code (e.g., usa.geo.json, fra.svg).