REST Countries Scraper

Scrape REST Countries — the free public API for country metadata. All 250 ISO countries, with name (common + official + native), capital, population, area, currencies, languages, borders, region/subregion, flags (emoji + PNG + SVG), timezones, calling codes, TLDs, lat/lng, and more. HTTP-only via the public restcountries.com/v3.1 API. No auth, no proxy.

What this actor does

• Seven modes: all, byNames, byAlphaCodes, byRegion, bySubregion, byCurrency, byLanguage
• Filters: min population, min area (km²), UN members only, independent states only
• Auto-resolves alpha-2 / alpha-3 / numeric codes
• Empty fields are omitted

Output per country

• Names: commonName, officialName, altSpellings[], demonym
• ISO codes: cca2, cca3, ccn3, cioc, fifaCode
• Status: independent, unMember, status, landlocked
• Capital: capital[], capitalPrimary
• Geography: region, subregion, continents[], borders[], latitude, longitude
• Demographics: population, areaKm2
• Symbols: flagEmoji (🇩🇪), flagPng, flagSvg, coatOfArmsPng, coatOfArmsSvg
• Currency / language: currencies[] (code + name + symbol), currencyCodes[], languageCodes[], languageNames[]
• Communications: timezones[], callingCodes[], tlds[]
• Maps: googleMapsUrl, openStreetMapsUrl
• recordType: "country", scrapedAt

Input

Field	Type	Default	Description
mode	string	all	One of seven modes
names	array	–	Country names (mode=byNames)
alphaCodes	array	–	Alpha-2/3 codes (mode=byAlphaCodes)
region	string	–	Continental region
subregion	string	–	Subregion (e.g. Western Europe)
currency	string	–	ISO 4217 (mode=byCurrency)
language	string	–	Language name or ISO code
minPopulation	int	–	Drop countries below this
minArea	int	–	Drop countries below this km²
unMembersOnly	bool	false	–
independentOnly	bool	false	Excludes territories
maxItems	int	250	Hard cap (1–500)

Example: all UN member states with population > 10M

{
  "mode": "all",
  "minPopulation": 10000000,
  "unMembersOnly": true
}

Example: lookup specific countries

{
  "mode": "byAlphaCodes",
  "alphaCodes": ["DE", "FR", "ES", "IT", "GB", "PT"]
}

Example: all Eurozone countries

{
  "mode": "byCurrency",
  "currency": "EUR"
}

Example: all Spanish-speaking countries

{
  "mode": "byLanguage",
  "language": "spanish"
}

Use cases

• Geographic dropdowns — populate forms with all countries, sorted by region
• Lookup tables — alpha-2 ↔ alpha-3 ↔ numeric ISO mappings
• Phone-number formatting — callingCodes[] for international dialing
• Flag UI — flagEmoji for inline display, flagSvg for high-DPI
• Currency converter — group countries by currency for FX UIs
• i18n — group countries by official language

FAQ

Is the REST Countries API free? Yes. Self-hosted, no auth, no rate limits beyond reasonable use.

What's the difference between cca2 / cca3 / ccn3 / cioc? ISO 3166-1 alpha-2 (DE), alpha-3 (DEU), numeric (276), and IOC (GER) codes respectively.

Why does mode=all require many requests of fields? REST Countries v3.1+ requires explicit fields= parameter for /all to keep payloads small. The actor sends a comprehensive list — every field documented above.

How many countries are there? 250 entries (includes territories, dependencies, Antarctic). For sovereign UN states only, set unMembersOnly: true (193 entries).

What's cioc? International Olympic Committee code. Only set for countries that compete in the Olympics.

Why is latitude / longitude sometimes missing? REST Countries returns latlng: ["bad", "data"] for a few entries. The actor handles this gracefully.

How fresh is the data? Updated periodically (manual edits by maintainers). For real-time political changes, supplement with a different source.