restcountries.com APIrestcountries.com ↗
Look up countries by name and get capital, population, region, currencies, and languages. Single endpoint, fuzzy matching, returns structured JSON.
curl -X GET 'https://api.parse.bot/scraper/a5b531c0-d31c-4811-9193-08343f10dff8/get_country?name=Canada' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed Python client. Install the CLI, sign in, then pull this API’s generated client:
pip install parse-sdk parse login parse add --marketplace restcountries-com-api
parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: REST Countries SDK — look up countries by name."""
from parse_apis.REST_Countries_API import RestCountries, NotFoundError
client = RestCountries()
# Search for countries matching a name
for country in client.countries.search(name="Canada", limit=5):
print(country.name, country.region, country.population)
for currency in country.currencies:
print(f" Currency: {currency.name} ({currency.code}, {currency.symbol})")
for lang in country.languages:
print(f" Language: {lang.name} ({lang.native_name})")
# Drill into the first result for a specific search
result = client.countries.search(name="France", limit=1).first()
if result:
print(result.name, result.official_name, result.capital)
# Handle not-found errors gracefully
try:
found = client.countries.search(name="Atlantis", limit=1).first()
if found:
print(found.name, found.population)
else:
print("No country matched")
except NotFoundError as exc:
print(f"Not found: {exc}")
print("exercised: countries.search / currency fields / language fields / error handling")
Search for countries by name using fuzzy matching against the REST Countries database. Returns matching countries with their capital city, population, geographic region, currencies, and languages. The search matches common names, official names, and country codes. Uses the publicly available demo key which returns sample data (Canada) for all queries; a paid API key enables full search functionality.
| Param | Type | Description |
|---|---|---|
| namerequired | string | Country name or partial name to search for (e.g. 'Canada', 'stan', 'United'). |
{
"type": "object",
"fields": {
"total": "integer count of matched countries",
"countries": "array of country objects with name, official_name, capital, population, region, subregion, currencies, and languages"
},
"sample": {
"data": {
"total": 1,
"countries": [
{
"name": "Canada",
"region": "Americas",
"capital": [
"Ottawa"
],
"languages": [
{
"name": "English",
"native_name": "English"
},
{
"name": "French",
"native_name": "français"
}
],
"subregion": "North America",
"currencies": [
{
"code": "CAD",
"name": "Canadian dollar",
"symbol": "$"
}
],
"population": 41575585,
"official_name": "Canada"
}
]
},
"status": "success"
}
}About the restcountries.com API
The REST Countries API exposes one endpoint — get_country — that searches the REST Countries database by name and returns up to 8 structured fields per match, including capital city, population, region, subregion, currencies, and languages. Fuzzy matching means partial inputs like 'stan' or 'United' return all relevant countries in a single response, making it straightforward to power dropdowns, validation logic, or geography lookups.
What the API Returns
The get_country endpoint accepts a single required name parameter — a full or partial country name — and returns a total count alongside a countries array. Each object in the array includes name (common name), official_name, capital, population, region, subregion, currencies, and languages. All of these fields are present on every matched result, so you do not need to guard against missing keys depending on query type.
Search Behavior
The name input is matched against common names, official names, and country codes in the underlying REST Countries database. A query like 'stan' will surface Afghanistan, Kazakhstan, Pakistan, and other matches simultaneously. Queries against partial strings such as 'United' return United States, United Kingdom, United Arab Emirates, and any other entries that match — the total field tells you exactly how many were found without needing to count the array manually.
Currencies and Languages
The currencies and languages fields are returned as structured objects rather than flat strings, so your code can iterate over multiple values per country. A country like Switzerland, for example, carries entries for multiple official languages. This makes the endpoint useful for locale detection, form validation, or display layers that need to present currency symbols or language names alongside country selections.
The restcountries.com API is a managed, monitored endpoint for restcountries.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when restcountries.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official restcountries.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Populate a country selector dropdown with official names, capitals, and regions pulled from
get_country. - Validate user-entered country names by fuzzy-matching against the REST Countries database and returning the canonical
official_name. - Display a travel destination card showing capital city, population, and subregion for any searched country.
- Build a currency lookup tool that resolves a country name to its associated
currenciesobject. - Implement locale detection by mapping a country name to its
languagesfield for language preference logic. - Filter countries by partial string (e.g., 'island') to generate regional geography quizzes using
nameandregionfields. - Cross-reference
populationandregiondata for basic demographic summaries in data visualization dashboards.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 250 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does REST Countries have an official developer API?+
What does the `get_country` endpoint return when a partial name like 'stan' is used?+
total field reflects the exact count of matches, and each entry in the countries array includes all eight fields: name, official_name, capital, population, region, subregion, currencies, and languages.Can I filter results by region or retrieve all countries in a continent?+
get_country endpoint filters only by name string. The region and subregion fields are returned in each result, so you can filter client-side after fetching. You can fork this API on Parse and revise it to add a region-based endpoint if server-side geographic filtering is needed.Does the API return geographic coordinates, flag images, or ISO codes?+
name, official_name, capital, population, region, subregion, currencies, and languages. Coordinates, flag URLs, and ISO alpha codes are not included in the current response shape. You can fork this API on Parse and revise it to surface those additional fields from the REST Countries source.