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"

# last codes first
curl "https://api.openflags.net/api/v1/flags?dir=desc&page_size=20"

Only the flags that have artwork

62% of the catalogue has no flag artwork yet. Every flag object reports a boolean has_image; has_image=true filters a list down to the entries that have one, before pagination, so each page comes back full.

GET https://api.openflags.net/api/v1/flags?has_image=true&page_size=50

# 50 flags per page, all of them renderable
curl "https://api.openflags.net/api/v1/flags?has_image=true&page_size=50"

# the opposite set: entries with a coat of arms only, or nothing yet
curl "https://api.openflags.net/api/v1/flags?has_image=false"

Accepted on /api/v1/flags, /api/v1/search, /api/v1/countries/:iso/flags and /api/v1/flags/random. The value must be lowercase true or false; anything else is a 400.

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"

# only matches that have flag artwork
curl "https://api.openflags.net/api/v1/search?q=mexico&has_image=true"

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

# only the subdivisions that have a flag
curl "https://api.openflags.net/api/v1/countries/US/flags?has_image=true"

Random flag (JSON)

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

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

# never returns an entry with no artwork
curl "https://api.openflags.net/api/v1/flags/random?has_image=true"

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