REST Countries API
The REST Countries API provides a RESTful interface to access comprehensive country data — names, flags, regions, languages, currencies, and more. It supports querying country data by name, code, currency, language, region, and other criteria, with no authentication required.
Integration Overview
The REST Countries API offers the following integration points to query country-related data, with optional field filtering to customize responses.
- Get All / Independent Countries. Retrieve all countries (with field filtering), or only independent ones.
- Get Country by Name / Code / Codes. Retrieve country details by name, a single ISO code, or a list of codes.
- Get by Currency / Demonym / Language. Fetch countries by currency, demonym, or spoken language.
- Get by Capital / Region / Subregion / Translation. Fetch countries by capital, region, subregion, or translated name.
- Generic Service with Field Filtering. Query any service with customizable field filtering.
Detailed Integration Documentation
Get All / Independent Countries
| Actions | Get All Countries / getIndependentCountries |
|---|---|
| Endpoints | GET /all · GET /independent |
| Purpose | Retrieves all countries (with optional field filtering), or only countries that are independent. |
| Parameters | All — optional: fields (e.g. name,flags). Independent — required: status (boolean, e.g. true). |
| Output | Successful: a JSON array of countries. Failure: error if fields is malformed or status is missing/invalid. |
| Workflow example | GET /all?fields=name,flags to populate a dashboard, or /independent?status=true to filter. |
Get Country by Name / Code / Codes
| Actions | getCountryByName / getCountryByCode / getCountriesByCodes |
|---|---|
| Endpoints | GET /name/{name} · GET /alpha/{code} · GET /alpha?codes= |
| Purpose | Retrieves a country by full/partial name, by a single ISO 3166-1 code, or several countries by a list of codes. |
| Parameters | name (path) + optional fullText (boolean); code (path) — alpha-2 or alpha-3; codes — comma-separated (e.g. US,GB,FR). |
| Output | Successful: a JSON object or array with country details. Failure: error if no match / invalid code. |
| Workflow example | GET /name/Canada?fullText=true, GET /alpha/US, or GET /alpha?codes=US,GB,FR. |
Get by Currency / Demonym / Language
| Actions | getCountriesByCurrency / getCountriesByDemonym / getCountriesByLanguage |
|---|---|
| Endpoints | GET /currency/{currency} · GET /demonym/{demonym} · GET /lang/{language} |
| Purpose | Retrieves countries that use a currency (ISO 4217), match a demonym, or speak a language (ISO 639-1). |
| Parameters | Required (path): currency (e.g. usd), demonym (e.g. American), or language (e.g. en). |
| Output | Successful: a JSON array of matching countries. Failure: error if the value is invalid. |
| Workflow example | GET /currency/usd, /demonym/American, or /lang/en. |
Get by Capital / Region / Subregion / Translation
| Actions | getCountriesByCapital / getCountriesByRegion / getCountriesBySubregion / getCountriesByTranslation |
|---|---|
| Endpoints | GET /capital/{capital} · /region/{region} · /subregion/{subregion} · /translation/{translation} |
| Purpose | Retrieves countries by capital city, region (e.g. Europe), subregion (e.g. Northern Europe), or translated name (e.g. Deutschland). |
| Parameters | Required (path): capital, region, subregion, or translation. |
| Output | Successful: a JSON array of matching countries. Failure: error if the value is invalid or no match. |
| Workflow example | GET /region/Europe, /subregion/Northern Europe, or /translation/Deutschland. |
Generic Service with Field Filtering
| Action | getGenericService |
|---|---|
| Endpoint | GET /{service} |
| Purpose | A flexible endpoint to query any service with customizable field filtering. |
| Parameters | Required (path): service (e.g. all). Optional: fields (e.g. name,flags,region). |
| Output | Successful: a JSON response with filtered data. Failure: error if the service or fields are invalid. |
| Workflow example | GET /all?fields=name,flags,region to extract specific fields. |
Example Workflow: Country Information Dashboard
| Fetch all countries | GET /all?fields=name,flags,region to populate names and flags. |
|---|---|
| Country detail | GET /name/France?fullText=true for population, capital, and languages. |
| Filter | Use region/subregion endpoints to segment the dashboard. |
| Monitor | Handle invalid inputs gracefully and log calls; use fields to reduce payloads (CORS supported, no auth). |
Use Case
A travel insights platform integrates the REST Countries API on GCP for real-time access to global country metadata. Using /all, /name/{name}, and /region/{region}, the system fetches flags, regions, capitals, currencies, and languages, ingested into BigQuery for demographic analysis and multilingual personalization. Filtered field queries reduce payloads, and responses are cached in Cloud Storage — powering destination intelligence, regional segmentation, and international compliance across web and mobile services.
For technical support, contact custom-connectors-support@isolutions.sa.