Bandeiras e metadados de países

Flag images and country / subdivision metadata

A Flags API tem duas partes: um CDN de imagens de bandeiras (países e subdivisões, em SVG/WebP/PNG) e uma API de metadados em JSON (códigos ISO, nomes traduzidos, código de discagem, moeda, etc.).

The Flags API has two parts: a flag image CDN (countries and subdivisions, in SVG/WebP/PNG) and a JSON metadata API (ISO codes, translated names, calling code, currency, and more).

Base: https://flags.api.insyde.one

Imagens (/img/*) são públicas. A API (/v1/*) exige ?key= — a mesma chave usada nas outras APIs.
Images (/img/*) are public. The API (/v1/*) requires ?key= — the same key used by the other APIs.

1. Imagens de bandeiras / Flag images

As imagens são públicas e seguem um esquema de URL previsível:

Images are public and follow a predictable URL scheme:

/img/c/{iso2}/{shape}.svg
/img/c/{iso2}/{shape}/h{height}.{ext}
/img/s/{iso2}-{sub}/{shape}.svg
/img/s/{iso2}-{sub}/{shape}/h{height}.{ext}

Parte / Part	Valores / Values
`c` / `s`	país (country) / subdivisão (subdivision)
`shape`	`rect` (4×3) · `square` (1×1)
`height`	`20`, `40`, `60`, `80`, `120`, `160`, `240`, `320`
`ext`	`webp` · `png` (ou o SVG vetorial)

Exemplos / Examples:

https://flags.api.insyde.one/img/c/us/rect.svg
https://flags.api.insyde.one/img/c/us/rect/h40.webp
https://flags.api.insyde.one/img/c/br/square/h80.png
https://flags.api.insyde.one/img/s/us-ca/rect/h40.webp
https://flags.api.insyde.one/img/s/br-sp/rect.svg

Em HTML / In HTML:

<!-- vetorial, escala em qualquer tamanho / vector, scales to any size -->
<img src="https://flags.api.insyde.one/img/c/br/rect.svg" alt="Brasil" height="40">

<!-- raster otimizado para um tamanho específico / raster optimized for a size -->
<img src="https://flags.api.insyde.one/img/c/br/rect/h40.webp" alt="Brasil">

2. API de metadados / Metadata API

Adicione ?key=YOUR_API_KEY em toda chamada /v1/*:

Add ?key=YOUR_API_KEY to every /v1/* call:

GET /v1/c/{lookup}?key=...     # país por iso2 / iso3 / numérico / emoji / hex
GET /v1/s/{iso2-sub}?key=...   # subdivisão / subdivision
GET /v1/calling/{code}?key=... # países por código de discagem / by calling code
GET /health                    # público / public

O lookup de país aceita vários formatos / Country lookup accepts several formats:

GET /v1/c/us                       # ISO-2
GET /v1/c/usa                      # ISO-3
GET /v1/c/840                      # numérico / numeric
GET /v1/c/1F1FA-1F1F8              # emoji hex
GET /v1/c/%F0%9F%87%BA%F0%9F%87%B8 # 🇺🇸 url-encoded
GET /v1/s/us-ca                    # Califórnia
GET /v1/calling/+55                # Brasil (e outros do código)

3. Formato da resposta / Response shape

GET /v1/c/us:

{
  "iso2": "US",
  "iso3": "USA",
  "numeric": "840",
  "emoji": "🇺🇸",
  "name": "United States",
  "names": { "en": "...", "pt": "...", "es": "...", "de": "...", "fr": "...", "it": "..." },
  "calling_code": "+1",
  "tld": ".us",
  "currency": "USD",
  "continent": "NA",
  "has_subdivisions": true,
  "flags": {
    "rect":   { "svg": "/img/c/us/rect.svg",   "webp": "/img/c/us/rect/h{h}.webp" },
    "square": { "svg": "/img/c/us/square.svg", "webp": "/img/c/us/square/h{h}.webp" }
  }
}

Troque {h} por uma das 8 alturas para montar a URL da imagem. / Replace {h} with one of the 8 heights to build the image URL.

4. Exemplos por linguagem / Examples by language

curl:

curl "https://flags.api.insyde.one/v1/c/br?key=YOUR_API_KEY"

JavaScript (fetch):

const BASE = 'https://flags.api.insyde.one';
const KEY = 'YOUR_API_KEY';

async function country(lookup) {
  const res = await fetch(`${BASE}/v1/c/${lookup}?key=${KEY}`);
  if (!res.ok) throw new Error((await res.json()).error);
  return res.json();
}

const br = await country('br');
// monta a bandeira em 40px de altura / build the 40px-tall flag
const flag = BASE + br.flags.rect.webp.replace('{h}', '40');

Python (requests):

import requests

resp = requests.get("https://flags.api.insyde.one/v1/calling/+55",
                    params={"key": "YOUR_API_KEY"})
resp.raise_for_status()
countries = resp.json()

5. Códigos de erro / Error codes

HTTP	Significado / Meaning	O que fazer / What to do
`401`	Chave inválida/ausente em `/v1` / Invalid or missing key on `/v1`	Adicione `?key=` válido / Add a valid `?key=`
`404`	País/subdivisão/imagem não encontrada / Country, subdivision, or image not found	Confira o código/forma/altura / Check the code, shape, height

6. Cache

Rota / Route	Cache-Control
`/img/*`	`public, max-age=86400, s-maxage=31536000, immutable`
`/v1/*` 200	`public, max-age=60, s-maxage=86400`
`/v1/*` 401	`no-store`

7. Limitações / Limitations

Subdivisões cobrem BR, DE, US, ES (outras retornam 404). / Subdivisions cover BR, DE, US, ES (others 404).
Bandeiras quadradas de subdivisões podem não existir (404). / Subdivision square flags may not exist (404).
Sem endpoint "listar tudo" — apenas lookups individuais. / No "list all" endpoint — single-record lookups only.

Back to Insyde APIs