Public read API

Flag lookup

Clients can fetch the flag associated with a Twitch user ID. No authentication is required.

Endpoint

GET /api/flags/{twitchUserId}

Try it with curl:

curl https://twitchflags.live/api/flags/18063875

twitchUserId: Twitch numeric user ID. Digits only (for example 18063875).

Success response

200 OK with JSON:

{
  "twitchUserId": "18063875",
  "flag": "US"
}

twitchUserId: Echo of the validated path parameter.
flag: ISO 3166-1 alpha-2 country or territory code (uppercase).

Error responses

All errors return JSON of the form { "error": "…" }.

Status	error	When
`400`	`invalid_twitch_user_id`	Path ID is missing or not digits-only.
`404`	`flag_not_set`	User has not saved a flag.
`429`	`rate_limited`	Request was rate limited.
`503`	`service_unavailable`	Flag storage is temporarily unavailable.

Headers & CORS

Access-Control-Allow-Origin: * on GET responses
Successful reads and 404 flag_not_set: Cache-Control: public, max-age=604800, s-maxage=604800, stale-while-revalidate=604800
Successful saves and removals invalidate the affected Twitch user ID's Vercel CDN cache tag.
Other errors: Cache-Control: no-store
OPTIONS preflight is cacheable for 24h (Access-Control-Max-Age: 86400)

Client library & examples

TwitchFlagsJS (opens in new tab) is a small browser-global helper with no required build step. It calls this API and can return an ISO code, Unicode flag, emoji shortcode, browser-localized name, or Twemoji image.

Pinned production script

Load the pinned hosted script and request a detached image element. The client loads Twemoji only when an image method needs it.

<div id="flag-container"></div>
<script
  src="https://cdn.jsdelivr.net/gh/DesertIce/TwitchFlagsJS@9155c6394ae63de39bac349c9fdd981711188ba1/twitchflags.js"
  integrity="sha384-FOPARJMnXkPPvb8oawPqz71sOGfyqzDNB1nw1XeJ41e2oShBd3sTix2mtOBFw7EB"
  crossorigin="anonymous"
></script>
<script>
  async function showFlag() {
    const image = await TwitchFlagsJS.GetFlagImageElement("18063875");

    if (image) {
      document.querySelector("#flag-container").append(image);
    }
  }

  showFlag();
</script>

Follow future updates

For easier updates, load the GitHub Pages build instead. This mutable URL follows future TwitchFlagsJS updates without changing your page, but it does not provide integrity pinning. Review upstream changes before relying on automatic updates in a production page.

<script src="https://desertice.github.io/TwitchFlagsJS/twitchflags.js"></script>

Pass a digits-only Twitch numeric user ID, not a username.
Lookup methods return promises and resolve with an empty result instead of rejecting. Failures are also written to the browser console.
Successful flags are cached for the page lifetime; a missing flag is cached for one hour. See the repository for the full method, caching, and Twemoji configuration reference.

Chat widget references

These Streamer.bot browser-source widgets show how to place the returned Twemoji element beside a Twitch username. Use them as integration references rather than additional API dependencies.