FlagCDN API
Free country flag CDN with no key: flag images in any width, SVG or PNG, plus a JSON map of every ISO country code to its name in 30+ languages. Tested example included.
Endpoint tested and returned HTTP 200 on 2026-08-21
What is the FlagCDN API?
FlagCDN is a free, key-free service that serves country flag images at any requested width in PNG or SVG, and publishes a JSON lookup of every ISO 3166-1 alpha-2 country code to its country name, available in more than thirty languages.
Flags are one of those assets that look trivial until you try to ship them. Aspect ratios differ wildly — Switzerland and Nepal are not 3:2 — file sizes matter on a country picker with two hundred rows, and someone always has to decide what to do about disputed territories. FlagCDN handles the first two by generating images at whatever width you ask for and caching them at the edge.
The endpoint documented here is the metadata half rather than the images: `/{lang}/codes.json` returns a flat object mapping each lowercase alpha-2 code to a country name, and swapping `en` for `de`, `ja`, `pt` or any other supported language localises the whole map in one request. That makes it a usable country-name lookup in its own right, and it pairs naturally with the image URLs, which follow the pattern `/w320/{code}.png` or `/{code}.svg` using the same codes as keys.
Quick facts
- Base URL
https://flagcdn.com- Authentication
- No key or account. Images and metadata are free for personal and commercial use, hotlinking explicitly permitted.
- Rate limit
- No published limit. Everything is served from a CDN and designed to be linked directly from production pages.
- Pricing
- Free.
- CORS
- Enabled — callable directly from browser JavaScript
- Official docs
- Read the docs
How to use the FlagCDN API
Every request below was executed against the live API on 2026-08-21, and the response shown is the real body it returned — not an illustration.
1. Fetch every ISO country code mapped to its English name
GET https://flagcdn.com/en/codes.json
curl 'https://flagcdn.com/en/codes.json'const res = await fetch("https://flagcdn.com/en/codes.json");
if (!res.ok) throw new Error(`Request failed: ${res.status}`);
const data = await res.json();
console.log(data);import requests
res = requests.get("https://flagcdn.com/en/codes.json", timeout=20)
res.raise_for_status()
print(res.json()){
"ad": "Andorra",
"ae": "United Arab Emirates",
"af": "Afghanistan",
"ag": "Antigua and Barbuda",
"ai": "Anguilla",
"al": "Albania",
"am": "Armenia",
"ao": "Angola",
"aq": "Antarctica",
"ar": "Argentina",
"as": "American Samoa",
"at": "Austria",
"au": "Australia",
"aw": "Aruba",
"ax": "Åland Islands",
"az": "Azerbaijan",
"ba": "Bosnia and Herzegovina",
"bb": "Barbados",
"bd": "Bangladesh",
"be": "Belgium",
"bf": "Burkina Faso",
"bg": "Bulgaria",
"bh": "Bahrain",
"bi": "Burundi",
"bj": "Benin",
"bl": "Saint Barthélemy",
"bm": "Bermuda",
"bn": "Brunei",
"bo": "Bolivia",
"bq": "Caribbean Netherlands",
"br": "Brazil",
"bs": "Bahamas",
"bt": "Bhutan",
"bv": "Bouvet Island",
"bw": "Botswana",
"by": "Belarus",
"bz": "Belize",
"ca": "Canada",
"cc": "Cocos (Keeling) Islands",
"cd": "DR Congo",
"cf": "Central African Republic",
"cg": "Republic of the Congo",
"ch": "Switzerland",
"ci": "Côte d'Ivoire (Ivory Coast)",
"ck": "Cook Islands",
"cl": "Chile",
"cm": "Cameroon",
"cn": "China",
"co": "Colombia",
"cr": "Costa Rica",
"cu": "Cuba",
"cv": "Cape Verde",
"cw": "Curaçao",
"cx": "Christmas Island",
"cy": "Cyprus",
"cz": "Czechia",
"de": "Germany",
"dj": "Djibouti",
"dk": "Denmark",
"dm": "Dominica",
"do": "Dominican Republic",
"dz": "Algeria",
"ec": "Ecuador",
"ee": "Estonia",
"eg": "Egypt",
"eh": "Western Sahara",
"er": "Eritrea",
"es": "Spain",
"et": "Ethiopia",
"eu": "European Union",
"fi": "Finland",
"fj": "Fiji",
"fk": "Falkland IslandsParameters
| Parameter | Type | Required | Description |
|---|---|---|---|
lang | path | Required | Two-letter language code for the country names: `en`, `de`, `fr`, `es`, `ja`, `pt` and about thirty more. en |
codes.json | path | Required | The metadata file itself. `/{lang}/codes.json` is the whole map in one request. codes.json |
(flag PNG) | path | Optional | `/w320/{code}.png` renders a flag at 320px wide. Widths from w20 to w2560 are available. w320/gb.png |
(flag SVG) | path | Optional | `/{code}.svg` returns the vector original, which scales without a size decision. gb.svg |
(fixed height) | path | Optional | `/h60/{code}.png` sizes by height instead, which keeps a row of mixed-ratio flags aligned. h60/np.png |
Response fields
(object keys)string- Lowercase ISO 3166-1 alpha-2 country codes — `ad`, `ae`, `af` and so on. Note the codes are lowercase, unlike most ISO usage.
(object values)string- Country name in the requested language, using common short forms such as "DR Congo" rather than the full official title.
(coverage)n/a- Includes territories and dependencies alongside sovereign states — Antarctica, Åland, Bouvet Island and the like all appear.
What you can build with the FlagCDN API
- Build a country picker with flags and localised names from one source
- Localise country names without shipping your own translation table
- Show a flag next to a currency, phone code or shipping destination
- Render flags at a consistent height despite differing aspect ratios
- Validate a user-supplied country code against the current ISO list
Common errors and how to fix them
404 on a flag image
The code is uppercase, or it is a three-letter code.
Fix: FlagCDN uses lowercase alpha-2 codes in URLs. `GB.png` fails where `gb.png` works, and `gbr.png` is not supported at all.
Flags of different widths look ragged in a list
Aspect ratios genuinely differ between countries.
Fix: Size by height with `/h60/{code}.png` rather than by width, and let the widths vary. Nepal's non-rectangular flag will still stand out.
A territory is missing or named unexpectedly
Coverage includes dependencies and disputed entities, with editorial choices about naming.
Fix: Fetch `codes.json` and treat it as the authoritative list for what this service offers, rather than assuming it matches another ISO listing exactly.
Images look blurry on a high-density display
A raster width was chosen for a CSS pixel size, not a device pixel size.
Fix: Request roughly double the CSS width, or use the SVG, which has no resolution to get wrong.
FlagCDN API — frequently asked questions
Is FlagCDN free for commercial use?
Yes. Both the images and the metadata are free for personal and commercial projects, and hotlinking directly from the CDN is explicitly permitted rather than merely tolerated.
How do I get a flag at a specific size?
Put the size in the path: `/w320/gb.png` for 320 pixels wide, `/h60/gb.png` for 60 pixels tall. For anything responsive, `/gb.svg` avoids the decision entirely.
Does it provide country names in other languages?
Yes. `/{lang}/codes.json` returns the whole code-to-name map in more than thirty languages, so swapping `en` for `ja` localises a country picker in a single request.
Why are the country codes lowercase?
Because they are used directly in URLs, and lowercase paths avoid case-sensitivity problems across servers and caches. Uppercase your codes for display if the convention matters to you, but send lowercase.
Tools that pair with this API
Flag Emoji Generator
Turn ISO 3166-1 country codes into flag emoji, decode flags back into codes, or browse and copy every country flag with its Unicode code points.
JSON to CSV Converter
Convert a JSON array of objects to CSV online. Automatic column headers from the union of all keys, delimiter choice and proper quoting — all in-browser.
JSON Formatter
Format, beautify and minify JSON online with 2-space, 4-space or tab indentation. Sort keys alphabetically and catch syntax errors instantly — free and private.
FlagCDN is an independent third-party service and is not affiliated with ByteTools or ByteVancer. Details on this page were verified on 2026-08-21; always check the official documentation before relying on this API in production, as terms and limits can change.