Open Flags Docs

Appearance

API ​

The Open Flags API is a read-only REST/JSON API served over HTTPS. There is no authentication and no write endpoints (no POST/PUT/DELETE) — every route is a GET.

Base URL ​

https://api.openflags.net

Response shape ​

Endpoints under /api/v1 return JSON. List endpoints (/api/v1/flags, /api/v1/search, /api/v1/countries/:iso/flags) wrap results as:

json
{
  "data": [ ... ],
  "meta": {
    "current_page": 1,
    "page_size": 20,
    "total_count": 5757,
    "total_pages": 288,
    "has_next": true,
    "has_prev": false
  }
}

meta describes the result set you asked for. With ?has_image=true it counts only the flags that have artwork, so total_count and total_pages shrink accordingly and every page comes back full.

Single-item endpoints (/api/v1/flags/:iso_code, /api/v1/flags/random) wrap the result as { "data": { ... } }.

Flag object ​

json
{
  "iso_code": "US-CA",
  "country_iso": "US",
  "country_name": "US",
  "country_display_name": "United States",
  "region_name": "us-ca",
  "display_name": "California",
  "aliases": ["California", "加利福尼亚州"],
  "flag": { "svg": "US/US-CA/flag.svg", "source": "flagcdn.com/us-ca.svg" },
  "coat": { "svg": null, "source": null },
  "has_image": true,
  "data_source": "flagcdn"
}

flag.svg and coat.svg are paths relative to the static flag host (see Available Routes / cURL) — join them with /flags/ to get a servable image URL, e.g. https://api.openflags.net/flags/US/US-CA/flag.svg.

has_image is a boolean, present on every flag object, and true when the entry has flag artwork (flag.svg is not null). 2,210 of the 5,757 entries do; the rest carry only a coat of arms, or nothing yet. It refers to flag artwork only, so a coat-of-arms-only entry reads false. Use ?has_image=true on the list endpoints to ask for just those — see Filtering by artwork.

List results are ordered by iso_code; /api/v1/flags takes dir=desc for the reverse order.

Next ​