API Documentation

Everything you need to integrate Flagcore into your application.

Authentication

All API requests require an API key. Include it in the X-API-Key header.

bash

curl -H "X-API-Key: fc_your-api-key" \
  https://flagcore.de/api/flags/de.svg

Endpoints

GET/api/flags/{code}.{format}

Retrieve a country flag in SVG or PNG format.

Parameter	Type	Description
code*	string	ISO 3166-1 alpha-2 country code (e.g., de, us, gb)
format*	string	svg or png
w	number	Width for PNG: 20, 40, 80, 160, 320, 640, 1280, 2560

bash

curl -H "X-API-Key: YOUR_KEY" \
  https://flagcore.de/api/flags/de.svg

curl -H "X-API-Key: YOUR_KEY" \
  "https://flagcore.de/api/flags/de.png?w=640"

GET/api/countries

Retrieve comprehensive country information.

bash

curl https://flagcore.de/api/countries

Response:

json

[
  {
    "code": "de",
    "name": "Germany",
    "officialName": "Federal Republic of Germany",
    "capital": "Berlin",
    "continent": "Europe",
    "population": 83240525,
    "area": 357114,
    "currency": "Euro (EUR)",
    "callingCode": "+49",
    "tld": ".de"
  }
]

GET/api/countries/{code}

Retrieve detailed information for a specific country.

Parameter	Type	Description
code*	string	ISO 3166-1 alpha-2 country code

bash

curl https://flagcore.de/api/countries/de

POST/api/keys

Generate a new API key.

Parameter	Type	Description
email*	string	Your email address

bash

curl -X POST https://flagcore.de/api/keys \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

Response:

json

{
  "key": "fc_a1b2c3d4-e5f6-...",
  "alreadyExists": false,
  "rateLimit": 1000
}

GET/api/keys/{key}/usage

Check usage statistics for an API key.

Parameter	Type	Description
key*	string	Your API key

bash

curl https://flagcore.de/api/keys/fc_your-key/usage

Response:

json

{
  "total": 4521,
  "today": 127,
  "limit": 1000
}

Parameters

Header	Description	Required
X-API-Key	Your API key	Required

Width in pixels for PNG format. Available: 20, 40, 80, 160, 320, 640, 1280, 2560.

Rate Limiting

Each API key is limited to 1,000 requests per day. The current usage is returned in response headers.

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 873
X-RateLimit-Reset: 2026-03-06T00:00:00Z

Examples

JavaScript / TypeScript

javascript

const response = await fetch(
  "https://flagcore.de/api/flags/de.svg",
  { headers: { "X-API-Key": "fc_your-key" } }
);
const svgText = await response.text();

Python

python

import requests

response = requests.get(
    "https://flagcore.de/api/flags/de.svg",
    headers={"X-API-Key": "fc_your-key"}
)
svg_content = response.text

HTML

html

<!-- Note: For direct HTML embedding, use the CDN URL -->
<img src="https://flagcore.de/api/flags/de.png?w=160"
     alt="Germany" />