Custom Connector
ExchangeRate Connector
Global
The ExchangeRate Connector facilitates seamless integration with ExchangeRate-API, providing real-time and historical exchange-rate data for 160+ world currencies. It acts as a proxy for latest rates, pair conversions, historical data, supported currency codes, and localization data.
Overview
Integration Overview
This document provides a detailed guide for each integration point, its purpose, configuration, and workflow support using the ExchangeRate Connector. All actions require an apiKey.
- getLatestRates. Latest exchange rates for all supported currencies relative to a base currency.
- getPairConversion. Exchange rate between two specific currencies.
- getPairConversionWithAmount. Converts a specified amount between two currencies.
- getHistoricalRates. Rates for a specific date (Pro, Business, or Volume plans).
- getHistoricalConversion. Converts an amount using historical rates (Pro, Business, or Volume plans).
- getSupportedCodes. List of supported currency codes and names.
- getLocalizationData. Currency names, symbols, regions, and flag URLs (Pro, Business, or Volume plans).
Documentation
Detailed Integration Documentation
Latest Rates Retrieval
| Action | getLatestRates |
|---|---|
| Purpose | Retrieves the latest exchange rates for all supported currencies relative to a base currency — the primary entry point for current rate data. |
| Configuration | Configure the base URL via CONNECTOR_ENV_EXCHANGERATE_BASE_URL. Register at exchangerate-api.com to obtain an API key. |
| Parameters | Required: apiKey; base_code (ISO 4217, e.g. USD). |
| Output | Successful: JSON with result, time_last/next_update (unix + UTC), base_code, and a conversion_rates object (e.g. AUD: 1.4817, EUR: 0.9013). Failure: error-type unknown-code. |
| Workflow example | Execute getLatestRates with base_code=USD to display rates in a dashboard. |
Pair Conversion (rate / with amount)
| Action | getPairConversion / getPairConversionWithAmount |
|---|---|
| Purpose | Retrieves the exchange rate between two currencies, or converts a specified amount using the current rate. |
| Configuration | Configure the base URL via CONNECTOR_ENV_EXCHANGERATE_BASE_URL. Register at exchangerate-api.com to obtain an API key. |
| Parameters | Required: apiKey; base_code (e.g. EUR); target_code (e.g. GBP); amount (for the with-amount variant, e.g. 100). |
| Output | Successful: JSON with conversion_rate (e.g. 0.8412) and, for the amount variant, conversion_result (e.g. 84.12). Failure: error-type unsupported-code / invalid-request. |
| Workflow example | Execute getPairConversionWithAmount with base_code=EUR, target_code=GBP, amount=100 for invoicing. |
Historical Rates & Conversion
| Action | getHistoricalRates / getHistoricalConversion |
|---|---|
| Purpose | Retrieves rates for a specific date, or converts an amount using historical rates — for research and reporting. Requires a Pro, Business, or Volume plan. |
| Configuration | Configure the base URL via CONNECTOR_ENV_EXCHANGERATE_BASE_URL. Register at exchangerate-api.com to obtain an API key. Requires a valid Pro, Business, or Volume subscription. |
| Parameters | Required: apiKey; base_code (e.g. USD); year; month (1–12); day (1–31); amount (for the conversion variant, e.g. 4). |
| Output | Successful: JSON with year/month/day, base_code, and conversion_rates (or conversion_amounts + requested_amount). Failure: error-type no-data-available / 404. |
| Workflow example | Execute getHistoricalRates with base_code=USD, year=2015, month=2, day=22 for trend analysis. |
Supported Codes & Localization
| Action | getSupportedCodes / getLocalizationData |
|---|---|
| Purpose | Retrieves supported currency codes and names, and (Pro/Business/Volume plans) localization data — names, symbols, regions, and flag URLs. |
| Configuration | Configure the base URL via CONNECTOR_ENV_EXCHANGERATE_BASE_URL. Register at exchangerate-api.com to obtain an API key. getLocalizationData requires a Pro, Business, or Volume subscription. |
| Parameters | Required: apiKey. |
| Output | Successful: JSON with supported_codes (arrays of [code, name]) or a currencies object (name, symbol, region, flag_url). Failure: error-type invalid-request / 403. |
| Workflow example | Execute getSupportedCodes to populate a currency dropdown, and getLocalizationData to add symbols and flags. |
Example Workflow: Currency Conversion & Historical Analysis
| Retrieve codes | Use getSupportedCodes to identify target currencies (e.g. USD, EUR). |
|---|---|
| Latest rates | Execute getLatestRates with base_code=USD for a financial dashboard. |
| Convert | Use getPairConversionWithAmount with base_code=USD, target_code=EUR, amount=100. |
| Historical & localization | Use getHistoricalRates / getHistoricalConversion for trends and getLocalizationData for richer UI (Pro/Business/Volume plans). |
Use Case
The ExchangeRate Connector facilitates seamless integration with ExchangeRate-API, giving access to real-time and historical exchange-rate data for 160+ currencies. Acting as a proxy, it streamlines retrieval of latest rates, pair conversions, historical data, supported currency codes, and localization data — powering currency converters, financial dashboards, and multi-currency invoicing on GCP.
Support
For technical support, contact custom-connectors-support@isolutions.sa.