0
# World Countries
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: world-countries
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install world-countries`
10

11
## Core Imports
12

13
```typescript
14
import countries from "world-countries";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const countries = require("world-countries");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import countries from "world-countries";
27

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

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

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

38
// Get all country names
39
const countryNames = countries.map(country => country.name.common);
40
```
41

42
## Architecture
43

44
World Countries is organized around several key components:
45

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

53
## Capabilities
54

55
### Countries Dataset
56

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

59
```typescript { .api }
60
declare const countries: Countries;
61
export default countries;
62

63
type Countries = Country[];
64

65
interface Country {
66
  name: CountryName;
67
  tld: string[];
68
  cca2: string;
69
  ccn3: string;
70
  cca3: string;
71
  cioc?: string;
72
  independent: boolean;
73
  status: string;
74
  unMember: boolean;
75
  unRegionalGroup: "African Group" | "Asia and the Pacific Group" | "Eastern European Group" | "Latin American and Caribbean Group" | "Western European and Others Group" | "";
76
  currencies: { [currencyCode: string]: Currency };
77
  idd: IntlDirectDialingCode;
78
  capital: string[];
79
  altSpellings: string[];
80
  region: string;
81
  subregion: string;
82
  languages: { [languageCode: string]: string };
83
  translations: { [languageCode: string]: OfficialAndCommon };
84
  latlng: [number, number];
85
  demonyms: { [languageCode: string]: Demonyms };
86
  landlocked: boolean;
87
  borders: string[];
88
  area: number;
89
  flag: string;
90
}
91
```
92

93
## Types
94

95
```typescript { .api }
96
interface CountryName extends OfficialAndCommon {
97
  native: {
98
    [languageCode: string]: OfficialAndCommon;
99
  };
100
}
101

102
interface OfficialAndCommon {
103
  common: string;
104
  official: string;
105
}
106

107
interface Currency {
108
  name: string;
109
  symbol: string;
110
}
111

112
interface IntlDirectDialingCode {
113
  root: string;
114
  suffixes: string[];
115
}
116

117
interface Demonyms {
118
  f: string;
119
  m: string;
120
}
121
```
122

123
## Country Data Structure
124

125
Each country object contains the following properties:
126

127
- **name**: Country names (common, official, native translations)
128
- **tld**: Top-level domains (e.g., [".us"])
129
- **cca2**: ISO 3166-1 alpha-2 code (e.g., "US")
130
- **ccn3**: ISO 3166-1 numeric code (e.g., "840")
131
- **cca3**: ISO 3166-1 alpha-3 code (e.g., "USA")
132
- **cioc**: International Olympic Committee code (e.g., "USA")
133
- **independent**: Independence status as sovereign state
134
- **status**: ISO 3166-1 assignment status
135
- **unMember**: UN membership status
136
- **unRegionalGroup**: UN Regional Group membership
137
- **currencies**: Currencies with names and symbols
138
- **idd**: International Direct Dialing codes
139
- **capital**: Capital city names
140
- **altSpellings**: Alternative country name spellings
141
- **region**: Geographic region (e.g., "Americas")
142
- **subregion**: Geographic subregion (e.g., "Northern America")
143
- **languages**: Official languages by ISO code
144
- **translations**: Country name translations in multiple languages
145
- **latlng**: Latitude and longitude coordinates [lat, lng]
146
- **demonyms**: Resident names by language and gender
147
- **landlocked**: Landlocked status (boolean)
148
- **borders**: Bordering countries as ISO alpha-3 codes
149
- **area**: Land area in square kilometers
150
- **flag**: Unicode emoji flag
151

152
## Usage Examples
153

154
### Finding Countries by Criteria
155

156
```typescript
157
import countries from "world-countries";
158

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

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

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

170
// Filter by region
171
const asianCountries = countries.filter(c => c.region === "Asia");
172
const europeanCountries = countries.filter(c => c.region === "Europe");
173
```
174

175
### Working with Country Data
176

177
```typescript
178
import countries from "world-countries";
179

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

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

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

196
// Find countries in specific UN regional group
197
const africanGroupCountries = countries.filter(c => 
198
  c.unRegionalGroup === "African Group"
199
);
200
```
201

202
### Geographic Operations
203

204
```typescript
205
import countries from "world-countries";
206

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

213
// Find countries within a region by coordinates
214
const findNearbyCountries = (targetLat: number, targetLng: number, maxDistanceKm: number) => {
215
  return countries.filter(country => {
216
    const [lat, lng] = country.latlng;
217
    const distance = getDistance(targetLat, targetLng, lat, lng);
218
    return distance <= maxDistanceKm;
219
  });
220
};
221

222
// Get countries by continent/region
223
const continentCountries = {
224
  africa: countries.filter(c => c.region === "Africa"),
225
  asia: countries.filter(c => c.region === "Asia"),
226
  europe: countries.filter(c => c.region === "Europe"),
227
  americas: countries.filter(c => c.region === "Americas"),
228
  oceania: countries.filter(c => c.region === "Oceania"),
229
};
230
```
231

232
## Alternative Data Formats
233

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

236
- `dist/countries.json` - Standard JSON format
237
- `dist/countries-unescaped.json` - JSON with unescaped Unicode characters
238
- `dist/countries.csv` - Comma-separated values format
239
- `dist/countries.xml` - XML format
240
- `dist/countries.yml` - YAML format
241

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

244
## Geographic Data Files
245

246
Individual geographic data files are available in the `data/` directory:
247

248
- `data/{cca3}.geo.json` - GeoJSON geographic outlines
249
- `data/{cca3}.topo.json` - TopoJSON geographic data  
250
- `data/{cca3}.svg` - SVG flag files
251

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