Flag API

Country flags as SVG, PNG, WebP or JPEG, in any size. URLs follow the flagcdn.com scheme, so pointing existing code here is a hostname swap.

Quick start

Build a URL from a size, a two-letter country code and a format. No key or sign-up is needed.

{origin}/w320/gb.png

In a page, add a second size for high-density screens:

<img src="{origin}/w160/gb.png"
     srcset="{origin}/w320/gb.png 2x"
     width="160" alt="United Kingdom">

From a script:

curl -o gb.png {origin}/w320/gb.png
curl {origin}/en/codes.json

URL builder


      

    

    

      

      

    

  


  
Endpoints

  

    

      
GETReturns

      
/{code}.svgThe vector flag, e.g. /gb.svg.

      
/w{width}/{code}.{format}Fixed width; height follows the flag's own aspect ratio. /w320/gb.png

      
/h{height}/{code}.{format}Fixed height; width follows the aspect ratio. /h120/gb.webp

      
/{width}x{height}/{code}.{format}Exact box, flag fitted inside and padded. /64x48/gb.png

      
/{lang}/codes.jsonEvery code with its name in that language. /en/codes.json

      
/sizes.jsonPreset sizes, formats and the size limits of this instance.

      
/healthzLiveness check with flag count and cache usage.

      
/docsThis page.

    

  

  
{format} is png, webp or jpg. HEAD works on every endpoint. Paths are case-insensitive, so /W320/GB.PNG is fine.


  
Sizes

  

    
Fixed width (w320) and fixed height (h120) keep each flag's real proportions, so the other dimension varies by country: /w320/gb.png is 320 × 160, /w320/ch.png is 320 × 320. Use fixed height for a row of flags that should line up.

    
Fixed box (64x48) always returns exactly that many pixels. The flag is scaled to fit inside and centred; the leftover space is transparent (white for JPEG). Use it when every image must be the same size, such as icons in a list.

    

    
Presets, matching flagcdn.com:

    
Width

    
Height

    
Fixed box (4:3)

  


  
Formats

  

    

      
ExtensionContent typeNotes

      
.svgimage/svg+xmlVector original, sharp at any size. No size segment in the URL. Sent gzipped when the client accepts it.

      
.pngimage/pngLossless, with transparency. The safe default.

      
.webpimage/webpLossless, with transparency, usually smaller than PNG.

      
.jpg / .jpegimage/jpegNo transparency: padding and non-rectangular flags (Nepal) sit on white.

    

  


  
Country codes

  

    
Codes are lower-case ISO 3166-1 alpha-2 (gb, us, de), plus eu, xk (Kosovo) and the UK nations gb-eng, gb-sct, gb-wls and gb-nir. The full list is browsable below.

    
/{lang}/codes.json returns a single object mapping each code to its name. {lang} is a language tag such as en, de, fr, ja or pt-br; /codes.json is the English list.

    
{ "ad": "Andorra", "ae": "United Arab Emirates", … }

  


  
Responses and errors

  

    

      
StatusWhen

      
200The image or JSON you asked for.

      
304Your cached copy is still current (If-None-Match matched the ETag).

      
400The size is malformed or over the limit, or the format is not supported.

      
404There is no flag for that code, no names for that language, or no such path.

      
405Any method other than GET, HEAD or OPTIONS.

    

    
Errors are JSON with a single error message:

    
{ "error": "No flag for code \"zz\". See /en/codes.json for the full list." }

  


  
Caching and CORS

  

    
Every image and codes list carries an ETag and a Cache-Control header, so browsers and proxies can keep copies and revalidate cheaply. URLs are stable: a flag that changes keeps its URL and gets a new ETag.

    
All responses send Access-Control-Allow-Origin: *, so flags can be fetched from scripts or drawn to a canvas from any internal site.

  


  
All flags