Loading…
Everything you need to integrate Flagswing flags into your app.
Flagswing provides country flags in SVG, PNG, and EPS formats via a global CDN. For simple embedding, no account or API key is required. The CDN is free forever.
If you need flag metadata (name, colors, formats) or want higher request limits, generate a free API key from your developer dashboard.
<!-- No signup required --> <img src="https://pub-d7a1861fd19b400ab91b028d5ffa0d27.r2.dev/flags/svg/uz.svg" alt="Uzbekistan flag" width="32" height="24" loading="lazy" />
curl -H "X-API-Key: YOUR_KEY" \ https://api.flagswing.com/v1/flags/uz
All flags are served from a globally distributed edge network. Files are cached at the CDN layer — typical response times are under 50 ms worldwide.
https://pub-d7a1861fd19b400ab91b028d5ffa0d27.r2.dev/flags/{format}/{code}.{format}
Examples:
https://pub-d7a1861fd19b400ab91b028d5ffa0d27.r2.dev/flags/svg/uz.svg
https://pub-d7a1861fd19b400ab91b028d5ffa0d27.r2.dev/flags/png/us.png
https://pub-d7a1861fd19b400ab91b028d5ffa0d27.r2.dev/flags/eps/gb.eps| Format | Extension | Best for |
|---|---|---|
| SVG | .svg | Web, any size, Retina displays |
| PNG | .png | Email templates, legacy browsers |
| EPS | .eps | Print, Illustrator, Photoshop |
const CDN = 'https://pub-d7a1861fd19b400ab91b028d5ffa0d27.r2.dev';
function FlagImage({ code, size = 32 }: { code: string; size?: number }) {
return (
<img
src={`${CDN}/flags/svg/${code}.svg`}
alt={`${code.toUpperCase()} flag`}
width={size}
height={Math.round(size * 0.75)}
loading="lazy"
/>
);
}
// Usage
<FlagImage code="uz" size={48} /><template>
<img
:src="`https://pub-d7a1861fd19b400ab91b028d5ffa0d27.r2.dev/flags/svg/${code}.svg`"
:alt="`${code.toUpperCase()} flag`"
width="32"
height="24"
loading="lazy"
/>
</template>
<script setup lang="ts">
defineProps<{ code: string }>();
</script>The REST API returns JSON. All endpoints require an X-API-Key header except where noted.
# Pass your API key as a header curl -H "X-API-Key: fs_live_xxxxxxxxxxxx" \ https://api.flagswing.com/v1/flags/uz
Returns metadata for a single flag identified by its ISO 3166-1 alpha-2 code.
curl -H "X-API-Key: YOUR_KEY" \ https://api.flagswing.com/v1/flags/uz
{
"code": "uz",
"name": "Uzbekistan",
"slug": "uzbekistan",
"formats": {
"svg": "https://pub-d7a1861fd19b400ab91b028d5ffa0d27.r2.dev/flags/svg/uz.svg",
"png": "https://pub-d7a1861fd19b400ab91b028d5ffa0d27.r2.dev/flags/png/uz.png",
"eps": "https://pub-d7a1861fd19b400ab91b028d5ffa0d27.r2.dev/flags/eps/uz.eps"
},
"colors": [
{ "name": "Teal Blue", "hex": "#1EBFAE" },
{ "name": "White", "hex": "#FFFFFF" },
{ "name": "Green", "hex": "#1EB53A" }
],
"license": "free",
"premium_shapes": ["sphere", "heart", "star", "wave"]
}Same as above but the formats object is filtered to the requested format. Valid values: svg, png, eps.
List flags, optionally filtered by region and paginated.
# List up to 20 European flags curl -H "X-API-Key: YOUR_KEY" \ "https://api.flagswing.com/v1/flags?region=europe&limit=20"
Full-text search over flag names and ISO codes.
curl -H "X-API-Key: YOUR_KEY" \ "https://api.flagswing.com/v1/flags/search?q=uzb"
Rate limits are applied per API key. The CDN has no rate limit. Limits reset at midnight UTC each day.
| Plan | Requests / day | Price |
|---|---|---|
| Free | 100 | $0 |
| Basic | 1,000 | $9/mo |
| Pro | 10,000 | $29/mo |
| Enterprise | Unlimited | Contact |
When you exceed the limit, the API returns 429 Too Many Requests. Upgrade your plan for higher limits.
const CDN = 'https://pub-d7a1861fd19b400ab91b028d5ffa0d27.r2.dev';
interface FlagItem {
code: string;
name: string;
}
async function fetchFlags(region: string): Promise<FlagItem[]> {
const res = await fetch(
`https://api.flagswing.com/v1/flags?region=${region}&limit=50`,
{ headers: { 'X-API-Key': process.env.FLAGSWING_API_KEY ?? '' } }
);
if (!res.ok) throw new Error('Failed to fetch flags');
const data = (await res.json()) as { flags: FlagItem[] };
return data.flags;
}
export default async function FlagGrid() {
const flags = await fetchFlags('europe');
return (
<ul className="grid grid-cols-8 gap-2">
{flags.map((f) => (
<li key={f.code} title={f.name}>
<img
src={`${CDN}/flags/svg/${f.code}.svg`}
alt={`${f.name} flag`}
width={48}
height={36}
loading="lazy"
/>
</li>
))}
</ul>
);
}// app/country/[code]/page.tsx
const CDN = 'https://pub-d7a1861fd19b400ab91b028d5ffa0d27.r2.dev';
interface PageProps {
params: Promise<{ code: string }>;
}
export default async function CountryPage({ params }: PageProps) {
const { code } = await params;
return (
<main>
<img
src={`${CDN}/flags/svg/${code}.svg`}
alt={`${code.toUpperCase()} flag`}
width={64}
height={48}
/>
</main>
);
}async function searchFlags(q: string) {
const res = await fetch(
`https://api.flagswing.com/v1/flags/search?q=${encodeURIComponent(q)}`,
{ headers: { 'X-API-Key': process.env.FLAGSWING_API_KEY ?? '' } }
);
if (!res.ok) throw new Error(`Search failed: ${res.status}`);
return res.json() as Promise<{ flags: Array<{ code: string; name: string }> }>;
}
const results = await searchFlags('uzb');
console.log(results.flags); // [{ code: "uz", name: "Uzbekistan" }, ...]Ready to build?
Generate a free API key — takes 10 seconds.