Custom Connector
Countrylayer Connector
Global
The Countrylayer Connector provides access to detailed country information. It acts as a proxy supporting retrieval of all countries and searches by country name, capital, language, currency, region, regional bloc, calling code, or alpha code, with field filtering and API-key authentication.
Overview
Integration Overview
This document provides a detailed guide for each integration point, its purpose, configuration, and workflow support using the Countrylayer Connector.
- getAllCountries. Retrieves a list of all available countries.
- searchCountriesByName. Searches for countries by name, with optional full-text search.
- searchCountriesByCapital. Searches for countries by capital city name.
- searchCountriesByLanguage. Searches for countries by official language.
- searchCountriesByCurrency. Searches for countries by official currency.
- searchCountriesByRegion. Searches for countries by region.
- searchCountriesByRegionalBloc. Searches for countries by regional bloc membership.
- searchCountriesByCallingCode. Searches for countries by calling code.
- searchCountriesByAlphaCode. Searches for countries by alpha code.
- ping. Checks the health of the connector service.
Documentation
Detailed Integration Documentation
Get All Countries
| Operation ID | getAllCountries |
|---|---|
| Endpoint | /all-countries |
| Purpose | Retrieves a list of all available countries, with optional filtering to include specific fields. Data may be limited by subscription plan. |
| Parameters | Required: access_key. Optional: filters – semicolon-separated fields (e.g. name;capital;currencies). |
| Configuration | Configure CONNECTOR_ENV_COUNTRYLAYER_BASE_URL and CONNECTOR_ENV_PORT (default 8081). |
| Output | Successful: JSON array of country objects (name, alpha2Code, alpha3Code, callingCodes, capital, region, subregion, population, latlng, currencies, languages, flag, regionalBlocs, etc.). Failure: error object (invalid_access_key). |
| Workflow example | Execute getAllCountries with filters=name;capital;currencies, then populate a country selection dropdown. |
Search Countries by Name
| Operation ID | searchCountriesByName |
|---|---|
| Endpoint | /search-by-name/{name} |
| Purpose | Searches for countries by name, supporting partial or full-text searches, with optional filtering. |
| Parameters | Required: access_key, name (e.g. Germany). Optional: fullText (boolean), filters. |
| Configuration | Configure the connector with the correct base URL. |
| Output | Successful: JSON array of country objects. Failure: error object (404_not_found). |
| Workflow example | Execute searchCountriesByName with name=Germany and fullText=true for search functionality. |
Search Countries by Capital
| Operation ID | searchCountriesByCapital |
|---|---|
| Endpoint | /search-by-capital/{capital} |
| Purpose | Retrieves country data by capital city name, with optional filtering. |
| Parameters | Required: access_key, capital (e.g. Berlin). Optional: filters. |
| Configuration | Configure the connector with the correct base URL. |
| Output | Successful: JSON array of country objects. Failure: error object (404_not_found). |
| Workflow example | Execute searchCountriesByCapital with capital=Berlin for geographic or travel applications. |
Search Countries by Language
| Operation ID | searchCountriesByLanguage |
|---|---|
| Endpoint | /search-by-language/{language} |
| Purpose | Retrieves country data by official language spoken, with optional filtering. |
| Parameters | Required: access_key, language (e.g. ita). Optional: filters. |
| Configuration | Configure the connector with the correct base URL. |
| Output | Successful: JSON array of country objects. Failure: error object (404_not_found). |
| Workflow example | Execute searchCountriesByLanguage with language=ita for linguistic or cultural analysis. |
Search Countries by Currency
| Operation ID | searchCountriesByCurrency |
|---|---|
| Endpoint | /search-by-currency/{currency} |
| Purpose | Retrieves country data by official currency used, with optional filtering. |
| Parameters | Required: access_key, currency (e.g. EUR). Optional: filters. |
| Configuration | Configure the connector with the correct base URL. |
| Output | Successful: JSON array of country objects. Failure: error object (404_not_found). |
| Workflow example | Execute searchCountriesByCurrency with currency=EUR for financial or e-commerce applications. |
Search Countries by Region
| Operation ID | searchCountriesByRegion |
|---|---|
| Endpoint | /search-by-region/{region} |
| Purpose | Retrieves country data by region, with optional filtering. |
| Parameters | Required: access_key, region (e.g. Europe). Optional: filters. |
| Configuration | Configure the connector with the correct base URL. |
| Output | Successful: JSON array of country objects. Failure: error object (404_not_found). |
| Workflow example | Execute searchCountriesByRegion with region=Europe for regional analysis or mapping. |
Search Countries by Regional Bloc
| Operation ID | searchCountriesByRegionalBloc |
|---|---|
| Endpoint | /search-by-regionalbloc/{regionalbloc} |
| Purpose | Retrieves country data by regional bloc membership, with optional filtering. |
| Parameters | Required: access_key, regionalbloc (e.g. EU). Optional: filters. |
| Configuration | Configure the connector with the correct base URL. |
| Output | Successful: JSON array of country objects. Failure: error object (404_not_found). |
| Workflow example | Execute searchCountriesByRegionalBloc with regionalbloc=EU for policy or trade applications. |
Search Countries by Calling Code
| Operation ID | searchCountriesByCallingCode |
|---|---|
| Endpoint | /search-by-callingcode/{callingcode} |
| Purpose | Retrieves country data by official calling code, with optional filtering. |
| Parameters | Required: access_key, callingcode (e.g. 49). Optional: filters. |
| Configuration | Configure the connector with the correct base URL. |
| Output | Successful: JSON array of country objects. Failure: error object (404_not_found). |
| Workflow example | Execute searchCountriesByCallingCode with callingcode=49 for telecom or contact management. |
Search Countries by Alpha Code
| Operation ID | searchCountriesByAlphaCode |
|---|---|
| Endpoint | /search-by-alpha-code/{code} |
| Purpose | Retrieves country data by alpha code, with optional filtering. |
| Parameters | Required: access_key, code (e.g. DE). Optional: filters. |
| Configuration | Configure the connector with the correct base URL. |
| Output | Successful: JSON array of country objects. Failure: error object (404_not_found). |
| Workflow example | Execute searchCountriesByAlphaCode with code=DE for country-specific data processing. |
Health Check
| Operation ID | ping |
|---|---|
| Endpoint | /ping |
| Purpose | Checks the health of the connector service. |
| Parameters | None. |
| Configuration | No specific configuration required. |
| Output | Successful: plain text “OK” with status 200. Failure: appropriate error status if the service is unavailable. |
| Workflow example | Execute ping to verify the connector is running and confirm service availability. |
Example Workflow: Country Information Retrieval and Filtering
| Retrieve all countries | Execute getAllCountries with filters=name;capital;currencies for a country selection dropdown. |
|---|---|
| Search by name | Execute searchCountriesByName with name=Germany and fullText=true for customer validation or localization. |
| Search by currency | Execute searchCountriesByCurrency with currency=EUR for financial calculations or market analysis. |
| Search by region | Execute searchCountriesByRegion with region=Europe for regional reporting or mapping. |
Support
For technical support, contact custom-connectors-support@isolutions.sa.