# Countries API
> Reference data for all 250 countries and territories — capitals, ISO codes (alpha-2/alpha-3), currencies, languages, flags, population, area, borders, calling codes and more. Look up by name, ISO code, region, currency or language.

## 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/countries-api/..."
```

## Pricing
- **Free** (Free) — 25,000 calls/Mo, 5 req/s
- **Basic** ($5/Mo) — 150,000 calls/Mo, 15 req/s
- **Pro** ($15/Mo) — 750,000 calls/Mo, 30 req/s
- **Mega** ($39/Mo) — 3,000,000 calls/Mo, 60 req/s

## Endpoints

### Countries

#### `GET /v1/all` — All countries (summary)

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

**Response:**
```json
{
    "data": {
        "count": 250,
        "countries": [
            {
                "cca2": "AF",
                "cca3": "AFG",
                "name": "Afghanistan",
                "region": "Asia",
                "capital": [
                    "Kabul"
                ],
                "flag_svg": "https://upload.wikimedia.org/wikipedia/commons/5/5c/Flag_of_the_Taliban.svg",
                "subregion": "Southern Asia",
                "population": 43844000,
                "official_name": "Islamic Republic of Afghanistan"
            },
            {
                "cca2": "AX",
                "cca3": "ALA",
                "name": "Åland Islands",
                "region": "Europe",
                "capital": [
                    "Mariehamn"
                ],
                "flag_svg": "https://flagcdn.com/ax.svg",
                "subregion": "Northern Europe",
                "population": 30654,
                "official_name": "Åland Islands"
            },
            {
                "cca2": "AL",
                "cca3": "ALB",
                "name": "Albania",
                "region": "Europe",
                "capital": [
                    "Tirana"
                ],
                "flag_svg": "https://flagcdn.com/al.svg",
                "subregion": "Southeast Europe",
                "population": 2363314,
                "official_name": "Republic of Albania"
            },
            {
                "cca2": "DZ",
                
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/code` — Look up by ISO code(s)

**Parameters:**
- `code` (query, required, string) — ISO alpha-2/alpha-3, comma-separated Example: `de,fr,it`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/countries-api/v1/code?code=de%2Cfr%2Cit"
```

**Response:**
```json
{
    "data": {
        "count": 3,
        "countries": [
            {
                "tld": [
                    ".de"
                ],
                "cca2": "DE",
                "cca3": "DEU",
                "ccn3": null,
                "name": "Germany",
                "latlng": [
                    51,
                    9
                ],
                "region": "Europe",
                "borders": [
                    "AUT",
                    "BEL",
                    "CZE",
                    "DNK",
                    "FRA",
                    "LUX",
                    "NLD",
                    "POL",
                    "CHE"
                ],
                "capital": [
                    "Berlin"
                ],
                "area_km2": 357114,
                "flag_png": "https://flagcdn.com/w320/de.png",
                "flag_svg": "https://flagcdn.com/de.svg",
                "languages": [
                    "German"
                ],
                "subregion": "Western Europe",
                "timezones": [],
                "continents": [
                    "Europe"
                ],
                "currencies": [
                    {
                        "code": "EUR",
                        "name": "euro",
                        "symbol": "€"
                    }
                ],
                "population": 83491249,
                "google_maps": null,
                "calling_code": "+49",
         
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/search` — Find countries by (partial) name

**Parameters:**
- `name` (query, required, string) — Country name or part of it Example: `germany`
- `fullText` (query, optional, string) — Require exact common/official name match (true) Example: `false`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/countries-api/v1/search?name=germany&fullText=false"
```

**Response:**
```json
{
    "data": {
        "count": 1,
        "query": "germany",
        "countries": [
            {
                "tld": [
                    ".de"
                ],
                "cca2": "DE",
                "cca3": "DEU",
                "ccn3": null,
                "name": "Germany",
                "latlng": [
                    51,
                    9
                ],
                "region": "Europe",
                "borders": [
                    "AUT",
                    "BEL",
                    "CZE",
                    "DNK",
                    "FRA",
                    "LUX",
                    "NLD",
                    "POL",
                    "CHE"
                ],
                "capital": [
                    "Berlin"
                ],
                "area_km2": 357114,
                "flag_png": "https://flagcdn.com/w320/de.png",
                "flag_svg": "https://flagcdn.com/de.svg",
                "languages": [
                    "German"
                ],
                "subregion": "Western Europe",
                "timezones": [],
                "continents": [
                    "Europe"
                ],
                "currencies": [
                    {
                        "code": "EUR",
                        "name": "euro",
                        "symbol": "€"
                    }
                ],
                "population": 83491249,
                "google_maps": null,
                "cal
…(truncated, see openapi.json for full schema)
```

### Lists

#### `GET /v1/currency` — Countries using a currency

**Parameters:**
- `currency` (query, required, string) — ISO-4217 currency code Example: `eur`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/countries-api/v1/currency?currency=eur"
```

**Response:**
```json
{
    "data": {
        "count": 36,
        "currency": "EUR",
        "countries": [
            {
                "cca2": "AX",
                "cca3": "ALA",
                "name": "Åland Islands",
                "region": "Europe",
                "capital": [
                    "Mariehamn"
                ],
                "flag_svg": "https://flagcdn.com/ax.svg",
                "subregion": "Northern Europe",
                "population": 30654,
                "official_name": "Åland Islands"
            },
            {
                "cca2": "AD",
                "cca3": "AND",
                "name": "Andorra",
                "region": "Europe",
                "capital": [
                    "Andorra la Vella"
                ],
                "flag_svg": "https://flagcdn.com/ad.svg",
                "subregion": "Southern Europe",
                "population": 88406,
                "official_name": "Principality of Andorra"
            },
            {
                "cca2": "AT",
                "cca3": "AUT",
                "name": "Austria",
                "region": "Europe",
                "capital": [
                    "Vienna"
                ],
                "flag_svg": "https://flagcdn.com/at.svg",
                "subregion": "Central Europe",
                "population": 9200931,
                "official_name": "Republic of Austria"
            },
            {
                "cca2": "BE",
                "cca3": "BEL",
          
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/language` — Countries speaking a language

**Parameters:**
- `language` (query, required, string) — Language name or ISO-639-3 code Example: `german`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/countries-api/v1/language?language=german"
```

**Response:**
```json
{
    "data": {
        "count": 7,
        "language": "german",
        "countries": [
            {
                "cca2": "AT",
                "cca3": "AUT",
                "name": "Austria",
                "region": "Europe",
                "capital": [
                    "Vienna"
                ],
                "flag_svg": "https://flagcdn.com/at.svg",
                "subregion": "Central Europe",
                "population": 9200931,
                "official_name": "Republic of Austria"
            },
            {
                "cca2": "BE",
                "cca3": "BEL",
                "name": "Belgium",
                "region": "Europe",
                "capital": [
                    "Brussels"
                ],
                "flag_svg": "https://flagcdn.com/be.svg",
                "subregion": "Western Europe",
                "population": 11825551,
                "official_name": "Kingdom of Belgium"
            },
            {
                "cca2": "DE",
                "cca3": "DEU",
                "name": "Germany",
                "region": "Europe",
                "capital": [
                    "Berlin"
                ],
                "flag_svg": "https://flagcdn.com/de.svg",
                "subregion": "Western Europe",
                "population": 83491249,
                "official_name": "Federal Republic of Germany"
            },
            {
                "cca2": "LI",
                "cca3": "LIE",
              
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/region` — Countries in a region

**Parameters:**
- `region` (query, required, string) — Region or subregion Example: `europe`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/countries-api/v1/region?region=europe"
```

**Response:**
```json
{
    "data": {
        "count": 53,
        "region": "europe",
        "countries": [
            {
                "cca2": "AX",
                "cca3": "ALA",
                "name": "Åland Islands",
                "region": "Europe",
                "capital": [
                    "Mariehamn"
                ],
                "flag_svg": "https://flagcdn.com/ax.svg",
                "subregion": "Northern Europe",
                "population": 30654,
                "official_name": "Åland Islands"
            },
            {
                "cca2": "AL",
                "cca3": "ALB",
                "name": "Albania",
                "region": "Europe",
                "capital": [
                    "Tirana"
                ],
                "flag_svg": "https://flagcdn.com/al.svg",
                "subregion": "Southeast Europe",
                "population": 2363314,
                "official_name": "Republic of Albania"
            },
            {
                "cca2": "AD",
                "cca3": "AND",
                "name": "Andorra",
                "region": "Europe",
                "capital": [
                    "Andorra la Vella"
                ],
                "flag_svg": "https://flagcdn.com/ad.svg",
                "subregion": "Southern Europe",
                "population": 88406,
                "official_name": "Principality of Andorra"
            },
            {
                "cca2": "AT",
                "cca3": "AUT",
       
…(truncated, see openapi.json for full schema)
```


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