تخطي إلى المحتوى
POST AI agent ready /v1/country/lookup

Country Lookup API - ISO Codes, Capital, Currency, Phone Prefix

Accepts a 2-letter ISO 3166-1 alpha-2 code, 3-letter alpha-3 code, or partial name match. Returns the country name, code, code3, numeric code, capital, currency code and name, phone prefix, continent, and flag emoji.

Parameters

stringrequired

Country identifier: alpha-2 (e.g., "JP"), alpha-3 ("JPN"), or name ("Japan").

Code examples

curl -X POST https://api.botoi.com/v1/country/lookup \
  -H "Content-Type: application/json" \
  -d '{"query":"Japan"}'

When to use this API

Fill a country dropdown with flags

Call the endpoint for each user-selected country and display the flag_emoji next to the name. No icon library required; emoji renders natively in every modern browser.

Derive default currency from country

When a user picks their shipping country, look it up and set the currency selector to currency_code. Much lighter than shipping a 200KB locale library.

Format phone inputs

Given a country from an address form, set the phone input prefix to phone_prefix. Combined with /v1/phone/validate, you catch most format errors before they hit your SMS provider.

Frequently asked questions

What matches are accepted?
Exact alpha-2 code (JP), exact alpha-3 code (JPN), or partial name substring match (case-insensitive). Name match returns the first country whose name contains the query as a substring.
How many countries are in the database?
All 249 ISO 3166-1 officially assigned entries. Some dependent territories share a phone prefix with their governing country (e.g., Puerto Rico uses +1 US).
Why is Kosovo not in the list?
Kosovo does not have an officially assigned ISO 3166-1 code. The endpoint follows the official ISO list; user-assigned codes (XK) are excluded.
Is the flag_emoji reliable across platforms?
Flag emojis use regional indicator symbols that render on macOS, iOS, Android, and most modern Linux distros. Windows 10+ renders the two-letter code instead of a flag image by default.
What is the numeric code for?
ISO 3166-1 numeric (M49) is a three-digit code (004 Afghanistan, 840 US). Useful for legacy systems that store country as integer and for UN statistics.

Get your API key

Free tier includes 5 requests per minute with no credit card required. Upgrade for higher limits.

Sign up free View full docs