🌍 guess-the-flag

A fun and educational NPM package to quiz yourself or others on country flags. This package allows you to fetch random flags (with emoji and image), generate multiple-choice options, and verify answers — perfect for games, quizzes, or learning geography.

📦 Installation

npm install guess-the-flag

or with Yarn:

yarn add guess-the-flag

🧠 Use Case

Build your own flag guessing game or integrate into quiz apps, educational tools, or even Discord bots!

🚀 Getting Started

1. Import the package

const flagGame = require('guess-the-flag');

2. Get a random flag

const random = flagGame.getRandomFlag();
console.log("Flag Emoji:", random.emoji); // 🇯🇵
console.log("Image URL:", random.image);  // SVG URL
console.log("Country:", random.name);     // Japan

3. Generate multiple choice options

const options = flagGame.getOptions(random.name);
console.log("Options:", options); 
// [ 'Japan', 'India', 'France', 'Brazil' ]

4. Check the answer

const guess = 'Japan';
const isCorrect = flagGame.checkGuess(random.emoji, guess);
console.log("Correct?", isCorrect); // true

🧩 Full API Reference

getRandomFlag()

Returns a random country with its emoji and image.

{
  name: "India",
  emoji: "🇮🇳",
  image: "https://cdn.jsdelivr.net/..."
}

getOptions(correctCountry: string, count = 4)

Returns multiple choice options including the correct country.

['India', 'Japan', 'Germany', 'Brazil']

checkGuess(flag: string, country: string)

Returns true if the guess is correct, otherwise false.

checkGuess("🇮🇳", "India"); // true
checkGuess("https://cdn.jsdelivr.net/.../IN.svg", "India"); // true

getFlagByCountry(country: string)

Returns the flag emoji and image for a given country.

{
  emoji: "🇫🇷",
  image: "https://cdn.jsdelivr.net/.../FR.svg"
}

getCountryByFlag(flag: string)

Returns the country name by either emoji or image URL.

getCountryByFlag("🇺🇸"); // "United States"
getCountryByFlag("https://cdn.jsdelivr.net/.../US.svg"); // "United States"

getAllFlags()

Returns an array of all countries with emoji and image flags.

[
  { name: "India", emoji: "🇮🇳", image: "..." },
  { name: "Germany", emoji: "🇩🇪", image: "..." },
  ...
]

🧑‍💻 Author

Shubham Somwanshi
Portfolio | GitHub

📄 License

MIT © 2025 Shubham Somwanshi

💡 Tip

You can use this in CLI games, React quiz apps, or even as an educational tool for kids to learn world geography with fun and ease!