Countries Info (JavaScript/Node.js)

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

Installation

npm 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

const CountriesService = require('@mohaned.ghawar/countries-info');
const service = new CountriesService();

// Get all countries
const allCountries = service.getAllCountries();

// Get a specific country by its 3-letter code
const usa = service.getCountryByCode('USA');

// Get a country by name
const france = service.getCountryByName('France');

// Get all regions/states of a country
const usStates = service.getCountryRegions('USA');

// Get all countries in a continent
const europeanCountries = service.getCountriesByContinent('Europe');

// Search countries by name
const searchResults = service.searchByName('united');

// Get cities in a specific region
const californiaCities = service.getCitiesByRegion('USA', 'California');

// Get all cities in a country
const allUsCities = service.getAllCitiesInCountry('USA');

// Get total number of cities in a country
const usCityCount = service.getCityCount('USA');

// Search for cities across all countries
const 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

{
  name: {
    common: "United States",
    official: "United States of America"
  },
  code: "USA",
  capital: "Washington, D.C.",
  continent: "North America",
  population: 331002651,
  area_km2: 9833517
}

City Object

{
  name: "Los Angeles",
  latitude: "34.05223",
  longitude: "-118.24368",
  population: 3971883,
  countryCode: "USA",  // Only included in searchCities results
  regionName: "California"  // Only included in searchCities results
}

Regions Array

// Example: service.getCountryRegions('USA')
[
  "Alabama",
  "Alaska",
  "Arizona",
  // ... all US states
  "Wisconsin",
  "Wyoming"
]

Data Coverage

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

Examples

Get US States

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

Get European Countries

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

Search Countries

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

Get Cities in California

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

Get All Cities in the USA

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

Search for Cities Named Paris

const service = new CountriesService();
const citiesNamedParis = service.searchCities('Paris');
console.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.