Flags API - Country & Organization Flags in PNG, WEBP & SVG
Every product that displays a country (a checkout, a language switcher, a signup form) eventually accumulates a folder of flag images that nobody owns: mismatched crops, missing territories, artwork that goes stale after a redesign. The Flags API replaces that folder with a single HTTP request that returns the flag itself, ready to render.
Request any country flag or international organization flag in PNG, WEBP, or SVG, in flat or round style, at five icon sizes. It's built for developers shipping country selectors, fintech dashboards, localization flows, and analytics interfaces. Start with 10,000 free credits - no credit card required.
Features
Country Flags by ISO Code
Request any country flag by passing its ISO 3166-1 alpha-2 code in the name parameter, with type=country. The API returns the flag as binary image data with the correct Content-Type header, so it drops straight into an <img> tag, a mobile view, or a build pipeline. Use it to render flags from the same country codes you already store for users, orders, or sessions.
International Organization Flags
Set type=organization to retrieve flags for international bodies including the European Union, United Nations, NATO, ASEAN, the African Union, the Arab League, the Gulf Cooperation Council, and the Organization of American States. Use it as an organization flags API for diplomatic, trade, and compliance interfaces where membership matters as much as nationality - coverage that free flag CDNs limit to the EU and UN at most.
Three Image Formats
Choose the output with the format parameter: png (the default), webp, or svg. PNG and WEBP are raster formats suited to standard web and mobile rendering; SVG is resolution-independent vector output for high-density displays and interfaces that scale. The response Content-Type reflects the requested format: image/png, image/webp, or image/svg+xml.
Flat and Round Shapes
The required shape parameter accepts flat for standard rectangular flags and round for circular icons. Round flags fit avatar-style country indicators, profile interfaces, and compact mobile components; flat flags suit tables, dashboards, and data-heavy layouts. Both shapes are available for every supported country and organization.
Five Icon Sizes
The size parameter accepts 16px, 24px, 32px, 48px, and 64px, with 64px as the default. Sizing applies to PNG and WEBP output; SVG scales to any dimension without a size parameter. Pick the exact size your UI renders and skip client-side resizing and image-optimization passes.
Supported Flags Endpoint
Call /flags/supported with no parameters to get the full machine-readable inventory: a supported_countries array with each country's name, iso2, and iso3 codes, and a supported_organizations array of organization identifiers. Use it to validate input before requesting a flag, populate dropdowns, or map ISO alpha-3 codes from external datasets to the alpha-2 codes the flag endpoint expects.
Built for These Use Cases
Country selectors and onboarding forms
Build a dropdown by pulling the supported-flags list once, rendering each entry's round icon beside its name, and caching the images your form actually shows. Pair it with the Countries API to attach capitals, calling codes, and currencies to the same ISO codes: one credit pool, one key, matching identifiers.Geo-personalized dashboards
Detect a visitor's country with the IP Geolocation API, then render their flag in the header, the account menu, or a localized banner. Because both APIs speak ISO 3166-1 alpha-2, the country code from one request is the flag request of the next - no mapping table in between.Fintech and multi-currency interfaces
Currency pickers, remittance flows, and FX dashboards read faster when each currency carries its country's flag. A country flags API that serves consistent flat icons at a fixed size keeps every row of a rates table aligned, and WEBP output trims payload where bandwidth budgets are tight.
Analytics and admin panels
Traffic-by-country tables, moderation queues, and CRM views all benefit from a flag column. Fetch flags at the exact pixel size the table renders as a country flag API for internal tooling: no sprite sheets, no design-asset requests, no manual updates when artwork changes.
API Endpoints
Supported Flags API
Retrieve a complete list of all supported country and organization flags with their name, ISO alpha-2, and ISO alpha-3 codes. No parameters are required.
Flags API
Retrieve a flag image for a specified country or organization. Pass the ISO country code, shape, type, and optionally format and size to get a flag in your preferred style and dimensions.
All Endpoints
| Endpoint | Description | Credits | Reference | Playground |
|---|---|---|---|---|
| Flags | Get a country or organization flag image in PNG, WEBP, or SVG. | 1 | Reference | Playground |
| Flags Supported | List all countries and organizations with a supported flag image. | 1 | Reference | Playground |
How-to Guides
List of Flags Supported
Before your UI requests a single image, it needs to know which codes will resolve: an unsupported code returns a 404, not a placeholder. Pull the supported list once to validate stored country codes, populate a selector, or translate ISO alpha-3 codes from an external dataset into the alpha-2 codes the flag endpoint expects.
# Response { "supported_countries": [ { "name": "Luxembourg", "iso2": "LU", "iso3": "LUX" }, { "name": "Suriname", "iso2": "SR", "iso3": "SUR" }, { "name": "Tunisia", "iso2": "TN", "iso3": "TUN" }, { "name": "Colombia", "iso2": "CO", "iso3": "COL" }, { "name": "Pakistan", "iso2": "PK", "iso3": "PAK" } ], "supported_organizations": [ "Commonwealth_of_Independent_States", "Gulf_Cooperation_Council", "Arab_League", "Organization_of_American_States", "African_Union", "European_Union", "United_Nations", "NATO", "Association_of_Southeast_Asian_Nations", "Commonwealth_of_Nations" ] }curl -X 'GET' 'https://api.apifreaks.com/v1.0/flags/supported?apiKey=API-KEY'
Get Flag Image by Country Code
When a signup form, invoice, or dashboard needs a specific country's flag, one GET request returns the image itself: binary data with the matching content type, not a JSON wrapper around a URL. Save it to disk at build time or stream it straight through to the client.
# Response: binary PNG image data # Save the output to a file using --output flag # Content-Type: image/pngcurl -X 'GET' 'https://api.apifreaks.com/v1.0/flags?name=US&type=country&shape=flat&size=32px&format=png&apiKey=API-KEY' --output us-flag.png
Render a Round SVG Flag for a Profile UI
Avatar rows and compact mobile headers need a circular icon that stays sharp on every display density. Request shape=round with format=svg and the flag scales to any container without a size parameter or a retina variant.
# Response: binary SVG image data # Content-Type: image/svg+xml # SVG output is resolution-independent - the size parameter is not requiredcurl -X 'GET' 'https://api.apifreaks.com/v1.0/flags?name=JP&type=country&shape=round&format=svg&apiKey=API-KEY' --output jp-flag-round.svg
Get an International Organization Flag
Trade dashboards and compliance tooling often need to show a bloc (the EU, NATO, ASEAN) next to its member states. Set type=organization and pass the organization identifier from the supported-flags list as the name.
# Response: binary PNG image data # Organization identifiers come from the supported_organizations # array of the /flags/supported endpointcurl -X 'GET' 'https://api.apifreaks.com/v1.0/flags?name=European_Union&type=organization&shape=flat&size=48px&format=png&apiKey=API-KEY' --output eu-flag.png
Frequently Asked Questions
type parameter to organization in your request. Use the Supported Flags endpoint first to get a complete list of all supported organizations and their identifiers before making individual flag requests.flag_emoji character. If you need an image file at a controlled size and shape, use the Flags API; if you need country data with an emoji-level flag, use the Countries API. Both accept the same ISO 3166-1 alpha-2 codes, so they combine cleanly in one workflow.Pricing
To use the Flags API, you will need API credits. We only charge for successful queries, defined by a 2xx status code. If your request results in a 4xx or 5xx status code, no credits will be charged, and any deducted credits will be returned.
For each successful request, 1 credit will be charged.
Utilize the Credits Usage API to efficiently monitor your recent consumption of both one-off and subscription credits. This API provides a streamlined way to track and manage your credit usage, ensuring you stay informed about your remaining balance and can optimize your resource allocation effectively.