# FlagCDN Emoji Lookup Scraper (`acquistion-automation/flagcdn-emoji-lookup-scraper`) Actor

Pull country flag emoji data from FlagCDN's codes.json API. Retrieve ISO country codes and country names for all 249 nations and territories. Use the results to build emoji pickers, localization tools, or geographic datasets. Each record includes the two-letter ISO code and the full country name.

- **URL**: https://apify.com/acquistion-automation/flagcdn-emoji-lookup-scraper.md
- **Developed by:** [Acquisition Automation Co.](https://apify.com/acquistion-automation) (community)
- **Categories:** Developer tools, Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $4.79 / 1,000 results

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?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

[![Acquisition Automation](https://api.apify.com/v2/key-value-stores/AOdPHdOpeDpzEPS5f/records/banner.jpg)](https://apify.com/acquistion-automation)

### FlagCDN Emoji Lookup Scraper

**Scrape FlagCDN emoji country codes and names from the official codes.json API.** Get every ISO country code mapped to its country name in one flat dataset. No login, no API key, no browser. Export to CSV, JSON, Excel, or XML.

FlagCDN publishes a public codes.json endpoint that maps ISO country codes to country names, but there is no official download page or bulk export tool. This Actor reads that endpoint directly and returns every mapping as a clean row. It is the fastest way to get the full FlagCDN emoji country code list into your own dataset.

| Who uses it | What they scrape FlagCDN for |
|---|---|
| Frontend developers | Build a country flag emoji picker without hardcoding the ISO code list |
| Data analysts | Get a clean country code to country name reference table for joins |
| Localization teams | Verify which ISO country codes FlagCDN supports before integrating |
| Indie hackers | Seed a country selector or flag emoji component with real data |

### What it does

This Actor collects the complete FlagCDN emoji country code mapping from the official codes.json API and returns each ISO code and country name as a flat row.

- 🌍 **Full country list:** every ISO country code and country name from the official FlagCDN codes.json endpoint.
- ⚡ **One API call:** the Actor hits the verified endpoint once and returns the complete mapping, no pagination needed.
- 📦 **Flat row output:** each result is a single row with the ISO code and country name, ready for CSV, JSON, Excel, or XML export.
- 🔢 **Max items control:** set maxItems to limit the preview or pull the full list up to 1,000,000 rows for paid users.

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

### What you can do with FlagCDN data

**🌍 Build a flag emoji picker.**

A frontend developer runs the Actor once to get the full FlagCDN emoji country code list, then feeds the ISO codes into a country selector component.

**📊 Create a country reference table.**

A data analyst scrapes the FlagCDN emoji JSON to build a clean ISO code to country name lookup table for joining with other datasets.

**🧪 Verify FlagCDN coverage.**

A localization engineer runs the Actor to check which ISO country codes FlagCDN supports before committing to the service.

**🛠️ Seed a side project.**

An indie hacker pulls the FlagCDN emoji database to populate a country dropdown or flag emoji feature without writing a scraper from scratch.

### Why choose this scraper

| | What you get |
|---|---|
| **No API key** | The FlagCDN codes.json endpoint is public, so you can start scraping immediately |
| **Official source** | Data comes straight from the verified FlagCDN API, not a third party mirror |
| **One flat schema** | Every row has the same ISO code and country name fields, no nested JSON to flatten |
| **Bulk export ready** | Output goes directly to CSV, JSON, Excel, or XML for your pipeline |

### What a FlagCDN record looks like

Every record returns as one flat JSON row. Here is a real one from a run:

```json
{
 "isoCode": "ad",
 "countryName": "Andorra",
 "flagUrl": "https://flagcdn.com/w40/ad.png",
 "flagEmoji": "🇦🇩"
}
```

Every value above comes from a real run. A field a record does not have comes back as `null`.

### Configure the run

Drive the Actor with a single maxItems setting. Free users get a 10 item preview, paid users can pull the full FlagCDN emoji country code list up to 1,000,000 rows. The Input tab lists every parameter.

A first run with the defaults:

```json
{
 "maxItems": 10
}
```

A larger pull:

```json
{
 "maxItems": 200
}
```

### Free users

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

### Run it

1. [Create a free Apify account](https://console.apify.com/sign-up).
2. Open the [FlagCDN Emoji Lookup Scraper](https://apify.com/acquistion-automation/flagcdn-emoji-lookup-scraper).
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 FlagCDN 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=acquistion-automation/flagcdn-emoji-lookup-scraper"
```

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

### Troubleshooting

**Why am I getting only 10 items?**

Free users are limited to a 10 item preview. Upgrade to a paid plan and set maxItems higher to pull the full FlagCDN emoji country code list.

**Why is my run returning no results?**

Check that maxItems is set to at least 1. The FlagCDN endpoint is public and stable, so an empty result usually means the input was set to zero or the run failed before the API call.

**Can I get the flag emoji characters themselves?**

No. This Actor returns the ISO country code and country name mapping. Flag emoji characters are rendered from the ISO codes by your application, not stored in the codes.json data.

**Why does the output have only two fields?**

The FlagCDN codes.json endpoint only contains ISO country codes and country names. That is the complete data available from this source.

### FAQ

| Question | Answer |
|---|---|
| What does the FlagCDN emoji lookup scraper return? | It returns every ISO country code mapped to its country name from the official FlagCDN codes.json endpoint. Each row has isoCode, countryName, flagUrl, and flagEmoji. |
| Do I need an API key for FlagCDN? | No. The codes.json endpoint is public and requires no authentication. The Actor reads it directly. |
| How many items can I scrape? | Free users get a 10 item preview. Paid users can set maxItems up to 1,000,000, which covers the full FlagCDN country code list many times over. |
| Is this the same data as the FlagCDN website? | Yes. The Actor calls the verified https://flagcdn.com/en/codes.json endpoint, which is the same source the FlagCDN site uses for its country flag emoji data. |
| What export formats are supported? | You can export the results to CSV, JSON, Excel, or XML directly from the Apify dataset. |
| Does this Actor scrape flag images? | No. It scrapes the ISO country code to country name mapping only. Flag images are served separately by FlagCDN and are not part of this Actor's output. |
| How often is the FlagCDN data updated? | The Actor reads the live codes.json endpoint on every run, so you always get the current mapping from FlagCDN. |
| Can I filter by country name or ISO code? | The Actor returns the full list. You can filter the exported dataset in your own pipeline or use maxItems to limit the preview size. |

### Related actors

Browse the full [Acquisition Automation collection](https://apify.com/acquistion-automation) for more scrapers.

🆘 **Need help?** Open an issue in the Issues tab of this Actor with your run ID, your input, and what you expected.

### Pricing

This Actor uses **pay-per-result** pricing: **$0.00529 per result** collected. You are billed only for the results you receive, so a run that returns nothing costs nothing.

⚠️ **Disclaimer.** This Actor is unofficial and is not affiliated with, endorsed by, or sponsored by FlagCDN. 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`):

Free users: Limited to 10 items (preview). Paid users: Optional, max 1,000,000

## Actor input object example

```json
{
  "maxItems": 10
}
```

# Actor output Schema

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

Complete dataset of all scraped records.

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

// Run the Actor and wait for it to finish
const run = await client.actor("acquistion-automation/flagcdn-emoji-lookup-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 }

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

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,acquistion-automation/flagcdn-emoji-lookup-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/9M7JVdzfAQif3n3EK/builds/TeWEMgmPjI7nWE6D1/openapi.json