Name: Country Info API - Population, Currency, Holidays & More
Brand: quotalink
SKU: api-quotalink-country-info-api
Availability: InStock
Author: API Market

李乐

## Overview

Country Info API gives you a complete profile for any of 227 countries in a single call. Instead of stitching together a population dataset, a currency feed, a holiday calendar and a city list yourself, you send one country code and get all of it back in one JSON response.

Look up a country by ISO2 (`JP`), ISO3 (`JPN`) or plain name (`Japan`) — all three work on every endpoint that takes a code. Alongside the full profile there are focused endpoints for public holidays and live exchange rates when you only need one slice of the data.

## Features

- **227 countries** — searchable list with ISO2/ISO3 codes, flags, population and currency.
- **Flexible lookup** — ISO2, ISO3 or full country name, case-insensitive.
- **Full country profile** — currency with symbol, live exchange rate, 10 years of population history, 15 major cities, and the year's public holidays in one response.
- **Public holidays** — full-year holiday calendars with English and local names, for any year.
- **Live exchange rates** — 166 currencies against USD, both directions supported.
- **Helpful errors** — unknown codes return a 404 with a hint showing the accepted formats.
- **No provider account needed** — your API.market key is the only credential.

## Use Cases

- **Travel and booking apps** — show destination currency, flag and upcoming public holidays.
- **E-commerce** — display local currency and convert prices at live rates.
- **HR and payroll** — track public holidays across every country your team works in.
- **Fintech dashboards** — pull 166 exchange rates in one request.
- **Onboarding and forms** — populate country pickers with codes, names and flags.
- **Education and research** — population history for demographic charts.

## API Documentation

### Base URL

```
https://prod.api.market/api/v1/quotalink/country-info-api
```

### Authentication

Pass your API.market key in the `x-api-market-key` header on every request. No other credential is needed.

```
x-api-market-key: YOUR_API_MARKET_KEY
```

Find your key under **Account → API Keys** on api.market. Requests without this header return `400` with `No x-api-market-key or x-magicapi-key defined in headers`.

### Country codes

Every endpoint that takes a `{code}` path parameter accepts three formats interchangeably:

| Format | Example |
| --- | --- |
| ISO 3166-1 alpha-2 | `JP` |
| ISO 3166-1 alpha-3 | `JPN` |
| Country name | `Japan` |

### Endpoints

#### GET /countries

Lists countries with basic information.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `search` | query | string | No | Filter by name, case-insensitive |
| `limit` | query | integer | No | Maximum results, default and maximum 250 |

```bash
curl "https://prod.api.market/api/v1/quotalink/country-info-api/countries?search=japan" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{
  "success": true,
  "count": 1,
  "countries": [
    {
      "name": "Japan",
      "iso2": "JP",
      "iso3": "JPN",
      "currency_code": "JPY",
      "population": 126529100,
      "flag": "https://upload.wikimedia.org/wikipedia/en/9/9e/Flag_of_Japan.svg"
    }
  ]
}
```

Omit `search` to get the full list of 227 countries.

#### GET /countries/{code}

Returns the full profile for one country.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `code` | path | string | Yes | ISO2, ISO3 or country name |

```bash
curl "https://prod.api.market/api/v1/quotalink/country-info-api/countries/JP" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{
  "success": true,
  "country": {
    "name": "Japan",
    "iso2": "JP",
    "iso3": "JPN",
    "flag": "https://upload.wikimedia.org/wikipedia/en/9/9e/Flag_of_Japan.svg",
    "population": 126529100,
    "population_year": 2018,
    "population_history": [
      { "year": 2009, "value": 128047000 },
      { "year": 2010, "value": 128070000 }
    ],
    "currency": {
      "code": "JPY",
      "name": "Yen",
      "symbol": "¥"
    },
    "exchange_rate": {
      "currency_code": "JPY",
      "rate_to_usd": 159.20446,
      "rate_from_usd": 0.006281,
      "description": "1 USD = 159.20446 JPY"
    },
    "major_cities": ["Abashiri", "Abiko", "Abira", "Aboshiku-okinohama"],
    "holidays": {
      "year": 2026,
      "count": 16,
      "upcoming": [
        { "date": "2026-01-01", "name": "元日", "type": "Public" },
        { "date": "2026-01-12", "name": "成人の日", "type": "Public" }
      ]
    },
    "summary": "",
    "wikipedia_url": "",
    "thumbnail": ""
  }
}
```

Response fields:

| Field | Type | Description |
| --- | --- | --- |
| `name`, `iso2`, `iso3` | string | Country name and ISO codes |
| `flag` | string | URL to the country's flag (SVG) |
| `population` | integer | Population figure |
| `population_year` | integer | Year the population figure refers to |
| `population_history` | array | Last 10 years of population, as `{year, value}` |
| `currency` | object | `code`, `name` and `symbol` |
| `exchange_rate` | object | Live rate against USD, both directions, plus a formatted `description` |
| `major_cities` | array | Up to 15 city names |
| `holidays.year` | integer | Year the holiday data covers |
| `holidays.count` | integer | Number of public holidays that year |
| `holidays.upcoming` | array | Upcoming holidays as `{date, name, type}`, where `name` is the local-language name |
| `summary`, `wikipedia_url`, `thumbnail` | string | Wikipedia enrichment fields. These are currently returned as empty strings — use `GET /countries/{code}/holidays` and the fields above for data you can rely on |

#### GET /countries/{code}/holidays

Returns the full public holiday calendar for a country and year.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `code` | path | string | Yes | ISO2, ISO3 or country name |
| `year` | query | integer | No | Year to query, defaults to the current year |

```bash
curl "https://prod.api.market/api/v1/quotalink/country-info-api/countries/JP/holidays?year=2026" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{
  "success": true,
  "country": "Japan",
  "iso2": "JP",
  "year": 2026,
  "count": 16,
  "holidays": [
    {
      "date": "2026-01-01",
      "name": "New Year's Day",
      "local_name": "元日",
      "fixed": false,
      "global": true,
      "type": "Public"
    },
    {
      "date": "2026-01-12",
      "name": "Coming of Age Day",
      "local_name": "成人の日",
      "fixed": false,
      "global": true,
      "type": "Public"
    }
  ]
}
```

Note the difference from the profile endpoint: here `name` is the English name and `local_name` is the local-language name. In `GET /countries/{code}` the `holidays.upcoming[].name` field carries the local name instead.

A year with no holiday data returns `200` with `count: 0` and an empty `holidays` array rather than an error.

#### GET /countries/{code}/exchange-rate

Returns the exchange rate for a single country's currency.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `code` | path | string | Yes | ISO2, ISO3 or country name |

```bash
curl "https://prod.api.market/api/v1/quotalink/country-info-api/countries/JP/exchange-rate" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{
  "success": true,
  "country": "Japan",
  "currency": {
    "code": "JPY",
    "name": "Yen",
    "symbol": "¥"
  },
  "exchange_rate": {
    "currency_code": "JPY",
    "rate_to_usd": 159.20446,
    "rate_from_usd": 0.006281,
    "description": "1 USD = 159.20446 JPY"
  }
}
```

Use `rate_to_usd` to convert USD into the local currency and `rate_from_usd` to convert local currency into USD.

#### GET /exchange-rates

Returns every available exchange rate with USD as the base. Takes no parameters.

```bash
curl "https://prod.api.market/api/v1/quotalink/country-info-api/exchange-rates" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{
  "base": "USD",
  "count": 166,
  "rates": {
    "EUR": 0.86417,
    "GBP": 0.738482,
    "JPY": 159.20446,
    "CNY": 6.748651,
    "INR": 95.610406
  }
}
```

Each value is the amount of that currency equal to 1 USD.

## Status Codes

| Code | Meaning | What to do |
| --- | --- | --- |
| `200` | Success | Parse the response body |
| `400` | The `x-api-market-key` header is missing or malformed | Check the header |
| `401` | Invalid or expired API key | Verify the key under Account → API Keys |
| `403` | Your subscription does not cover this endpoint | Check your active plan |
| `404` | Country code not recognised | Use ISO2, ISO3 or the full country name |
| `429` | Plan quota exhausted or rate limit exceeded | Back off and retry, or upgrade |
| `5xx` | Upstream error | Retry with exponential backoff |

## Rate Limits

Both plans allow up to **10 requests per second**. Quotas apply per billing period:

- **Free Trial** — 100 API units, hard limit. Requests are rejected once the quota is spent.
- **Basic** — 1,000 API units per month, soft limit, with overage billed per additional call.

Every endpoint costs one unit per request.

## Error Handling

Errors return JSON with a `success: false` flag and a human-readable message. Unknown country codes also include a `hint`:

```json
{
  "success": false,
  "error": "Country 'ZZZ' not found",
  "hint": "Use ISO2 (CN), ISO3 (CHN), or full name (China)"
}
```

Practical guidance:

- **Check `success` before reading data.** Every successful response carries `success: true`.
- **Retry `429` and `5xx`** with exponential backoff starting around 1 second.
- **Do not retry `400`, `401` or `404`** — the request or the key is wrong and will fail again identically.
- **Allow a few seconds for `GET /countries/{code}`.** It aggregates several upstream sources, so it is the slowest endpoint. Set a client timeout of at least 10 seconds.
- **Treat an empty `holidays` array as valid**, not as a failure — some countries and years genuinely have no data.

## Implementation Guide

### Example Code

**Python**

```python
import requests

BASE = "https://prod.api.market/api/v1/quotalink/country-info-api"
HEADERS = {"x-api-market-key": "YOUR_API_MARKET_KEY"}

response = requests.get(f"{BASE}/countries/JP", headers=HEADERS, timeout=15)
response.raise_for_status()
country = response.json()["country"]

print(country["name"], country["currency"]["symbol"])
print("1 USD =", country["exchange_rate"]["rate_to_usd"], country["currency"]["code"])
```

**Node.js**

```javascript
const BASE = "https://prod.api.market/api/v1/quotalink/country-info-api";
const headers = { "x-api-market-key": process.env.API_MARKET_KEY };

const response = await fetch(`${BASE}/countries/JP/holidays?year=2026`, { headers });
const data = await response.json();

if (!data.success) {
  throw new Error(data.error);
}

for (const holiday of data.holidays) {
  console.log(holiday.date, holiday.name, `(${holiday.local_name})`);
}
```

**Converting a price with live rates**

```javascript
const BASE = "https://prod.api.market/api/v1/quotalink/country-info-api";
const headers = { "x-api-market-key": process.env.API_MARKET_KEY };

const { rates } = await fetch(`${BASE}/exchange-rates`, { headers }).then((r) => r.json());

const priceUsd = 49.99;
const priceJpy = Math.round(priceUsd * rates.JPY);
console.log(`$${priceUsd} = ¥${priceJpy}`);
```

### Performance Optimization

- **Cache exchange rates.** They update at most a few times a day, so fetching `/exchange-rates` once per hour and reusing it beats calling per-country rates repeatedly — and it costs one unit instead of many.
- **Cache the country list.** Names, codes and flags change very rarely. Fetch `/countries` once at startup and keep it in memory.
- **Use the focused endpoints.** If you only need holidays, call `/countries/{code}/holidays` rather than the full profile — it is faster and returns richer holiday data.
- **Fetch profiles in parallel.** The plans allow 10 requests per second, so batch concurrent lookups rather than looping serially.
- **Cache holiday calendars per country and year.** They are fixed once published.

## FAQ

**Do I need an account with the data providers?**

No. Your API.market key is the only credential required.

**Can I look up a country by name instead of a code?**

Yes. `JP`, `JPN` and `Japan` all resolve to the same country, and matching is case-insensitive.

**How many countries are covered?**

227 countries are returned by `GET /countries`.

**How current is the population data?**

Each profile includes a `population_year` field telling you which year the figure refers to; it currently reports 2018. Use `population_history` if you need the trend rather than a single figure.

**Why are `summary`, `wikipedia_url` and `thumbnail` empty?**

The Wikipedia enrichment fields are present in the response schema but are not currently populated. Build against the other fields for now.

**Which currencies are supported for exchange rates?**

166 currencies, all quoted against USD as the base.

**What happens if I request a year with no holiday data?**

You get a `200` response with `count: 0` and an empty `holidays` array, not an error.

**Are the exchange rates real-time?**

They are refreshed daily from the upstream rate feed, so they track the market closely but are not tick-by-tick.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Comprehensive country data API. Get population, currencies, exchange rates, public holidays, and Wikipedia summaries for 200+ countries.

Country Info API - Population, Currency, Holidays & More