# FlagCDN Flag Image Metadata Scraper (`acquistion-automation/flagcdn-flag-metadata-scraper`) Actor

Scrapes flag image metadata from FlagCDN by country code and width. Returns each flag as a row with its URL, format, dimensions, file size, and last-modified header.

- **URL**: https://apify.com/acquistion-automation/flagcdn-flag-metadata-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 $14.69 / 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 Image Metadata Scraper

**Scrape flag image metadata from FlagCDN for any country code, width, or the full country list.** Each row returns the image URL, format, dimensions, file size, and last-modified header. No API key required. Export to CSV, JSON, Excel, or XML.

FlagCDN serves flag images for every country but its public API only returns country codes and names. This actor reads the full country list from the API, then makes HEAD requests to each flag image URL to extract the metadata that the API does not expose. You get the image format, width, height, file size, and last-modified date for every flag you request.

| Who uses it | What they scrape FlagCDN for |
|---|---|
| Frontend developers | Build a flag picker component with correct image dimensions and file sizes to avoid layout shift. |
| Data analysts | Audit a flag dataset to confirm every country code resolves to a live image and record its attributes. |
| QA engineers | Verify that a CDN migration preserved all flag images and their metadata. |
| Content managers | Generate a manifest of flag assets with last-modified dates to track updates. |

### What it does

This Actor collects flag image metadata from FlagCDN by country code and image width, and returns each flag as a flat row with its URL, format, dimensions, file size, and last-modified timestamp.

- 🌐 **Full country list:** Leave country codes empty to process every country FlagCDN knows about.
- 🎯 **Targeted codes:** Provide a list of ISO 3166-1 alpha-2 codes to scrape only the flags you need.
- 📐 **Selectable width:** Choose from 20, 40, 80, 160, 320, 640, 1280, or 2560 pixels wide.
- 📦 **Flat row output:** Each flag becomes one row with its URL, format, width, height, file size, and last-modified date.

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

### What you can do with FlagCDN data

**🌐 Build a flag asset inventory.**

A frontend team scrapes all flags at 160px wide to document every image URL, its dimensions, and file size before integrating them into a design system.

**🔍 Validate a country code list.**

A data engineer feeds a list of 50 country codes into the actor to confirm each one returns a 200 response and records the last-modified date for freshness checks.

**📊 Compare image sizes across widths.**

A performance analyst runs the actor at 80px, 160px, and 320px for the same 10 countries to chart how file size scales with width.

**🔄 Monitor CDN updates.**

A DevOps engineer schedules a weekly scrape of all flags at 2560px and diffs the last-modified timestamps to detect when FlagCDN refreshes its images.

### Why choose this scraper

| | What you get |
|---|---|
| **No API key** | FlagCDN's public API and image endpoints need no authentication. |
| **Image metadata** | Get format, dimensions, file size, and last-modified header for every flag. |
| **Flexible scope** | Scrape one flag, a custom list, or the entire country catalog. |
| **Structured export** | Download results as CSV, JSON, Excel, or XML for any downstream tool. |

### What a FlagCDN record looks like

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

```json
{
 "url": "https://flagcdn.com/w80/ad.png",
 "id": "ad",
 "countryCode": "ad",
 "countryName": "Andorra",
 "imageUrl": "https://flagcdn.com/w80/ad.png",
 "width": 80,
 "height": 56,
 "format": "png",
 "fileSize": 600,
 "lastModified": "Tue, 01 Jul 2025 15:39:52 GMT",
 "status": "success"
}
```

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 from a list of ISO 3166-1 alpha-2 country codes and a target image width. Leave the country list empty to process every available flag, and set a max items limit to control the run size. The Input tab lists every parameter.

A first run with the defaults:

```json
{
 "maxItems": 10,
 "imageWidth": "80"
}
```

A larger pull:

```json
{
 "maxItems": 200,
 "imageWidth": "80"
}
```

### 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 Image Metadata Scraper](https://apify.com/acquistion-automation/flagcdn-flag-metadata-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-metadata-scraper"
```

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

### Troubleshooting

**Why am I getting no results?**

Check that your country codes are valid ISO 3166-1 alpha-2 codes. If you left the list empty, the actor fetches the full list from FlagCDN. Also verify your max items is not set to zero.

**Why is the file size zero for some flags?**

FlagCDN may not always return a Content-Length header. The actor records whatever the server sends. A missing header results in a zero or null value.

**Why do I get a 404 for a country code?**

The code may not exist in FlagCDN's current list. The actor fetches the official code list first, but if you supply a custom code that is not served, it will record the HTTP status.

**Why is the run slow with many countries?**

Each flag requires a separate HEAD request. Processing hundreds of countries takes time. Reduce the country list or increase the run timeout.

### FAQ

| Question | Answer |
|---|---|
| Does this actor download the flag images? | No. It makes HEAD requests to read the HTTP headers only. You get the metadata without downloading the image body. |
| What metadata fields does it return? | Each row includes the image URL, content type, width, height, file size in bytes, and the last-modified header. |
| Can I scrape all country flags in one run? | Yes. Leave the country codes input empty and the actor will fetch the full country list from FlagCDN's API, then process every flag. |
| What image widths are available? | FlagCDN serves flags at 20, 40, 80, 160, 320, 640, 1280, and 2560 pixels wide. You pick one width per run. |
| Do I need an API key for FlagCDN? | No. FlagCDN's codes.json endpoint and image URLs are publicly accessible with no authentication. |
| How do I limit the number of flags scraped? | Set the max items field. On the Free plan the limit is 10 items. Paid plans can go up to 1,000,000. |
| What format are the country codes? | Use ISO 3166-1 alpha-2 codes, like 'us' for the United States or 'de' for Germany. |
| Can I export the results? | Yes. The dataset can be exported to CSV, JSON, Excel, or XML from the Apify run page. |

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

## `imageWidth` (type: `string`):

Width of the flag image in pixels. FlagCDN serves images at widths like 20, 40, 80, 160, 320, 640, 1280, and 2560.

## `countryCodes` (type: `array`):

Optional list of ISO 3166-1 alpha-2 country codes to scrape. Leave empty to process all available countries from the API.

## Actor input object example

```json
{
  "maxItems": 10,
  "imageWidth": "80"
}
```

# 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,
    "imageWidth": "80"
};

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

# Run the Actor and wait for it to finish
run = client.actor("acquistion-automation/flagcdn-flag-metadata-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,
  "imageWidth": "80"
}' |
apify call acquistion-automation/flagcdn-flag-metadata-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-metadata-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/Yf0zapiEK7eRL0XEA/builds/RpCaitmiM8W1OcgiZ/openapi.json