Flag Feed API Reference

Overview

Flag Feed exposes a minimal, stateless REST API. All flag images are PNG, served with CDN caching and standard HTTP cache headers. No API key or authentication is required.

No authentication required
All responses use standard HTTP status codes
Flag images use ISO 3166-1 alpha-2 lowercase codes
JSON endpoints return Content-Type: application/json
Flag endpoint returns Content-Type: image/png

Quick Start

Fetch the US flag in one command:

shell

curl -o us.png https://flagfeed.com/country/us

Embed directly in HTML — no download needed:

html

<img src="https://flagfeed.com/country/us"
     width="64" height="64"
     alt="US Flag">

Base URL

base url

https://flagfeed.com

ℹ All endpoints are served over HTTPS. HTTP requests redirect to HTTPS.

Endpoints

GET /country/{country-code} image/png

Returns a circular PNG flag image for the given ISO 3166-1 alpha-2 country code.

Path Parameters

Parameter	Type	Required	Description
`country-code`	`string`	Yes	2-letter ISO 3166-1 alpha-2 code, lowercase (e.g. `us`, `gb`, `jp`)

Request

curl

curl -i https://flagfeed.com/country/us

Response — 200 OK

http response

HTTP/2 200 OK
content-type:     image/png
x-country-code:   US
cache-control:    public, max-age=86400
content-length:   <bytes>

<binary PNG data>

GET /api/info application/json

Returns API metadata: name, version, and available endpoints.

Request

curl

curl https://flagfeed.com/api/info

Response — 200 OK

json

{
  "name":        "Flag Feed API",
  "version":     "1.0.0",
  "description": "Simple REST API for world flag images",
  "endpoints":   {
    "GET /country/{country-code}": "Returns PNG flag image for ISO 3166-1 alpha-2 code"
  }
}

GET /status application/json

Liveness check. Returns 200 when the service is up.

Request

curl

curl https://flagfeed.com/status

Response — 200 OK

json

{
  "status":    "ok",
  "timestamp": "2026-03-24T10:30:00.000Z"
}

✓ Use /status in uptime monitors and load-balancer health checks. Response is always under 100 ms.

Response Headers

Header	Endpoints	Description
`content-type`	all	`image/png` for flag images, `application/json` for JSON endpoints
`x-country-code`	`/country/*`	Uppercase ISO country code that was resolved (e.g. `US`)
`cache-control`	`/country/*`	`public, max-age=86400` — CDN-cacheable for 24 hours
`access-control-allow-origin`	all	`*` — CORS open to all origins

Error Codes

All error responses use Content-Type: application/json.

Status	Code	Cause
400	`BAD_REQUEST`	Country code is not a valid 2-letter ISO alpha-2 string
404	`NOT_FOUND`	Flag image for the given code is not in the database
429	`RATE_LIMITED`	Too many requests from this origin; back off and retry

400 Bad Request

json

{
  "error": "Invalid country code. Please use 2-letter ISO country codes (e.g., 'us', 'gb', 'fr')"
}

404 Not Found

json

{
  "error":   "Flag not found for country code: XX",
  "message": "This flag is not available in our database yet."
}

Country Codes

Flag Feed uses ISO 3166-1 alpha-2 codes — always 2 lowercase letters.

⚠ Codes must be lowercase. Uppercase inputs return 400 Bad Request.

Code	Country	Endpoint
`us`	United States	https://flagfeed.com/country/us
`gb`	United Kingdom	https://flagfeed.com/country/gb
`jp`	Japan	https://flagfeed.com/country/jp
`de`	Germany	https://flagfeed.com/country/de
`fr`	France	https://flagfeed.com/country/fr
`br`	Brazil	https://flagfeed.com/country/br
`cn`	China	https://flagfeed.com/country/cn
`in`	India	https://flagfeed.com/country/in
`au`	Australia	https://flagfeed.com/country/au
`ca`	Canada	https://flagfeed.com/country/ca

View all supported country codes →

Rate Limits

Reasonable rate limits are enforced per IP to prevent abuse. When exceeded, the API returns 429 Too Many Requests.

ℹ For high-volume usage, cache flag images on your own CDN or storage. The Cache-Control: public, max-age=86400 header makes this straightforward.

Code Examples

Fetch a flag image and display it — multiple runtimes.

# Save flag to file
curl -o us.png https://flagfeed.com/country/us

# Inspect headers only
curl -I https://flagfeed.com/country/us

# check api status
curl -s https://flagfeed.com/status | jq

# Fetch API info
curl -s https://flagfeed.com/api/info | jq '.version'

// Display flag in the DOM
const img = document.createElement('img');
img.src = `https://flagfeed.com/country/${countryCode}`;
img.alt = `${countryCode.toUpperCase()} flag`;
img.width = 64;
document.body.appendChild(img);

// Or fetch as blob
const res  = await fetch(`https://flagfeed.com/country/jp`);
const blob = await res.blob();
img.src = URL.createObjectURL(blob);

import requests

# Save flag to disk
r = requests.get("https://flagfeed.com/country/de")
r.raise_for_status()
with open("de.png", "wb") as f:
    f.write(r.content)

# check status endpoint
status = requests.get("https://flagfeed.com/status").json()
print(status["status"])  # "ok"

function CountryFlag({ code, size = 64 }) {
  return (
    <img
      src={`https://flagfeed.com/country/${code}`}
      alt={`${code.toUpperCase()} flag`}
      width={size}
      height={size}
      style={{ borderRadius: '50%' }}
    />
  );
}

// Usage
<CountryFlag code="fr" size={32} />

<!-- Static embed -->
<img
  src="https://flagfeed.com/country/gb"
  width="64" height="64"
  alt="GB Flag"
  style="border-radius:50%">

<!-- Inline in a table -->
<td>
  <img src="https://flagfeed.com/country/jp"
       width="24" height="24"
       alt="JP">
  Japan
</td>