# Countries Data Scraper — Population, Capitals & More (`hipersoft/restcountries-scraper`) Actor

Fetch country reference data in bulk as clean JSON, CSV or Excel: name, ISO codes, capital, region, population, area, languages, currencies, borders, coordinates, timezones, flags and calling codes. Get all countries, or filter by name, region or ISO code.

- **URL**: https://apify.com/hipersoft/restcountries-scraper.md
- **Developed by:** [hiper soft](https://apify.com/hipersoft) (community)
- **Categories:** Other, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.0004 / country scraped

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

## Countries Data Scraper — Population, Capitals & More

Pull **reference data for every country in the world** as clean, structured **JSON, CSV, Excel or XML**. Get common and official names, **ISO codes, capital, region, population, area, languages, currencies, borders, coordinates, timezones, flags** and calling codes — for all countries at once, or filtered by **name, region or ISO code**. Ideal for dropdowns, forms, dashboards, data enrichment and automated pipelines.

### What does Countries Data Scraper do?

This actor turns world country data into a ready-to-use dataset. Choose a mode — all countries, by name, by region, or by ISO code — and it returns one tidy record per country with names, codes, capital, region, population, currencies, languages and more. Use it to seed a country/currency picker, enrich records with ISO codes, build a geography dashboard, or keep a fresh copy of country reference data on a schedule.

### What data can you get?

| Field | Description |
| --- | --- |
| `name` | Object with the country's `common` and `official` name. |
| `cca2` | Two-letter ISO 3166-1 country code (e.g. `SG`). |
| `cca3` | Three-letter ISO 3166-1 country code (e.g. `SGP`). |
| `capital` | Capital city or cities. |
| `region` | Region (e.g. Asia, Europe, Americas). |
| `subregion` | Subregion (e.g. South-Eastern Asia). |
| `population` | Population count. |
| `area` | Land area in km². |
| `languages` | Spoken languages as code → name pairs. |
| `currencies` | Currencies as code → `{ name, symbol }` pairs. |
| `borders` | Three-letter codes of bordering countries. |
| `latlng` | Latitude and longitude of the country. |
| `flag` | URL of the country's flag as a PNG image. |
| `timezones` | Timezones observed in the country. |
| `tld` | Internet top-level domain(s), e.g. `.sg`. |
| `callingCodes` | International dialling code(s), e.g. `+65`. |

### Use cases

- **Dropdowns & forms** — populate country, currency or dialling-code pickers with correct ISO codes.
- **Data enrichment** — add capital, region, population or currency to your existing records by ISO code.
- **Dashboards & maps** — power geography, demographics or logistics dashboards.
- **Localization** — map users to region, timezone, currency and language.
- **Data pipelines** — feed structured country reference data into BI tools, notebooks or apps.

### How to use it

1. Add **Countries Data Scraper** to your Apify account and open its input.
2. Pick a **mode**: all countries, by name, by region, or by ISO code.
3. Fill in the matching field — **names**, **region**, or **codes** — for the filtered modes.
4. Optionally set **fields** to keep only the columns you need, and **maxItems** to cap the output.
5. Click **Run**, then export the results as JSON, CSV, Excel or XML.

### Input

```json
{
  "mode": "byRegion",
  "region": "Europe"
}
```

| Field | Description |
| --- | --- |
| `mode` | `all`, `byName`, `byRegion` or `byCode`. |
| `names` | For `byName`: country names to match (partial, case-insensitive). |
| `region` | For `byRegion`: a single region, e.g. `Europe`. |
| `codes` | For `byCode`: two- or three-letter ISO codes, e.g. `US`, `SG`, `JPN`. |
| `fields` | Optional allow-list of output fields to keep. Empty = all fields. |
| `maxItems` | Cap the number of countries returned. `0` = no limit. |

### What you get

One flat JSON record per country, ready to export to CSV, Excel, JSON or XML.

```json
{
  "name": { "common": "Singapore", "official": "Republic of Singapore" },
  "cca2": "SG",
  "cca3": "SGP",
  "capital": ["Singapore"],
  "region": "Asia",
  "subregion": "South-Eastern Asia",
  "population": 5685807,
  "area": 710,
  "languages": { "eng": "English", "msa": "Malay", "tam": "Tamil", "zho": "Chinese" },
  "currencies": { "SGD": { "name": "Singapore dollar", "symbol": "$" } },
  "borders": [],
  "latlng": [1.36666666, 103.8],
  "flag": "https://flagcdn.com/w320/sg.png",
  "timezones": ["UTC+08:00"],
  "tld": [".sg"],
  "callingCodes": ["+65"]
}
```

### FAQ

**How do I get every country?**
Set `mode` to `all`. You'll get one record for every country.

**How do I look up specific countries?**
Use `mode: "byCode"` with a list of ISO codes (`US`, `SG`, `JPN`), or `mode: "byName"` with country names (partial matches work).

**How do I get all countries in a region?**
Use `mode: "byRegion"` with one of: Africa, Americas, Antarctic, Asia, Europe, Oceania.

**Can I return only some fields?**
Yes — set `fields` to an allow-list, e.g. `["name", "cca2", "capital", "population"]`, to keep just those columns.

**What export formats are available?**
JSON, CSV, Excel and XML, plus programmatic access through the Apify API.

**Can I use this with n8n?**
Yes. Run it from the [Apify n8n community node](https://apify.com/integrations/n8n) or trigger it over HTTP, then pass the dataset items straight into your n8n workflow to build dropdowns, enrich records or drive downstream steps.

**Can I connect this to my other tools?**
It works with [Make](https://apify.com/integrations/make), [Zapier](https://apify.com/integrations/zapier), [Slack](https://docs.apify.com/platform/integrations/slack), [Airbyte](https://docs.apify.com/platform/integrations/airbyte), [GitHub](https://docs.apify.com/platform/integrations/github), [Google Drive](https://docs.apify.com/platform/integrations/drive) and [many more](https://apify.com/integrations), plus the [Apify API](https://docs.apify.com/api/v2), JavaScript/Python clients and MCP. Or use [webhooks](https://docs.apify.com/platform/integrations/webhooks) to trigger an action whenever a run finishes.

**How fresh is the data?**
Static fields such as codes, capitals and borders change rarely; dynamic figures like population reflect the latest published values at run time. Re-run on a schedule to keep your copy current.

### Related Actors

- [World Bank Indicators Scraper](https://apify.com/hipersoft/worldbank-indicators-scraper) — GDP, population, inflation and thousands more indicators by country and year.
- [Open-Meteo Weather Scraper](https://apify.com/hipersoft/open-meteo-weather-scraper) — free weather forecasts and history for any coordinates.
- [CoinGecko Scraper](https://apify.com/hipersoft/coingecko-scraper) — live crypto prices, market cap and volume.

### Notes

Original clean-room implementation. Returns only public country reference data; you are responsible for compliant use. Country names and boundaries are provided for reference and do not imply any political position. All trademarks belong to their respective owners.

# Actor input Schema

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

How to select countries. "All countries" returns every country. "By name" filters by the names you list. "By region" returns every country in one region. "By ISO code" returns the exact countries whose two- or three-letter ISO codes you list.

## `names` (type: `array`):

Used when mode is "By name". One or more country names to match (partial, case-insensitive), e.g. "Singapore", "united", "korea". Matches common, official and native names.

## `region` (type: `string`):

Used when mode is "By region". A single region name: Africa, Americas, Antarctic, Asia, Europe or Oceania.

## `codes` (type: `array`):

Used when mode is "By ISO code". Two-letter (cca2) or three-letter (cca3) ISO country codes, e.g. "US", "SG", "JPN". Case-insensitive.

## `fields` (type: `array`):

Optional allow-list of output fields to keep, e.g. "name", "cca2", "capital", "population". Leave empty to return every field. Valid names: name, cca2, cca3, capital, region, subregion, population, area, languages, currencies, borders, latlng, flag, timezones, tld, callingCodes.

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

Maximum number of countries to output. 0 = no limit.

## Actor input object example

```json
{
  "mode": "all",
  "names": [
    "Singapore",
    "Japan"
  ],
  "region": "Europe",
  "codes": [
    "US",
    "SG",
    "JP"
  ],
  "fields": [
    "name",
    "cca2",
    "capital",
    "population"
  ],
  "maxItems": 0
}
```

# Actor output Schema

## `results` (type: `string`):

The results as dataset items.

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("hipersoft/restcountries-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 = {}

# Run the Actor and wait for it to finish
run = client.actor("hipersoft/restcountries-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 '{}' |
apify call hipersoft/restcountries-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,hipersoft/restcountries-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/fIv2uSlfTuIRiyFbE/builds/ETkxaKdoDuimVl4N3/openapi.json