REST Countries Data Search

Search, filter, and extract comprehensive country data from the REST Countries API v3.1. Look up any of 250+ countries and territories by name, ISO code, region, language, currency, or capital city. Returns 30+ structured fields per country -- population, area, flags, timezones, currencies, borders, map links, Gini index, and more. No API key required. Runs in under 10 seconds on 256 MB of memory.

---

Why use REST Countries Data Search?

• No coding required -- Search countries from the Apify Console web form without writing a single line of code. Fill in a field, click Start, and download structured results.
• Six flexible search modes -- Look up countries by name, ISO 3166-1 code, world region, spoken language, currency code, or capital city. Leave all fields empty to export the entire global dataset.
• Normalized, analysis-ready output -- Raw API responses are transformed into a consistent 30-field JSON schema with null-safe defaults, ready for direct import into databases, spreadsheets, or BI tools.
• Built-in dataset storage and export -- Results are automatically saved to an Apify dataset you can download as JSON, CSV, Excel, or XML at any time.
• Seamless automation -- Schedule recurring runs, trigger via API, or connect to Google Sheets, Zapier, Make, Slack, and webhooks for fully automated country data pipelines.
• Minimal cost -- The actor calls a free public API with no proxy overhead. A single run costs well under $0.01 in Apify platform credits, and hundreds of runs fit within the free tier.

---

Key features

• Six search endpoints -- Query the REST Countries API by name, ISO alpha-2/alpha-3 code, world region, language, currency, or capital city using a single actor.
• Full global coverage -- Access data for 250+ countries and territories, including sovereign states, dependent territories, and special administrative regions.
• 30+ output fields -- Each country record includes demographics, geography, government status, flag imagery (emoji, PNG, SVG), coat of arms, map URLs, timezones, borders, driving side, Gini coefficients, and more.
• Priority-based search resolution -- When multiple input fields are provided, the actor resolves the search endpoint using a deterministic priority order: countryCode, searchQuery, capital, region, language, currency.
• Configurable result limit -- Control output size with the maxResults parameter, supporting values from 1 to 250.
• Null-safe data transformation -- Handles missing fields, inconsistent API responses, and edge cases gracefully so downstream consumers never encounter unexpected nulls or missing keys.
• Low memory footprint -- Runs on just 256 MB of memory, keeping compute costs at an absolute minimum.
• No API key needed -- The REST Countries API is free and open. No authentication tokens, rate limit keys, or paid subscriptions are required.
• Instant results -- Most queries complete in under 10 seconds, even when returning all 250+ countries.

---

How to use REST Countries Data Search

Using the Apify Console

1. Navigate to the REST Countries Data Search actor page on Apify.
2. Click Try for free to open the actor in Apify Console.
3. Fill in your search parameters:
   • Enter a Country Name such as "Japan" or "Brazil" to search by name.
   • Enter a Country Code such as "US" or "DEU" to look up a specific country by ISO code.
   • Select a Region (Africa, Americas, Asia, Europe, Oceania) to retrieve all countries in that area.
   • Enter a Language such as "spanish" to find all Spanish-speaking countries.
   • Enter a Currency Code such as "EUR" to find all countries using the Euro.
   • Enter a Capital City such as "Berlin" to find the country with that capital.
4. Optionally adjust Max Results to control how many countries are returned.
5. Click Start to run the actor.
6. When the run completes, open the Dataset tab to view, filter, and export results as JSON, CSV, Excel, or XML.

Using the Apify CLI

$apify call ryanclinton/rest-countries-search -i '{"searchQuery": "Germany"}'

Using the Apify API

curl "https://api.apify.com/v2/acts/6GUYnSUCFTRuVcQDA/runs" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{"region": "Europe", "maxResults": 50}'

---

Input parameters

Parameter	Type	Required	Default	Description
searchQuery	string	No	--	Country name to search for (e.g., "United States", "Germany"). Prefilled with "United States".
countryCode	string	No	--	ISO 3166-1 alpha-2 or alpha-3 code (e.g., "US", "USA", "DE", "DEU"). Highest search priority.
region	string	No	--	Filter by world region. Options: Africa, Americas, Asia, Europe, Oceania.
language	string	No	--	Filter by spoken language (e.g., "spanish", "french", "english").
currency	string	No	--	Filter by currency code (e.g., "USD", "EUR", "GBP").
capital	string	No	--	Search by capital city name (e.g., "Washington", "Berlin").
maxResults	integer	No	50	Maximum number of country results to return. Range: 1--250.

Input JSON example

{
    "searchQuery": "United States",
    "maxResults": 10
}

Search priority order

When multiple fields are provided, the actor uses this priority to select which endpoint to call:

1. countryCode -- looks up /alpha/{code} for an exact ISO code match
2. searchQuery -- searches /name/{query} for name matches
3. capital -- searches /capital/{city} for capital city matches
4. region -- filters /region/{region} for all countries in a region
5. language -- filters /lang/{language} for countries speaking a language
6. currency -- filters /currency/{code} for countries using a currency

If no field is provided, the actor calls /all and returns every country.

Tips:

• Use countryCode for exact single-country lookups when you know the ISO code.
• Use region for bulk geographic exports (e.g., all 54 African countries in one run).
• Leave all fields empty and set maxResults to 250 for a complete global dataset.

---

Output

Each country record contains 30 structured fields. Here is an example output item:

{
    "name": "United States",
    "officialName": "United States of America",
    "nativeName": {
        "eng": {
            "official": "United States of America",
            "common": "United States"
        }
    },
    "cca2": "US",
    "cca3": "USA",
    "ccn3": "840",
    "capital": ["Washington, D.C."],
    "capitalLatLng": [38.89, -77.05],
    "region": "Americas",
    "subregion": "North America",
    "continents": ["North America"],
    "population": 331449281,
    "area": 9833520,
    "languages": {
        "eng": "English"
    },
    "currencies": {
        "USD": {
            "name": "United States dollar",
            "symbol": "$"
        }
    },
    "timezones": ["UTC-12:00", "UTC-11:00", "UTC-10:00", "UTC-09:00", "UTC-08:00", "UTC-07:00", "UTC-06:00", "UTC-05:00", "UTC-04:00"],
    "borders": ["CAN", "MEX"],
    "flagEmoji": "",
    "flagPng": "https://flagcdn.com/w320/us.png",
    "flagSvg": "https://flagcdn.com/us.svg",
    "coatOfArms": {
        "png": "https://mainfacts.com/media/images/coats_of_arms/us.png",
        "svg": "https://mainfacts.com/media/images/coats_of_arms/us.svg"
    },
    "googleMapsUrl": "https://goo.gl/maps/e8M246zY4BSjkjAv6",
    "openStreetMapsUrl": "https://www.openstreetmap.org/relation/148838#map=2/20.6/-85.8",
    "independent": true,
    "unMember": true,
    "landlocked": false,
    "startOfWeek": "sunday",
    "car": {
        "signs": ["USA"],
        "side": "right"
    },
    "gini": {
        "2018": 41.4
    },
    "extractedAt": "2026-02-19T12:00:00.000Z"
}

Output fields reference

Field	Type	Description
name	string	Common country name (e.g., "France")
officialName	string	Official country name (e.g., "French Republic")
nativeName	object	Native names keyed by language code
cca2	string	ISO 3166-1 alpha-2 code (e.g., "FR")
cca3	string	ISO 3166-1 alpha-3 code (e.g., "FRA")
ccn3	string	ISO 3166-1 numeric code (e.g., "250")
capital	array	Capital city name(s)
capitalLatLng	array	Latitude and longitude of the capital city
region	string	World region (Africa, Americas, Asia, Europe, Oceania)
subregion	string	Subregion (e.g., "Western Europe", "South America")
continents	array	Continent(s) the country belongs to
population	number	Total population count
area	number	Land area in square kilometers
languages	object	Official languages keyed by language code
currencies	object	Currencies with name and symbol, keyed by currency code
timezones	array	UTC timezone offsets observed in the country
borders	array	Alpha-3 codes of bordering countries
flagEmoji	string	Unicode flag emoji character
flagPng	string	URL to flag image in PNG format
flagSvg	string	URL to flag image in SVG format
coatOfArms	object	URLs to coat of arms images (PNG and SVG)
googleMapsUrl	string	Google Maps link to the country
openStreetMapsUrl	string	OpenStreetMap link to the country
independent	boolean	Whether the country is independent
unMember	boolean	Whether the country is a UN member state
landlocked	boolean	Whether the country is landlocked
startOfWeek	string	Day the week starts (e.g., "monday", "sunday")
car	object	Driving information: vehicle signs and driving side
gini	object	Gini inequality index keyed by year
extractedAt	string	ISO 8601 timestamp of when the data was extracted

---

Use cases

• Data enrichment -- Enrich CRM records, lead databases, or customer profiles with country-level metadata such as region, currency, population, and language.
• Geographic applications -- Build country selectors, map visualizations, or location-based filters using ISO codes, coordinates, flag images, and region data.
• Travel and hospitality platforms -- Display country flags, timezones, capital cities, and driving-side information for destination pages.
• E-commerce localization -- Determine local currencies, languages, and regions for international storefronts and checkout flows.
• Academic research -- Compile datasets of country demographics, Gini coefficients, UN membership status, and border relationships for statistical analysis.
• Educational tools -- Power geography quizzes, country fact cards, and interactive learning materials with structured reference data.
• Business intelligence dashboards -- Aggregate countries by region, subregion, population, or area to build comparative geographic reports.
• Regulatory compliance -- Identify UN member states, independent nations, and country codes for KYC, AML, and sanctions screening workflows.
• API backend data -- Use the structured output as a data source for REST APIs, GraphQL resolvers, or mobile applications that need country reference data.

---

API and integrations

Python

from apify_client import ApifyClient

client = ApifyClient("YOUR_API_TOKEN")

run = client.actor("6GUYnSUCFTRuVcQDA").call(run_input={
    "region": "Europe",
    "maxResults": 50,
})

dataset_items = client.dataset(run["defaultDatasetId"]).list_items().items

for country in dataset_items:
    print(f"{country['name']} ({country['cca2']}) -- Pop: {country['population']:,}")

JavaScript

import { ApifyClient } from "apify-client";

const client = new ApifyClient({ token: "YOUR_API_TOKEN" });

const run = await client.actor("6GUYnSUCFTRuVcQDA").call({
    currency: "EUR",
    maxResults: 30,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();

items.forEach((country) => {
    console.log(`${country.name} (${country.cca2}) -- ${country.currencies?.EUR?.name}`);
});

cURL

# Start a run
curl "https://api.apify.com/v2/acts/6GUYnSUCFTRuVcQDA/runs" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{"language": "french", "maxResults": 25}'

# Fetch results from the default dataset
curl "https://api.apify.com/v2/acts/6GUYnSUCFTRuVcQDA/runs/last/dataset/items?token=YOUR_API_TOKEN"

Platform integrations

• Google Sheets -- Automatically push country data to a spreadsheet after each run.
• Webhooks -- Trigger downstream workflows whenever new country data is collected.
• Zapier -- Connect to 5,000+ apps and automate data pipelines with country data as a trigger or action.
• Make (Integromat) -- Build multi-step automation scenarios that incorporate country reference data.
• Slack -- Receive notifications when scheduled country data runs complete.
• Amazon S3 / Google Cloud Storage -- Export datasets directly to cloud storage buckets for archival or further processing.

---

How it works

The actor follows a straightforward pipeline to query, transform, and store country data:

1. Input parsing -- Reads the input configuration and identifies which search parameters were provided.
2. Endpoint selection -- Selects the REST Countries API v3.1 endpoint based on input priority: countryCode > searchQuery > capital > region > language > currency > /all.
3. API request -- Sends a single HTTP GET request to https://restcountries.com/v3.1/{endpoint}.
4. Response handling -- Parses the JSON response. Handles 404 responses (no matches) gracefully and normalizes single-object responses from the /alpha endpoint into arrays.
5. Result limiting -- Applies the maxResults cap to truncate the result set.
6. Data transformation -- Maps each raw country object through a 30-field transformation function with null-safe defaults for every field.
7. Dataset push -- Pushes the transformed records to the Apify dataset for storage and export.

Input --> Endpoint Selection --> REST Countries API v3.1 (HTTP GET)
  --> Response Parsing --> Result Limiting --> 30-Field Transform --> Apify Dataset

---

Performance and cost

Metric	Value
Memory allocation	256 MB
Typical run time	Under 10 seconds
Cost per run	Less than $0.001 in Apify credits
Proxy required	No
API key required	No
Maximum results per run	250 countries
Runs within free tier	Hundreds per month
Data source latency	Real-time (live API call)

The actor makes a single HTTP request per run to the REST Countries API. There are no proxy costs, pagination loops, or retry overheads. Compute charges consist solely of the minimal memory-seconds consumed during the run.

---

Limitations

• Single search mode per run -- The actor uses only one API endpoint per execution. If multiple search fields are provided, only the highest-priority field is used (see the priority order above). To search by both region and language, run the actor twice with different inputs.
• No partial name matching control -- Name searches use the REST Countries API default matching behavior. Very short or ambiguous queries (e.g., "a") may return many results.
• Data freshness depends on the upstream API -- Country data (population, currencies, borders) is maintained by the REST Countries project. The actor reflects whatever the API currently returns.
• Maximum 250 results -- The result cap is bounded at 250, which covers all countries and territories in the database. This is a practical upper limit, not a restriction.
• No historical data -- The API provides current snapshot data only. For historical country-level economic data, consider the World Bank Development Indicators actor.
• Flag and coat of arms URLs are external -- Image URLs point to third-party CDNs (flagcdn.com, mainfacts.com). Availability depends on those services.
• No filtering within results -- The actor does not support combining multiple filters (e.g., region + language) in a single run. Post-process the dataset or run multiple queries to achieve combined filtering.

---

Responsible use

• Respect the REST Countries API -- The REST Countries API is a free community resource. Avoid scheduling runs at excessively high frequencies (e.g., every minute) that could strain the upstream service.
• Attribute data appropriately -- If you publish or redistribute country data obtained through this actor, consider attributing the REST Countries project (https://restcountries.com/) as the original data source.
• Verify critical data independently -- Country data such as population figures, border relationships, and political status can change. For high-stakes decisions (legal, regulatory, financial), cross-reference with official government or UN sources.
• Handle sensitive geopolitical data with care -- Country names, borders, and sovereignty status can be politically sensitive. Be mindful of how you present this data in user-facing applications.
• Comply with Apify terms of service -- Use the actor and Apify platform in accordance with the Apify Terms of Service and fair usage policies.

---

FAQ

Q: How many countries does the REST Countries API cover? A: The API covers over 250 countries and territories worldwide, including sovereign states, dependent territories, overseas regions, and special administrative areas.

Q: Does this actor require an API key? A: No. The REST Countries API is free and open. No API key, authentication token, or paid subscription is required. The actor works out of the box with no additional configuration.

Q: What happens if I provide multiple search fields? A: The actor uses a deterministic priority order: countryCode > searchQuery > capital > region > language > currency. Only the highest-priority field that has a value is used. The remaining fields are ignored for that run.

Q: Can I get all countries at once? A: Yes. Leave all search fields empty and set maxResults to 250. The actor will call the /all endpoint and return every country and territory in the database.

Q: What is the difference between cca2 and cca3 codes? A: The cca2 field is the ISO 3166-1 alpha-2 code (two letters, e.g., "US", "DE", "JP"). The cca3 field is the ISO 3166-1 alpha-3 code (three letters, e.g., "USA", "DEU", "JPN"). Both are internationally recognized. Most applications use alpha-2 codes, but alpha-3 codes are common in the borders field.

Q: How often is the country data updated? A: The REST Countries API is maintained by the open-source community and updated periodically. Population figures, currency details, and political status reflect the most recent data available in the API. Schedule recurring runs to keep your local dataset current.

Q: Can I filter by multiple criteria in one run? A: Not directly. The actor calls one API endpoint per run based on input priority. To combine filters (e.g., European countries that speak French), run a region query for "Europe", then post-process the results to filter by language in your downstream workflow.

Q: What format can I export the results in? A: The Apify dataset supports export to JSON, CSV, Excel (XLSX), XML, RSS, and HTML. You can download manually from the Console or fetch programmatically via the Apify API.

Q: How do I look up a country by its ISO code? A: Enter the code in the countryCode field. Both alpha-2 codes (e.g., "US", "FR") and alpha-3 codes (e.g., "USA", "FRA") are supported. The countryCode field has the highest search priority, so it will always be used if provided.

Q: What does the Gini field represent? A: The Gini index measures income inequality within a country on a scale of 0 (perfect equality) to 100 (maximum inequality). The field is an object keyed by year (e.g., {"2018": 41.4}), representing the most recent measurement year available.

Q: Does the actor handle countries with no capital city? A: Yes. Some territories and special entities do not have a designated capital. In these cases, the capital field returns an empty array and capitalLatLng returns null.

---

Related actors

Actor	Description
Currency Exchange Rate Tracker	Get real-time currency exchange rates for 150+ currencies with automatic conversion calculations.
Historical Exchange Rate Data	Look up past exchange rates between any two currencies for a specific date or date range.
Nominatim Geocoder	Convert addresses, place names, and coordinates using OpenStreetMap Nominatim geocoding.
World Bank Development Indicators	Access global development statistics, economic indicators, and demographic data by country.
Country Holidays Search	Find public holidays, bank holidays, and observances for any country and year.
Open Charge Map EV Stations	Search for electric vehicle charging stations worldwide with location and connector details.