Open Flags Docs

Appearance

GET ​

Base URL: https://api.openflags.net. All routes are GET-only — see REST API Docs for why.

Health check ​

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

List flags (paginated) ​

page defaults to 1, page_size defaults to 20 (max 100). Results are ordered by iso_code; dir=desc reverses that order before paginating, so page 1 holds the last codes and meta is the same in both directions.

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

dir must be lowercase asc (the default) or desc; anything else returns 400 {"error": "dir must be one of: asc, desc"}. It is only accepted here: search and the per-country list return their whole result set, so sort those yourself.

Filtering by artwork ​

62% of the catalogue has no flag artwork yet (coat-of-arms-only and stub entries). Every flag object reports a boolean has_image, and has_image=true narrows a list to the entries that have one:

cli
GET https://api.openflags.net/api/v1/flags?has_image=true&page_size=50
GET https://api.openflags.net/api/v1/search?q=mexico&has_image=true
GET https://api.openflags.net/api/v1/countries/US/flags?has_image=true
GET https://api.openflags.net/api/v1/flags/random?has_image=true

Filtering happens before pagination, so meta describes the filtered set and every page is full — don't filter client-side for this. has_image=false asks for the opposite set. The value must be the lowercase string true or false; anything else returns 400 {"error": "has_image must be one of: true, false"}. Leaving the parameter off returns the whole catalogue.

Get a single flag by ISO 3166 code ​

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

Returns 404 {"error": "Flag not found"} if the code doesn't exist.

Search flags ​

Returns every match, unpaginated. A missing q returns 400 {"error": "Missing 'q' parameter"}.

cli
GET https://api.openflags.net/api/v1/search?q=:term
GET https://api.openflags.net/api/v1/search?q=:term&has_image=true

List flags for a country ​

Ordered by iso_code. An unknown country is an empty list, not a 404.

cli
GET https://api.openflags.net/api/v1/countries/:iso/flags
GET https://api.openflags.net/api/v1/countries/:iso/flags?has_image=true

Random flag (JSON) ​

has_image=true keeps retrying out of your code — it only ever returns a flag that has artwork.

cli
GET https://api.openflags.net/api/v1/flags/random
GET https://api.openflags.net/api/v1/flags/random?has_image=true

Random flag image (direct SVG) ​

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

Static flag / coat-of-arms SVG ​

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

PNG conversion ​

size in pixels, defaults to 128, max 512.

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

For runnable curl examples of each of these, see Available Routes / cURL.