FlagCDN Flag Image Metadata Scraper

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:

{
 "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:

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

A larger pull:

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

Free users

Free-plan runs return up to 10 results as a preview. Upgrade your Apify plan to collect up to 1,000,000 results per run.

Run it

1. Create a free Apify account with $5 in credit.
2. Open the FlagCDN Flag Image 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 (run-sync-get-dataset-items) or the ApifyClient 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:

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