@mohaned.ghawar/countries-info/README.md

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

# Countries Info (JavaScript/Node.js)

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

## Installation

```bash
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

```javascript
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
```javascript
{
  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
```javascript
{
  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
```javascript
// 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
```javascript
const service = new CountriesService();
const usStates = service.getCountryRegions('USA');
console.log(usStates); // ["Alabama", "Alaska", "Arizona", ...]
```

### Get European Countries
```javascript
const service = new CountriesService();
const europeanCountries = service.getCountriesByContinent('Europe');
console.log(europeanCountries.map(c => c.name.common));
```

### Search Countries
```javascript
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
```javascript
const service = new CountriesService();
const californiaCities = service.getCitiesByRegion('USA', 'California');
console.log(californiaCities.map(c => c.name));
```

### Get All Cities in the USA
```javascript
const service = new CountriesService();
const allUsCities = service.getAllCitiesInCountry('USA');
console.log(allUsCities.map(c => c.name));
```

### Search for Cities Named Paris
```javascript
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](LICENSE) file for details.

## Support

If you encounter any issues or have questions, please file an issue on the [GitHub repository](https://github.com/MohanedGhawar2019/countries-info-js/issues).