# FlagCDN Flag Size & Format Variants Scraper (`acquistion-automation/flagcdn-flag-size-format-scraper`) Actor

Scrapes FlagCDN country codes and names, then returns each one with a flag image URL built from your chosen width and file format. Export the full list to CSV, JSON, Excel, or XML.

- **URL**: https://apify.com/acquistion-automation/flagcdn-flag-size-format-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 $3.62 / 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 Flag Size & Format Variants Scraper

**Scrape flag image size and format variants from FlagCDN for every country code, up to a million rows per run.** Each row returns the country code, country name, and the direct image URL built from your chosen dimensions and file type. Export to CSV, JSON, Excel, or XML.

FlagCDN serves flag images in many sizes and formats, but there is no single download that lists every variant for every country. This actor reads the public country codes API, then constructs the exact image URL for the size and format you pick, so you get a complete dataset in one run.

| Who uses it | What they scrape FlagCDN for |
|---|---|
| Frontend developers | Generate a full list of flag image URLs to embed in a country picker or language selector. |
| Data analysts | Build a reference table of country codes and their flag assets for a reporting dashboard. |
| Designers | Pull every flag in a consistent size and format for a UI mockup or icon set. |
| Educators | Collect flag images for geography quizzes or classroom materials. |

### What it does

This Actor collects FlagCDN country codes and names, then returns each one with a flag image URL built from your selected width and file format.

- 🏁 **Country code and name:** every row includes the ISO 3166-1 alpha-2 code and the official country name from FlagCDN.
- 📐 **Size selection:** pick from 16, 24, 32, 48, 64, 128, 256, 512, 1024, or 2048 pixels wide.
- 🖼️ **Format selection:** choose PNG, SVG, WebP, AVIF, or JPEG XL for the output image URL.
- 🔗 **Direct image URL:** each record contains the fully constructed FlagCDN URL you can use immediately.

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

### What you can do with FlagCDN data

**🌐 Populate a country selector.**

A frontend developer runs the actor with size 32 and format PNG to get every flag URL, then feeds the dataset into a React country dropdown.

**📊 Build a flag reference table.**

A data analyst scrapes all country codes with 256px WebP URLs and joins them to a sales table so the BI dashboard shows a flag next to each country.

**🎨 Create a design asset pack.**

A UI designer pulls every flag as SVG at 512px, then batches them into a Figma library for a travel app redesign.

**📚 Prepare classroom materials.**

An educator collects 128px PNG flags for every country and prints them as flash cards for a geography lesson.

### Why choose this scraper

| | What you get |
|---|---|
| **One run, all countries** | Get every flag variant without writing a loop or manually constructing URLs. |
| **Consistent output** | Every row follows the same flat schema, ready for your database or frontend. |
| **No API key needed** | FlagCDN's public codes endpoint requires no authentication. |
| **Flexible formats** | Switch between raster and vector formats by changing one input field. |

### What a FlagCDN record looks like

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

```json
{
 "imageUrl": "https://flagcdn.com/256/ad.png",
 "countryCode": "ad",
 "countryName": "Andorra",
 "size": "256",
 "format": "png",
 "scrapedAt": "2026-09-26T12:20:42.452Z"
}
```

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 by setting a maximum item count, a flag width in pixels, and an image format. The actor reads the full country list and builds one URL per country. The Input tab lists every parameter.

A first run with the defaults:

```json
{
 "maxItems": 10,
 "size": "256",
 "format": "png"
}
```

A larger pull:

```json
{
 "maxItems": 200,
 "size": "256",
 "format": "png"
}
```

### 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 with $5 in credit](https://console.apify.com/sign-up).
2. Open the [FlagCDN Flag Size & Format Variants Scraper](https://apify.com/acquistion-automation/flagcdn-flag-size-format-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-flag-size-format-scraper"
```

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

### Troubleshooting

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

Free Apify accounts are limited to 10 items per run. Upgrade to a paid plan to increase the max items limit and get all country codes.

**The image URL returns a 404 error.**

Check that the size and format you selected are valid. FlagCDN may not have every combination for every country. Try a common size like 256 and format PNG first.

**Can I get the flag in a custom size not in the dropdown?**

The actor supports only the sizes listed in the input. For a custom width, you can take the SVG URL and scale it in your application, or download the nearest PNG size and resize it.

**The actor runs but the dataset is empty.**

Make sure you have not set maxItems to 0. Also confirm that the FlagCDN codes endpoint is reachable from your network. A quick test is to open https://flagcdn.com/en/codes.json in a browser.

### FAQ

| Question | Answer |
|---|---|
| Does this actor download the flag images themselves? | No. It returns the direct image URL for each country. You can use those URLs in your application or download the files separately. |
| What sizes can I request? | You can choose from 16, 24, 32, 48, 64, 128, 256, 512, 1024, and 2048 pixels wide. The height is determined automatically by the aspect ratio. |
| Which image formats are supported? | PNG, SVG, WebP, AVIF, and JPEG XL. SVG gives you a vector flag that scales to any size without losing quality. |
| Do I need a FlagCDN API key? | No. The actor uses the public codes.json endpoint, which requires no authentication or registration. |
| How many items can I scrape? | Free Apify users can scrape up to 10 items as a preview. Paid users can scrape up to 1,000,000 items, which covers every country code many times over. |
| Can I filter by specific countries? | The actor returns all available country codes. You can filter the output dataset afterward using a tool like Excel or a short script. |
| What does the output look like? | Each row contains the country code, the country name, and the full flag image URL built from your chosen size and format. |
| Is the country list up to date? | The actor reads the live codes.json file from FlagCDN on each run, so you always get the current list of country codes and names. |

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

## `size` (type: `string`):

Width of the flag image in pixels. Common sizes: 16, 24, 32, 48, 64, 128, 256, 512, 1024, 2048.

## `format` (type: `string`):

File format for the flag image.

## Actor input object example

```json
{
  "maxItems": 10,
  "size": "256",
  "format": "png"
}
```

# 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,
    "size": "256",
    "format": "png"
};

// Run the Actor and wait for it to finish
const run = await client.actor("acquistion-automation/flagcdn-flag-size-format-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,
    "size": "256",
    "format": "png",
}

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

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,acquistion-automation/flagcdn-flag-size-format-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/XexT0iExV4dblfhuA/builds/KTVap3xb71sCBJpMS/openapi.json