canonical: https://jentic.com/apis/restcountries.com/restcountries

# REST Countries API

The REST Countries API returns reference data for more than 250 countries, including names, ISO codes, capitals, flag, region and subregion, population, area, borders, calling codes, currencies, languages, timezones, top-level domains, and memberships. A country can be fetched by its ISO 3166-1 alpha-2 or alpha-3 code, found with fuzzy search across names, capitals, and codes, or listed by the currency it uses or the region it sits in. Responses can be trimmed with response_fields or omit_fields, and the spec states the data is synced every 4 hours from more than 35 sources.

## For AI agents

Look up country reference data such as capitals, currencies, languages, timezones, calling codes, and borders by ISO code, fuzzy name search, currency, or region.

## Scope

Does not handle geocoding, address validation, states or cities, or exchange rates. Use for country-level reference data lookups only.

## Capabilities

- Fetch a country's full record by ISO 3166-1 alpha-2 code such as FR or alpha-3 code such as JPN
- Fuzzy-search countries by name, capital, or code with limit and offset pagination
- List every country that uses a given currency code such as EUR
- List countries in a region such as Europe, Americas, Asia, Africa, or Oceania
- Trim responses to the fields you need with response_fields or exclude fields with omit_fields

## Use cases

### AI agent answering country questions

An assistant agent asked about a country's capital, currency, or timezones should answer from data rather than memory. Through Jentic the agent searches for 'look up country details', loads the getCountryByAlpha2 or searchCountries operation, and requests only the fields it needs with response_fields. The bearer key is injected by Jentic at call time.

Example prompt: Call GET `/countries/v5` with q 'nether' and response_fields 'names,capitals,currencies,timezones', then answer the user's question about the Netherlands

### Normalising country fields in user data

Signup forms and CRM exports collect countries as free text, two-letter codes, or three-letter codes. Fuzzy search on GET `/countries/v5` maps messy input to a country record, and the alpha-2 and alpha-3 lookups confirm a code and return its canonical names and codes, so a pipeline can store one consistent format.

Example prompt: For each country string in a CSV, call GET `/countries/v5` with q set to the string and limit 1, and write the returned alpha-2 code from codes into a new column

### Building country pickers and regional views

Checkout and settings screens need country lists with flags and calling codes, often grouped by region or filtered by currency. GET `/countries/v5/region/{region}` lists countries in a region and GET `/countries/v5/currencies/{currency_code}` lists the countries for a currency, each trimmed with response_fields to keep payloads small.

Example prompt: Call GET `/countries/v5/region/Europe` with response_fields 'names,flag,calling_codes' and build a sorted country picker list

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/countries/v5/codes.alpha_2/{code}` | Get country by ISO alpha-2 code |
| GET | `/countries/v5/codes.alpha_3/{code}` | Get country by ISO alpha-3 code |
| GET | `/countries/v5` | Search countries |
| GET | `/countries/v5/currencies/{currency_code}` | Get countries by currency |
| GET | `/countries/v5/region/{region}` | Get countries by region |

## Key resources

- **Countries** — Country records with names, codes, capitals, flag, region, population, area, borders, calling codes, currencies, languages, timezones, TLDs, and memberships, looked up by code, search, currency, or region

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 66 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 100 / 100
  - Developer Experience & Jentic Compatibility: 59 / 100
  - AI-Readiness & Agent Experience: 45 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 95 / 100
- **View full report:** https://jentic.com/apis/restcountries.com/restcountries/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring REST Countries by hand means attaching the bearer key to each call and knowing which lookup path fits the input you have: alpha-2, alpha-3, currency, region, or fuzzy search. Through Jentic you install once, import REST Countries from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** REST Countries puts the country code, currency code, and region in the URL path (`/countries/v5/region/{region}`, `/countries/v5/currencies/{currency_code}`), so a rule can pin your agent to one region or one currency. Every operation is a read, so scoping here limits which data the agent pulls rather than guarding writes.
- **Credential handling:** Your REST Countries key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'find countries that use the euro' or 'look up country details', and Jentic returns the matching REST Countries operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Countrylayer API** — Country reference data by name, code, capital, currency, and region.
- **Country State City API** — Countries with their states and cities.
- **ExchangeRate-API** — Currency exchange rates.

## FAQ

### What authentication does the REST Countries API use?

The OpenAPI spec declares bearerAuth as the global security scheme: an API key sent as a Bearer token in the Authorization header on each of its operations. Through Jentic the key is held by your own instance and attached at call time, so the agent never handles it.

### Can I get only some fields for a country?

Yes. Every operation accepts response_fields, a comma-separated list of fields to include, and the code and search lookups also accept omit_fields to exclude fields. The Country schema includes names, codes, capitals, flag, region, subregion, population, area, borders, calling_codes, currencies, languages, timezones, tlds, and memberships.

### What are the rate limits for the REST Countries API?

The OpenAPI spec does not specify rate limits. Check https://restcountries.com for current usage terms.

### Is there a REST Countries MCP server?

You don't need an MCP server to give your agent REST Countries. Jentic connects it directly from the API Directory: import it, store your key once, and your agent calls the lookup and search operations it needs on demand, without extra tool definitions sitting in its context.

### Can I limit what my agent is allowed to do with the REST Countries API?

Yes. For example, write a rule that allows only GET `/countries/v5/region/Europe` and GET `/countries/v5/codes.alpha_2/{code}`, so the agent can read European country lists and single-country records but not run open-ended searches. Every call it makes is logged.

### How do I look up a country through Jentic?

Add the REST Countries API to your Jentic One instance from the directory and store your key. Your agent searches for 'look up country details', loads the getCountryByAlpha3 operation, and calls GET `/countries/v5/codes.alpha_3/{code}` with a code such as FRA. To run it on your own infrastructure, install Jentic One from its GitHub repo.
