Skip to content

README.md

Latest commit

 

History

History
173 lines (137 loc) · 3.98 KB

README.md

File metadata and controls

173 lines (137 loc) · 3.98 KB

🌍 Countries API

A free REST API for country data - perfect for testing, demos, prototypes, and learning.

Get comprehensive information about all 195 countries including names, capitals, populations, currencies, languages, flags, and more. No authentication required, CORS enabled, and powered by Cloudflare Workers for blazing-fast global performance.

🚀 Quick Start

Live API: https://countries-api.davegarvey.workers.dev

# Get all countries
curl https://countries-api.davegarvey.workers.dev/countries

# Get a specific country
curl https://countries-api.davegarvey.workers.dev/countries/US

# Get a random country (great for testing!)
curl https://countries-api.davegarvey.workers.dev/countries/random

# Filter by region
curl https://countries-api.davegarvey.workers.dev/countries?region=Europe

# Search for countries
curl https://countries-api.davegarvey.workers.dev/search?q=island

📋 Features

  • 195 Countries - Complete dataset with all recognized countries
  • Rich Data - Names, capitals, populations, currencies, languages, flags, calling codes
  • Flexible Filtering - By region, subregion, currency, language
  • No Auth Required - Open API, no API keys needed
  • CORS Enabled - Use directly from frontend applications
  • Fast & Reliable - Powered by Cloudflare's global network
  • Pretty JSON - Human-readable formatted responses

🔗 Common Endpoints

Get All Countries

GET /countries

Returns all 195 countries with complete data.

Get Specific Country

GET /countries/{code}

Get country by 2-letter (US, FR) or 3-letter (USA, FRA) ISO code.

Example Response:

{
  "name": "United States",
  "code": "US",
  "alpha3Code": "USA",
  "capital": "Washington, D.C.",
  "region": "Americas",
  "subregion": "Northern America",
  "population": 331002651,
  "languages": ["English"],
  "currency": "USD",
  "flag": "🇺🇸",
  "callingCode": "+1"
}

Get Random Country

GET /countries/random

Returns a random country - perfect for quiz apps, testing, or learning!

Filter by Region

GET /countries?region={region}

Available regions: Africa, Americas, Asia, Europe, Oceania

Example:

GET /countries?region=Europe

Filter by Currency

GET /countries?currency={currency}

Example:

GET /countries?currency=EUR  # All countries using Euro

Filter by Language

GET /countries?language={language}

Example:

GET /countries?language=Spanish

Search Countries

GET /search?q={query}

Search by country name or capital.

Example:

GET /search?q=united

Get Statistics

GET /stats

Returns global statistics including total population, most/least populous countries, and country counts by region.

Get Country Flag

GET /countries/{code}/flag

Returns just the flag emoji.

🎯 Use Cases

  • Learning & Education - Build geography quiz apps
  • Testing & Development - Populate dropdowns and forms with real data
  • Prototypes & Demos - Quick country data for MVPs
  • Data Visualization - Create maps and charts
  • Mobile Apps - Country pickers with flags
  • Tutorials - Teach API consumption and async programming

🛠️ Development

# Install dependencies
npm install

# Run locally
npm run dev

# Deploy to Cloudflare
npm run deploy

📊 Data Fields

Each country includes:

  • name - Country name
  • code - 2-letter ISO code
  • alpha3Code - 3-letter ISO code
  • capital - Capital city
  • region - Geographic region
  • subregion - Geographic subregion
  • population - Population count
  • languages - Array of official languages
  • currency - Currency code
  • flag - Flag emoji
  • callingCode - International calling code

📖 Full Documentation

Visit the API root endpoint for complete documentation:

GET /

📝 License

MIT