# REST Countries Reference Data Scraper (`parseforge/rest-countries-scraper`) Actor

Pull rich reference data on every country: official + common names, capital, currencies, languages, region, demonym, calling code, top-level domain, area, population, flag, coat-of-arms, timezones, borders, IDD. Filter by name, code, region, or currency.

- **URL**: https://apify.com/parseforge/rest-countries-scraper.md
- **Developed by:** [ParseForge](https://apify.com/parseforge) (community)
- **Categories:** Education, Travel, Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $10.00 / 1,000 result items

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

[![ParseForge](https://raw.githubusercontent.com/ParseForge/apify-assets/main/banner.jpg)](https://apify.com/parseforge?fpr=vmoqkp)

### REST Countries Reference Data Scraper

**Scrape country reference data from REST Countries, up to a million records per run.** Every country comes with its name, codes, capital, region, subregion, currencies, languages, population, area, and more. No API key or login. Export to CSV, JSON, Excel, or XML.

REST Countries is a free public API that provides reference data for every country in the world, but querying it directly means writing code, handling pagination, and parsing nested JSON. This Actor reads the API for you, filters by name, code, region, subregion, currency, language, or capital, and returns each country as one flat row. No registration, no rate limits to manage, no code to write.

| Who uses it | What they scrape REST Countries for |
|---|---|
| Data analysts | Building a clean country reference table for joins and lookups |
| Market researchers | Segmenting countries by region, language, or currency for reports |
| App developers | Populating a country picker or localization settings |
| Logistics teams | Mapping country codes to names and capitals for shipping rules |
| Educators | Downloading a current country dataset for geography lessons |

### What it does

This Actor collects country records from the REST Countries API by lookup mode and returns each country as a flat row with its name, ISO codes, capital, region, subregion, currencies, languages, population, area, and other reference fields.

- 🌍 **All countries:** collect every country in one run, up to your maxItems limit.
- 🔎 **Lookup by name:** get one country by its common name, like Spain or Japan.
- 🏷️ **Lookup by code:** pass ISO-2 or ISO-3 codes, semicolon-separated, like US;FR;JP.
- 🗺️ **Lookup by region or subregion:** filter to Africa, Europe, South America, or any subregion.
- 💱 **Lookup by currency:** find every country that uses EUR, USD, JPY, or any ISO 4217 code.
- 🗣️ **Lookup by language:** list countries where Spanish, English, French, or Mandarin is spoken.
- 🏛️ **Lookup by capital:** find the country for a capital city like Tokyo, London, or Brasília.

Results export to CSV, JSON, Excel, or XML, or straight from the API.

### What you can do with REST Countries data

**📊 Build a country reference table.**

A data analyst runs the Actor in all mode with maxItems 250 and exports the CSV to join country codes with sales data.

**🌐 Segment markets by language.**

A market researcher looks up countries by language Spanish and uses the list to plan a localized campaign.

**💱 Find currency zones.**

A fintech product manager looks up countries by currency EUR to see which markets share the euro.

**🗺️ Filter by region for reporting.**

An operations manager looks up countries by region Asia and downloads the JSON to feed a regional dashboard.

**🏛️ Resolve capital cities.**

A logistics developer looks up countries by capital Tokyo and gets the ISO codes needed for shipping rules.

### Why choose this scraper

|  | What you get |
|---|---|
| **No API key or login** | The Actor calls the public REST Countries API directly, so you can start a run immediately. |
| **Flat, consistent rows** | Nested fields like currencies and languages are flattened into a fixed schema for easy export. |
| **Flexible lookups** | Filter by name, ISO code, region, subregion, currency, language, or capital in one input. |
| **Up to a million records** | Set maxItems as high as you need, from one country to the entire dataset. |
| **Multiple export formats** | Download results as CSV, JSON, Excel, or XML from the Apify dataset. |

### How it compares

No other Store actor targets REST Countries the same way, so the honest comparison is with the alternatives teams actually weigh.

| | REST Countries Reference Data Scraper | Build it in-house | By hand |
|---|---|---|---|
| Setup | Run it now, zero config | Days of engineering | None, but hours per pull |
| When REST Countries changes | Maintained for you | You fix it | You re-learn the page |
| Proxies, retries, anti-bot | Built in | Your problem | Browser only |
| Output | Fixed JSON schema, CSV/Excel export | Whatever you build | Copy-paste |
| Cost | Pay per result | Engineering time | Analyst hours |

### Configure the run

Drive the Actor from a lookup mode and value, and set a maximum number of countries to collect per run. Filters run as each record is read so only matches reach your dataset. The Input tab lists every parameter.

A first run with the defaults:

```json
{
  "maxItems": 10,
  "mode": "all"
}
```

A larger pull:

```json
{
  "maxItems": 200,
  "mode": "all"
}
```

### Pricing

Pay-per-result: **$0.01333 per result** collected. You pay only for the results written to your dataset.

| Results collected | Approximate cost |
|---|---|
| 100 results | $1.33 |
| 1,000 results | $13.33 |
| 10,000 results | $133.30 |

New Apify accounts start with $5 in free credit.

### Free users

Free-plan runs return up to 10 results as a preview. [Upgrade your Apify plan](https://console.apify.com/sign-up?fpr=vmoqkp) to collect up to 1,000,000 results per run.

### Run it

1. [Create a free Apify account with $5 in credit](https://console.apify.com/sign-up?fpr=vmoqkp).
2. Open the [REST Countries Reference Data Scraper](https://apify.com/parseforge/rest-countries-scraper?fpr=vmoqkp).
3. Set your inputs and any filters, then click **Start**.
4. Export the results as CSV, Excel, JSON, or XML from the **Dataset** tab.

Run it programmatically through the [Apify API](https://docs.apify.com/api/v2) (`run-sync-get-dataset-items`) or the [ApifyClient](https://docs.apify.com/api/client/js) for JavaScript and Python.

### Use with AI agents (MCP)

Give an AI agent live access to REST Countries through the Model Context Protocol. Add the Actor to Claude, Cursor, or any MCP client:

```bash
claude mcp add --transport http apify "https://mcp.apify.com/?tools=parseforge/rest-countries-scraper"
```

Then prompt it in plain language to run the scraper and read back the results.

### Troubleshooting

**Why am I getting no results?**

Check your lookup value for typos and make sure it matches the expected format for the mode. For example, currency codes must be 3-letter ISO 4217 codes, and region names must be one of the listed values.

**Why did I get fewer results than maxItems?**

The Actor returns only the countries that match your lookup. If you used a specific mode and value, there may be fewer matches than your maxItems limit. Try all mode to get every country.

**Why is the capital field empty for some countries?**

Some countries in the REST Countries API do not have a capital listed, such as Antarctica. This is expected and not an error.

**Why are currencies and languages returned as objects?**

The Actor flattens nested fields into a fixed schema, but some fields like currencies and languages may still contain structured data. You can parse them further in your downstream tool.

**Can I filter by multiple languages or currencies at once?**

The current input accepts one lookup value per run. To get countries for multiple languages or currencies, run the Actor multiple times with different values and merge the results.

### FAQ

| Question | Answer |
|---|---|
| What is REST Countries? | REST Countries is a free public API that provides reference data for every country in the world, including names, codes, capitals, regions, currencies, languages, population, and area. This Actor scrapes that API and returns the data as flat rows. |
| Do I need an API key or login? | No. The Actor calls the public REST Countries API directly, so you can start a run immediately without any registration or credentials. |
| What lookup modes are available? | You can look up countries by name, ISO-2 or ISO-3 code, region, subregion, currency, language, or capital. You can also collect all countries in one run. |
| How do I pass multiple ISO codes? | In code mode, separate the codes with semicolons, for example US;FR;JP or USA;FRA;JPN. The Actor will return all matching countries. |
| What is the maximum number of countries I can collect? | You can set maxItems up to 1,000,000, which is more than the total number of countries in the world, so you can collect the entire dataset in one run. |
| What fields are returned for each country? | Each row includes the country name, ISO-2 and ISO-3 codes, capital, region, subregion, currencies, languages, population, area, and other reference fields from the API. |
| Can I export the results? | Yes. The Actor stores results in an Apify dataset, and you can export them as CSV, JSON, Excel, or XML from the Apify console or API. |
| Is the data current? | The Actor reads the live REST Countries API on each run, so the data reflects the latest information available from that source. |
| Can I schedule this Actor to run regularly? | Yes. You can set up a schedule in Apify to run the Actor daily, weekly, or at any interval, and it will always fetch the latest country data. |
| What if I get no results? | Check your lookup value for typos and make sure it matches the expected format for the mode. For example, currency codes must be 3-letter ISO 4217 codes, and region names must be one of the listed values. |

### Related actors

Browse the full [ParseForge collection](https://apify.com/parseforge?fpr=vmoqkp) for more scrapers.

🆘 **Need help?** Email parseforge@protonmail.com with your run ID, your input, and what you expected.

⚠️ **Disclaimer.** This Actor is unofficial and is not affiliated with, endorsed by, or sponsored by REST Countries. It collects only publicly available data. You are responsible for using the collected data in compliance with the source's terms of service and applicable data-protection laws, including GDPR, CCPA, and PIPL. Do not use it to collect personal data unlawfully.

# Actor input Schema

## `maxItems` (type: `integer`):

Maximum number of countries to collect per run.

## `mode` (type: `string`):

How to look up country records.

## `value` (type: `string`):

Value for the chosen lookup. By mode: name = country name (e.g. `Spain`); code = ISO-2 or ISO-3 codes, semicolon-separated (e.g. `US;FR;JP` or `USA;FRA;JPN`); region = one of `Africa`, `Americas`, `Asia`, `Europe`, `Oceania`, `Antarctic`; subregion = one of `Northern Africa`, `Sub-Saharan Africa`, `Northern America`, `Caribbean`, `South America`, `Central America`, `Central Asia`, `Eastern Asia`, `South-Eastern Asia`, `Southern Asia`, `Western Asia`, `Eastern Europe`, `Northern Europe`, `Southern Europe`, `Western Europe`, `Australia and New Zealand`, `Melanesia`, `Micronesia`, `Polynesia`; currency = 3-letter ISO 4217 code (e.g. `EUR`, `USD`, `JPY`, `GBP`); language = English language name (e.g. `Spanish`, `English`, `French`, `Mandarin`); capital = capital city name (e.g. `Tokyo`, `London`, `Brasília`). Ignored when mode is `all`.

## Actor input object example

```json
{
  "maxItems": 10,
  "mode": "all"
}
```

# Actor output Schema

## `overview` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "maxItems": 10,
    "mode": "all",
    "value": ""
};

// Run the Actor and wait for it to finish
const run = await client.actor("parseforge/rest-countries-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "maxItems": 10,
    "mode": "all",
    "value": "",
}

# Run the Actor and wait for it to finish
run = client.actor("parseforge/rest-countries-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "maxItems": 10,
  "mode": "all",
  "value": ""
}' |
apify call parseforge/rest-countries-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,parseforge/rest-countries-scraper"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/8aYB7T9B3wjRayFFg/builds/aBB8kEP23nD26tCa3/openapi.json