DEV Community

Jeremy Persing
Jeremy Persing

Posted on • Updated on

Add Country Flags to Your App With This API - alternative

I am going to be shutting down this service as of 3/12/23. If you would like to run your own instance of this, go to the country flags repository, download the code and run it on your own VPS.


I was recently working on a project that required me to implement country flags into the application. At the time, was a popular API that people were using, so I decided that I should rely on it for my project. While integrating the endpoints for into my application, I noticed that they only allowed user's to retrieve a country's flag by a two letter code. For example, if I wanted to get the flag of the United States, the endpoint would be This was a problem because my data didn't identify countries by their two letter codes. Another problem I ran into is that the server of went down half way through the project. So to fix these problems, I created my own API that allows users to get a country's flag by the country's name, its two letter code (ISO Alpha 2 code), its three letter code (ISO Alpha 3 code), and its UN Code. The codes for each country can be found at Here are a few example endpoints

Running Your Own Instance

If you wish to run your own instance of this API, you can download the source code here. If you would prefer to just pull a docker image of the API, you can get that here

Getting a Flag from User Input

I'll be using React for this demo. Keep in mind this is a basic demo, but this will probably be similar to what you will want
to use in your app.


import React, { useState } from 'react'
Enter fullscreen mode Exit fullscreen mode

States and Functions

const [flagURL, setFlagURL] = useState('')
const [identifier, setIdentifier] = useState('')

const handleButtonClick = () => {
  // can use here too
  const url = ''
  setFlagURL(url + identifier)
Enter fullscreen mode Exit fullscreen mode


<div style={{ marginBottom: '20px' }}>
      onChange={(e) => setIdentifier(}
      placeholder="Enter a country name, UN Code, ISO Alpha-2, or ISO Alpha-3 Code"
    <button onClick={handleButtonClick}>Get Flag</button>
<img src={flagURL} alt="flag" />
Enter fullscreen mode Exit fullscreen mode

Embedding an Image

Go to the flag that you want to embed and click the button labeled "Embed SVG" or "Embed PNG". A modal will then appear like the one shown in the image below. Go ahead and click copy and then paste the img element into your source code.

Embed an img element

Top comments (4)

jonrandy profile image
Jon Randy πŸŽ–οΈ

You can just use one line of JS - without any API at all:

const getFlagEmoji = countryCode=>String.fromCodePoint(...[...countryCode.toUpperCase()].map(x=>0x1f1a5+x.charCodeAt(0)))

getFlagEmoji('gb') // πŸ‡¬πŸ‡§
getFlagEmoji('za') // πŸ‡ΏπŸ‡¦
getFlagEmoji('th') // πŸ‡ΉπŸ‡­
Enter fullscreen mode Exit fullscreen mode
jeremypersing profile image
Jeremy Persing

I looked into this solution but Windows 10 doesn't seem to support flag emojis. This is the example on Windows
Windows Version
compared to other operating systems.
Everything else
Also, one of the drawbacks that I encountered working with other flag APIs is that you can only access a flag by its 2 letter country code. This became a pain to work with because the API that was supplying me with country data didn't include a 2 letter country code. That's why at countryflagsapi you can get a country's flag by the country's name, two letter code, three letter code, or UN Code. But if the application has access to the two letter country code and doesn't mind not having flags being shown on Windows 10, I think your solution is the way to go.

jonrandy profile image
Comment marked as low quality/non-constructive by the community. View Code of Conduct
Jon Randy πŸŽ–οΈ

Man, Windows is a total joke... why do people still use it?

miko2x profile image

Thank you so much!!

Some comments may only be visible to logged-in visitors. Sign in to view all comments.