⚙️ API Reference

Complete reference for all types, functions, and exports in the Countries Cities AR library.

📝

Types

TypeScript interfaces

📝 TypeScript Types

Country Interface

interface Country {
  code: string;      // ISO country code (e.g., "EG", "SA", "US")
  name: string;      // English name (e.g., "Egypt")
  nameAr: string;    // Arabic name (e.g., "مصر")
  nameFr: string;    // French name (e.g., "Égypte")
  cities: City[];    // Array of cities/states/provinces
}

City Interface

interface City {
  name: string;      // English name (e.g., "Cairo")
  nameAr: string;    // Arabic name (e.g., "القاهرة")
  nameFr: string;    // French name (e.g., "Le Caire")
}

Language Type

type Language = 'en' | 'ar' | 'fr';

⚡ Functions

getCountryByCode()

Get a country by its ISO code.

getCountryByCode(code: string): Country | undefined

Example:

const egypt = getCountryByCode('EG');
console.log(egypt?.nameAr); // "مصر"
console.log(egypt?.cities.length); // 27

getCitiesByCountryCode()

Get all cities/states for a specific country.

getCitiesByCountryCode(code: string): City[]

Example:

const saudiCities = getCitiesByCountryCode('SA');
console.log(saudiCities.length); // 13
console.log(saudiCities[0].nameAr); // "الرياض"

getCountryName()

Get the country name in a specific language.

getCountryName(code: string, lang?: Language): string | undefined

Example:

const nameEn = getCountryName('EG', 'en'); // "Egypt"
const nameAr = getCountryName('EG', 'ar'); // "مصر"
const nameFr = getCountryName('EG', 'fr'); // "Égypte"

searchCountries()

Search for countries by name in any language.

searchCountries(query: string, lang?: Language): Country[]

Example:

// Search in Arabic
const arabCountries = searchCountries('عرب', 'ar');

// Search in English
const unitedCountries = searchCountries('united', 'en');

searchCities()

Search for cities globally or within a specific country.

searchCities(
  query: string,
  countryCode?: string,
  lang?: Language
): Array<{ city: City; country: Country }>

Example:

// Search all cities
const cairoResults = searchCities('cairo', undefined, 'en');

// Search in specific country
const egyptCities = searchCities('القاهرة', 'EG', 'ar');

console.log(egyptCities[0].city.nameAr); // "القاهرة"
console.log(egyptCities[0].country.name); // "Egypt"

📦 Data Exports

Available Datasets

allCountries

All 250 world countries

africaCountries

54 African countries

asiaCountries

49 Asian countries

europeCountries

50 European countries

americasCountries

48 American countries

oceaniaCountries

19 Oceanian countries

Example Usage:

import { 
  allCountries, 
  africaCountries, 
  asiaCountries 
} from 'countries-cities-ar';

console.log(allCountries.length); // 250
console.log(africaCountries.length); // 54
console.log(asiaCountries.length); // 49