Available Routes / cURL

All routes are GET-only. Base URL: https://api.openflags.net

Health check

GET https://api.openflags.net/api/v1/health

curl https://api.openflags.net/api/v1/health

List flags (paginated)

Returns a page of flags. page defaults to 1, page_size defaults to 20 (max 100).

GET https://api.openflags.net/api/v1/flags?page=1&page_size=20

curl "https://api.openflags.net/api/v1/flags?page=1&page_size=20"

Get a single flag by ISO 3166 code

GET https://api.openflags.net/api/v1/flags/:iso_code

curl https://api.openflags.net/api/v1/flags/US-CA

Search flags

Matches against ISO code, region name, country name, and known aliases (including translated names).

GET https://api.openflags.net/api/v1/search?q=:term

curl "https://api.openflags.net/api/v1/search?q=california"

List flags for a country

GET https://api.openflags.net/api/v1/countries/:iso/flags

curl https://api.openflags.net/api/v1/countries/US/flags

Random flag (JSON)

GET https://api.openflags.net/api/v1/flags/random

curl https://api.openflags.net/api/v1/flags/random

Random flag image (direct SVG)

Serves the SVG file directly — safe to drop straight into an <img src>.

GET https://api.openflags.net/api/v1/flags/random/image

<img src="https://api.openflags.net/api/v1/flags/random/image" alt="Random flag" />

Static flag / coat-of-arms files

Every flag's flag.svg / coat.svg field (see the flag object shape) is a path served directly under /flags/:

GET https://api.openflags.net/flags/:country_iso/flag.svg
GET https://api.openflags.net/flags/:country_iso/:region_iso/flag.svg

# Country-level flag
curl https://api.openflags.net/flags/US/flag.svg

# Region-level flag
curl https://api.openflags.net/flags/US/US-CA/flag.svg

PNG conversion

Converts a flag SVG to PNG on the fly (and caches the result). size is in pixels, defaults to 128, max 512.

GET https://api.openflags.net/flags-png/:country/*path?size=128

curl "https://api.openflags.net/flags-png/US/US-CA/flag.svg?size=256" --output california.png