World-Countries-JSON is a comprehensive, high-performance dataset and library providing detailed information for 249 countries and territories worldwide. From basic ISO codes to travel-specific data like plug types and emergency numbers, this package is designed for modern web applications that need reliable global data.
- 🌍 Global Coverage: Comprehensive data for 249 countries and overseas territories.
- 🔍 Advanced Search: Search by Alpha-2, Alpha-3, ISO Numeric, or Country Name (case-insensitive).
- ⚡ Super Fast: Optimized for quick lookups via pre-indexed data.
- 🛡️ Travel Ready: Includes plug types, driving side, emergency contacts, and tipping etiquette.
- 📦 Zero Dependencies: Lightweight and reliable.
- 💾 Offline First: All data is local—no external API calls required.
npm install world-countries-jsonconst countries = require("world-countries-json");
// Get country by Alpha-2 code
const uk = countries.getCountry("GB");
console.log(uk.country_name); // "United Kingdom"
console.log(uk.capital); // "London"| Method | Description | Example |
|---|---|---|
getCountry(query) |
Smart search (auto-detects code or name) | countries.getCountry('US') |
getByAlpha2(code) |
Search by 2-letter ISO code | countries.getByAlpha2('FR') |
getByAlpha3(code) |
Search by 3-letter ISO code | countries.getByAlpha3('DEU') |
getByISO(code) |
Search by ISO Numeric code | countries.getByISO('250') |
getByName(name) |
Search by full country name | countries.getByName('France') |
searchByName(query) |
Partial name search (returns array) | countries.searchByName('united') |
Each country entry is a rich JSON object:
{
"id": "826",
"iso": "GBR",
"alpha_2": "GB",
"country_name": "United Kingdom",
"cover_image": "",
"flag_url": "https://flagcdn.com/gb.svg",
"short_description": "The United Kingdom is an island nation in northwestern Europe, known for its global cultural influence and historic landmarks.",
"known_for": [
{
"title": "🏰 Buckingham Palace & Royalty",
"color": "gray"
},
{
"title": "🕰️ Big Ben & Westminster",
"color": "brown"
},
{
"title": "🪨 Stonehenge",
"color": "gray"
},
{
"title": "🎓 Oxford & Cambridge Universities",
"color": "blue"
},
{
"title": "⚽ Premier League Football",
"color": "red"
}
],
"capital": "London",
"major_cities": [
"London",
"Birmingham",
"Glasgow",
"Liverpool",
"Manchester",
"Edinburgh",
"Bristol"
],
"official_language": ["English"],
"currency": {
"title": "Pound Sterling",
"symbol": "£"
},
"major_religions": "Christianity (60%)",
"national_day": {
"title": "King's Official Birthday",
"date": "Occurs in June"
},
"phone": {
"digital_code": "+44",
"phone_operators": ["EE", "O2", "Vodafone UK", "Three"]
},
"plug_types": ["G"],
"transport": {
"driving_side": "Left",
"taxi": ["Uber", "Free Now", "Black Cabs"],
"metro": [
"London Underground (The Tube)",
"Glasgow Subway",
"Tyne and Wear Metro"
]
},
"health": {
"tap_water_safety": "Safe to drink",
"alcohol_consumption_age": "18 years old",
"alcohol_parchase_age": "18 years old",
"alcohol_info": [
"Legal age is 18",
"Iconic pub culture with vast ales and spirits tradition"
]
},
"money": {
"tipping": {
"hotels": "£1-2 per bag",
"guides": "10% for private tours",
"restaurants": "10-15% is standard",
"taxis": "Rounding up the fare"
}
},
"weather": {
"title": "The UK has a temperate maritime climate with cool winters and warm summers.",
"when_to_visit": [
{
"icon": "🌤️",
"title": "Late Spring / Summer",
"time_period": "May to September",
"short_description": "Longest days and warmest weather."
},
{
"icon": "🎄",
"title": "Christmas Season",
"time_period": "December",
"short_description": "Festive markets and lights, though cold."
}
],
"best_time": "The best time to visit is from June to August."
},
"emergency": [
{
"title": "Emergency Services",
"number": "999"
},
{
"title": "Emergency (EU standard)",
"number": "112"
},
{
"title": "Non-emergency Police",
"number": "101"
},
{
"title": "Non-emergency Medical",
"number": "111"
}
]
}We welcome contributions to keep the data accurate and up-to-date!
- Fork the repository.
- Add/Modify data: If you are adding a new country, use the
template.jsonas your guide. - Validate:
- Ensure your JSON follows the exact structure of
template.json. - Your contribution must pass the schema validation.
- Run
npm run testto verify your changes.
- Ensure your JSON follows the exact structure of
- Submit a Pull Request.
Important
All new data entries must follow the template.json structure strictly to ensure compatibility with our indexing engine.
This project is licensed under the MIT License. See the LICENSE file for details.
Developed with ❤️ by Marian Dudych