# Flags API
> National flag design as an API — built on the classic UCI "Flags" dataset (194 countries) and enriched with each country's ISO 3166-1 alpha-2 code, its Unicode flag emoji and ready-to-use SVG / PNG image URLs. For each flag the API exposes its real design attributes: the number of vertical bars and horizontal stripes, the colours present, the predominant ("main") hue, the colours of the top-left and bottom-right corners, and which symbols appear — circles, crosses, saltires, quartered fields, stars or suns, a crescent, a triangle, an inanimate icon (e.g. an anchor), an animate image (e.g. an eagle) or written text. Look a flag up by country or code, search, or FILTER flags by colour, main hue or symbol — "every flag with a crescent", "flags that are mainly green". Served from memory — always fast.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/flags-api/..."
```

## Pricing
- **Free** (Free) — 25,000 calls/Mo, 3 req/s
- **Starter** ($5/Mo) — 250,000 calls/Mo, 10 req/s
- **Pro** ($12/Mo) — 1,200,000 calls/Mo, 25 req/s
- **Mega** ($30/Mo) — 6,000,000 calls/Mo, 60 req/s

## Endpoints

### Lookup

#### `GET /v1/flag` — Flag by country or code

**Parameters:**
- `country` (query, optional, string) — Country name Example: `Germany`
- `code` (query, optional, string) — ISO 3166-1 alpha-2 code Example: `de`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/flags-api/v1/flag?country=Germany&code=de"
```

**Response:**
```json
{
    "data": {
        "flag": {
            "code": "DE",
            "emoji": "🇩🇪",
            "country": "Germany FRG",
            "image_png": "https://flagcdn.com/w320/de.png",
            "image_svg": "https://flagcdn.com/de.svg",
            "attributes": {
                "bars": 0,
                "icon": false,
                "text": false,
                "stars": 0,
                "colors": [
                    "red",
                    "gold",
                    "black"
                ],
                "animate": false,
                "circles": 0,
                "colours": 3,
                "crosses": 0,
                "mainhue": "black",
                "stripes": 3,
                "topleft": "black",
                "botright": "gold",
                "crescent": false,
                "quarters": 0,
                "saltires": 0,
                "triangle": false
            }
        }
    },
    "meta": {
        "timestamp": "2026-06-08T18:25:10.023Z",
        "request_id": "03c7c2ed-902f-4aca-8a63-1bca8936ff78"
    },
    "status": "ok",
    "message": "Flag retrieved successfully",
    "success": true
}
```

### Search

#### `GET /v1/search` — Search flags by country

**Parameters:**
- `q` (query, required, string) — Search query (min 2 chars) Example: `united`
- `limit` (query, optional, string) — Max results (1-100) Example: `25`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/flags-api/v1/search?q=united&limit=25"
```

**Response:**
```json
{
    "data": {
        "count": 0,
        "flags": [],
        "query": "united",
        "total": 0
    },
    "meta": {
        "timestamp": "2026-06-08T18:25:10.115Z",
        "request_id": "002e871a-edc3-44df-ab46-dde2f60a2333"
    },
    "status": "ok",
    "message": "Search results retrieved successfully",
    "success": true
}
```

### Filter

#### `GET /v1/filter` — Filter flags by colour, hue or symbol

**Parameters:**
- `color` (query, optional, string) — A colour present on the flag Example: `green`
- `mainhue` (query, optional, string) — Predominant hue Example: `green`
- `symbol` (query, optional, string) — crescent, star, cross, saltire, circle, triangle, quarter, text, icon, animate Example: `crescent`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/flags-api/v1/filter?color=green&mainhue=green&symbol=crescent"
```

**Response:**
```json
{
    "data": {
        "count": 4,
        "flags": [
            {
                "code": "DZ",
                "emoji": "🇩🇿",
                "country": "Algeria",
                "image_png": "https://flagcdn.com/w320/dz.png",
                "image_svg": "https://flagcdn.com/dz.svg",
                "attributes": {
                    "bars": 2,
                    "icon": false,
                    "text": false,
                    "stars": 1,
                    "colors": [
                        "red",
                        "green",
                        "white"
                    ],
                    "animate": false,
                    "circles": 0,
                    "colours": 3,
                    "crosses": 0,
                    "mainhue": "green",
                    "stripes": 0,
                    "topleft": "green",
                    "botright": "white",
                    "crescent": true,
                    "quarters": 0,
                    "saltires": 0,
                    "triangle": false
                }
            },
            {
                "code": null,
                "emoji": null,
                "country": "Comorro Islands",
                "image_png": null,
                "image_svg": null,
                "attributes": {
                    "bars": 0,
                    "icon": false,
                    "text": false,
                    "stars": 4,
                    "colors": [
                        "
…(truncated, see openapi.json for full schema)
```

### List

#### `GET /v1/list` — List all flags

**Parameters:**
- `limit` (query, optional, string) — Page size (1-300) Example: `50`
- `offset` (query, optional, string) — Offset Example: `0`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/flags-api/v1/list?limit=50&offset=0"
```

**Response:**
```json
{
    "data": {
        "count": 50,
        "flags": [
            {
                "code": "AF",
                "emoji": "🇦🇫",
                "country": "Afghanistan",
                "image_png": "https://flagcdn.com/w320/af.png",
                "image_svg": "https://flagcdn.com/af.svg",
                "attributes": {
                    "bars": 0,
                    "icon": true,
                    "text": false,
                    "stars": 1,
                    "colors": [
                        "red",
                        "green",
                        "gold",
                        "white",
                        "black"
                    ],
                    "animate": false,
                    "circles": 0,
                    "colours": 5,
                    "crosses": 0,
                    "mainhue": "green",
                    "stripes": 3,
                    "topleft": "black",
                    "botright": "green",
                    "crescent": false,
                    "quarters": 0,
                    "saltires": 0,
                    "triangle": false
                }
            },
            {
                "code": "AL",
                "emoji": "🇦🇱",
                "country": "Albania",
                "image_png": "https://flagcdn.com/w320/al.png",
                "image_svg": "https://flagcdn.com/al.svg",
                "attributes": {
                    "bars": 0,
                    "icon": false,
   
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Service metadata

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/flags-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "service": "flags-api",
        "endpoints": {
            "GET /v1/flag": "Flag by country (country=, e.g. Germany) or ISO code (code=, e.g. de).",
            "GET /v1/list": "List all flags (limit, offset).",
            "GET /v1/meta": "This document.",
            "GET /v1/filter": "Filter flags by color=, mainhue= or symbol= (crescent, star, cross, saltire, circle, triangle, quarter, text, icon, animate).",
            "GET /v1/search": "Search flags by country name or code (q=, min 2 chars)."
        },
        "description": "National flag design (UCI Flags dataset, 194 countries) enriched with ISO 3166-1 alpha-2 code, Unicode flag emoji and SVG/PNG image URLs. Exposes each flag's bars, stripes, colours, main hue, corner colours and symbols (stars, crescent, cross, saltire, circle, triangle, icon, animate, text). Look up by country or code, search, or filter by colour / main hue / symbol. No key.",
        "total_flags": 194
    },
    "meta": {
        "timestamp": "2026-06-08T18:25:10.442Z",
        "request_id": "50d599f6-c2de-45e2-bb84-9e3e5076e73d"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/flags-api
OpenAPI spec: https://www.oanor.com/api/flags-api/openapi.json