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
  }
}

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 },
  "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.

Next ​