Countries Info (JavaScript/Node.js)

A comprehensive JavaScript library for accessing detailed country information, including regions, cities, capitals, continents, and more.

Installation

1npm install @mohaned.ghawar/countries-info

Features

• Complete country information (names, codes, capitals, etc.)
• Administrative regions for all countries (states, provinces, etc.)
• Detailed city data including:
  • City names and populations
  • Geographical coordinates
  • Hierarchical organization (Country -> Region -> Cities)
• Population and area data
• Continent information
• Easy-to-use API
• TypeScript-friendly
• Regular updates

Usage

1const CountriesService = require('@mohaned.ghawar/countries-info');
2const service = new CountriesService();
3
4// Get all countries
5const allCountries = service.getAllCountries();
6
7// Get a specific country by its 3-letter code
8const usa = service.getCountryByCode('USA');
9
10// Get a country by name
11const france = service.getCountryByName('France');
12
13// Get all regions/states of a country
14const usStates = service.getCountryRegions('USA');
15
16// Get all countries in a continent
17const europeanCountries = service.getCountriesByContinent('Europe');
18
19// Search countries by name
20const searchResults = service.searchByName('united');
21
22// Get cities in a specific region
23const californiaCities = service.getCitiesByRegion('USA', 'California');
24
25// Get all cities in a country
26const allUsCities = service.getAllCitiesInCountry('USA');
27
28// Get total number of cities in a country
29const usCityCount = service.getCityCount('USA');
30
31// Search for cities across all countries
32const citiesNamedParis = service.searchCities('Paris');

API Reference

Methods

getAllCountries()

Returns an array of all country objects.

getCountryByCode(code: string)

Returns a country object for the given 3-letter ISO code (e.g., 'USA', 'GBR').

getCountryByName(name: string)

Returns a country object for the given country name.

getCountryRegions(code: string)

Returns an array of region names for the given country code.

getCountriesByContinent(continent: string)

Returns an array of countries in the specified continent.

searchByName(name: string)

Returns an array of countries whose names contain the search term.

getCitiesByRegion(countryCode: string, regionName: string)

Returns an array of city objects for the given region.

getAllCitiesInCountry(countryCode: string)

Returns an array of city objects for the given country.

getCityCount(countryCode: string)

Returns the total number of cities in the given country.

searchCities(name: string)

Returns an array of city objects whose names contain the search term.

Data Structures

Country Object

1{
2  name: {
3    common: "United States",
4    official: "United States of America"
5  },
6  code: "USA",
7  capital: "Washington, D.C.",
8  continent: "North America",
9  population: 331002651,
10  area_km2: 9833517
11}

City Object

1{
2  name: "Los Angeles",
3  latitude: "34.05223",
4  longitude: "-118.24368",
5  population: 3971883,
6  countryCode: "USA",  // Only included in searchCities results
7  regionName: "California"  // Only included in searchCities results
8}

Regions Array

1// Example: service.getCountryRegions('USA')
2[
3  "Alabama",
4  "Alaska",
5  "Arizona",
6  // ... all US states
7  "Wisconsin",
8  "Wyoming"
9]

Data Coverage

• 250+ Countries
• 4,000+ Regions/States
• 150,000+ Cities worldwide

Examples

Get US States

1const service = new CountriesService();
2const usStates = service.getCountryRegions('USA');
3console.log(usStates); // ["Alabama", "Alaska", "Arizona", ...]

Get European Countries

1const service = new CountriesService();
2const europeanCountries = service.getCountriesByContinent('Europe');
3console.log(europeanCountries.map(c => c.name.common));

Search Countries

1const service = new CountriesService();
2const unitedCountries = service.searchByName('united');
3console.log(unitedCountries.map(c => c.name.common));
4// ["United States", "United Kingdom", "United Arab Emirates"]

Get Cities in California

1const service = new CountriesService();
2const californiaCities = service.getCitiesByRegion('USA', 'California');
3console.log(californiaCities.map(c => c.name));

Get All Cities in the USA

1const service = new CountriesService();
2const allUsCities = service.getAllCitiesInCountry('USA');
3console.log(allUsCities.map(c => c.name));

Search for Cities Named Paris

1const service = new CountriesService();
2const citiesNamedParis = service.searchCities('Paris');
3console.log(citiesNamedParis.map(c => c.name));

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see the LICENSE file for details.

Support

If you encounter any issues or have questions, please file an issue on the GitHub repository.