exchangerate API
exchangerate provides a simple REST API with real-time and historical exchange rates for 168 world currencies, delivering currency pairs in universally usable JSON format - compatible with any of your applications.
Spot exchange rate data is retrieved from several major forex data providers in real-time, validated, processed and delivered hourly, every 10 minutes, or even within the 60-second market window.
Providing the most representative forex market value available ("midpoint" value) for every API request, the exchangerate API powers currency converters, mobile applications, financial software components and back-office systems all around the world.
Specs & Overview
API Access Key & Authentication
After signing up, every user is assigned a personal API access key, a unique combination of letters and digits provided to access any of the API's data endpoints. To authenticate with the exchangerate API, simply attach your access_key
to your preferred endpoint URL:
Append your API Access Key: Here is an example API call illustrating how to authenticate with the exchangerate API:
Sign Up to Run API Requesthttps://api.exchangerate.host/live ? access_key = YOUR_ACCESS_KEY
API Response
The standard API response is an easily parseable, lightweight JSON file consisting of different objects and properties. The response will be explained in detail below.
Example API Response:
{ "success": true, "terms": "https://exchangerate.host/terms", "privacy": "https://exchangerate.host/privacy", "timestamp": 1430401802, "source": "USD", "quotes": { "USDAED": 3.672982, "USDAFN": 57.8936, "USDALL": 126.1652, "USDAMD": 475.306, "USDANG": 1.78952, "USDAOA": 109.216875, "USDARS": 8.901966, "USDAUD": 1.269072, "USDAWG": 1.792375, "USDAZN": 1.04945, "USDBAM": 1.757305, [...] } }
Along with the source
currency, a timestamp
and some legal reminders, the API will return a quotes
object containing all available or specified currency pairs with their respective exchange rate values (quotes).
API Response Properties:
exchangerate API results are delivered in JSON format for maximum usability. Find below descriptions for the JSON properties returned by the API:
Property | Description |
---|---|
success |
Returns true or false depending on whether or not your query succeeds. |
terms |
Returns a link to the exchangerate Terms & Conditions. |
privacy |
Returns a link to the exchangerate Privacy Policy. |
timestamp |
Returns the exact date and time (UNIX) the exchange rates were collected. |
source |
Returns the currency to which all exchange rates are relative. (default: USD ) |
quotes |
Contains all exchange rate values, consisting of the currency pairs and their respective conversion rates. |
Supported Currencies Available on: All plans
A full list of supported currencies can be accessed both in JSON Format (access key required) and on this website.
In order to access a JSON file containing all currently supported currencies (3-letter currency code and full currency name), simply attach your access_key
to the exchangerate API's list endpoint:
Example API Request:
Sign Up to Run API Requesthttps://api.exchangerate.host/list ? access_key = YOUR_ACCESS_KEY
Example API Response:
{ "success": true, "terms": "https://exchangerate.host/terms", "privacy": "https://exchangerate.host/privacy", "currencies": { "AED": "United Arab Emirates Dirham", "AFN": "Afghan Afghani", "ALL": "Albanian Lek", "AMD": "Armenian Dram", "ANG": "Netherlands Antillean Guilder", [...] } }
API Response Properties:
Property | Description |
---|---|
success |
Returns true or false depending on whether or not your query succeeds. |
terms |
Returns a link to the exchangerate Terms & Conditions. |
privacy |
Returns a link to the exchangerate Privacy Policy. |
currencies |
Returns all currencies supported by the exchangerate API. |
API Endpoints
The exchangerate API offers up to 5 customizable endpoints, all of which providing different kinds of data. Below you will find a short summary of all available endpoints. They will be explained in detail throughout the API Features section.
Base URL: All API requests start out with the following base URL:
https://api.exchangerate.host/
Available Endpoints: Take a look at the following API endpoints:
// "live" - get the most recent exchange rate data https://api.exchangerate.host/live // "historical" - get historical rates for a specific day https://api.exchangerate.host/historical?date=YYYY-MM-DD // "convert" - convert one currency to another https://api.exchangerate.host/convert?from=EUR&to=GBP&amount=100 // "timeframe" - request exchange rates for a specific period of time https://api.exchangerate.host/timeframe?start_date=2015-01-01&end_date=2015-05-01 // "change" - request any currency's change parameters (margin, percentage) https://api.exchangerate.host/change?currencies=USD,EUR
Important: The request URLs have been shortened for simplicity purposes. Please do not forget appending your API access key when making API requests.
256-bit HTTPS Encryption Available on: Basic Plan and higher
Paid Customers may establish a secure connection (industry-standard SSL) to the exchangerate API and all data provided by and accessible through it.
To connect securely, simply attach an s
to the HTTP Protocol. (resulting in https://
)
Example API Request:
https://api.exchangerate.host/live?access_key=YOUR_ACCESS_KEY
API Error Codes
If your query fails, the exchangerate API will return a 3-digit error-code and a plain text "info" property containing suggestions for the user.
Example Error: Find below an example error, triggered when a user's monthly API request volume has been reached or exceeded.
{ "success": false, "error": { "code": 104, "info": "Your monthly usage limit has been reached. Please upgrade your subscription plan." } }
Common API Errors:
Code | Info [affected API endpoints] |
---|---|
404 |
User requested a resource which does not exist. |
101 |
User did not supply an access key or supplied an invalid access key. |
103 |
User requested a non-existent API function. |
104 |
User has reached or exceeded his subscription plan's monthly API request allowance. |
105 |
The user's current subscription plan does not support the requested API function. |
106 |
The user's query did not return any results |
102 |
The user's account is not active. User will be prompted to get in touch with Customer Support. |
201 |
User entered an invalid Source Currency. |
202 |
User entered one or more invalid currency codes. |
301 |
User did not specify a date. [historical ] |
302 |
User entered an invalid date. [historical , convert ] |
401 |
User entered an invalid "from" property. [convert ] |
402 |
User entered an invalid "to" property. [convert ] |
403 |
User entered no or an invalid "amount" property. [convert ] |
501 |
User did not specify a Time-Frame. [timeframe , convert]. |
502 |
User entered an invalid "start_date" property. [timeframe , convert]. |
503 |
User entered an invalid "end_date" property. [timeframe , convert]. |
504 |
User entered an invalid Time-Frame. [timeframe , convert] |
505 |
The Time-Frame specified by the user is too long - exceeding 365 days. [timeframe ] |
JSONP Callbacks
The exchangerate API also supports JSONP Callbacks. To use this feature, simply attach:
callback = CALLBACK_FUNCTION
to any API endpoint, and the result set will be returned as the callback function you specified.
Example API Request:
Sign Up to Run API Requesthttps://api.exchangerate.host/live ? access_key = YOUR_ACCESS_KEY & callback = CALLBACK_FUNCTION
Example API Response:
CALLBACK_FUNCTION ({ "success": true, "terms": "https://exchangerate.host/terms", "privacy": "https://exchangerate.host/privacy", "timestamp": 1432480209, "source": "USD", "quotes": { "USDAED": 3.67315, "USDAFN": 60.790001, "USDALL": 126.194504, "USDAMD": 477.359985, "USDANG": 1.790403, [...] } })
Please note: The API also supports Access-Control (CORS) headers.
JSON Formatting
In order to enhance readability during debugging the exchangerate API features a built-in JSON format
function, which displays the API's response in typically JSON-structured format.
To enable this function, simply attach format=1
to any valid API endpoint URL:
Sign Up to Run API Requesthttps://api.exchangerate.host/live ? access_key = YOUR_ACCESS_KEY & format = 1
Important: This functionality should only be used for debugging purposes and does not necessarily produce valid JSON. Please be aware that enabling this function also increases the API response's file size, which might have a negative on your application's performance.
API Features
Real-time Rates Available on: All plans
Both free and paid users may access real-time exchange rates using the exchangerate API's live endpoint.
Optionally, it is possible to define an additional source
currency and specific output currencies using the currencies
parameter. Both of these options will be discussed in detail throughout this documentation.
Example API Request:
Sign Up to Run API Requesthttps://api.exchangerate.host/live ? access_key = YOUR_ACCESS_KEY & currencies = AUD,EUR,GBP,PLN
Request Parameters:
Object | Description |
---|---|
access_key |
[Required] Your API Access Key. |
source |
[optional] Specify a Source Currency other than the default USD. Supported on the Basic Plan and higher. |
currencies |
[optional] Specify a comma-separated list of currency codes to limit your API response to specific currencies. |
Example API Response:
Inside the quotes
object, the API will now return the latest available exchange rates for the currencies
specified in the currencies parameter (USD, AUD, EUR and PLN), all relative to the default source
currency USD (US Dollars).
{ "success": true, "terms": "https://exchangerate.host/terms", "privacy": "https://exchangerate.host/privacy", "timestamp": 1432400348, "source": "USD", "quotes": { "USDAUD": 1.278342, "USDEUR": 1.278342, "USDGBP": 0.908019, "USDPLN": 3.731504 } }
Response Properties:
Property | Description |
---|---|
success |
Returns true or false depending on whether or not your query succeeds. |
terms |
Returns a link to the exchangerate Terms & Conditions. |
privacy |
Returns a link to the exchangerate Privacy Policy. |
timestamp |
Returns the exact date and time (UNIX) the exchange rates were collected. |
source |
Returns the currency to which all exchange rates are relative. (default: USD ) |
quotes |
Contains all exchange rate values, consisting of the currency pairs and their respective conversion rates. |
Exchange rate data is refreshed every 60 minutes for Free & Basic customers, every 10 minutes for the Professional Plan, and every 60 seconds for Business customers.
Historical Rates Available on: All plans
The exchangerate API provides accurate historical exchange rate data for every past day all the way back to the year of 1999.
Historical rates may be accessed by simply attaching the date
parameter with a valid date (Format: YYYY-MM-DD
) to the API's historical
endpoint.
Example API Request:
Sign Up to Run API Requesthttps://api.exchangerate.host/historical ? access_key = YOUR_ACCESS_KEY & date = 2005-02-01
Request Parameters:
Parameter | Description |
---|---|
access_key |
[Required] Your API Access Key. |
date |
[Required] Specify a date for which to request historical rates. (Format: YYYY-MM-DD ) |
source |
[optional] Specify a Source Currency other than the default USD. Supported on the Basic Plan and higher. |
currencies |
[optional] Specify a comma-separated list of currency codes to limit your API response to specific currencies. |
Example API Response:
Inside the quotes
object, the API will now return all available exchange rates for your specified date.
{ "success": true, "terms": "https://exchangerate.host/terms", "privacy": "https://exchangerate.host/privacy", "historical": true, "date": "2005-02-01", "timestamp": 1107302399, "source": "USD", "quotes": { "USDAED": 3.67266, "USDALL": 96.848753, "USDAMD": 475.798297, "USDANG": 1.790403, "USDARS": 2.918969, "USDAUD": 1.293878, [...] } }
Please be aware that Exchange Rate data for certain currencies may not be available for each requested day (e.g. Bitcoin was only introduced in 2009).
Specify Output Currencies Available on: All plans
For both live and historical rates, you may limit your API request to a set of specific currencies by attaching the currencies
parameter followed by any available 3-letter currency codes (divided by commas) of your choice.
Example API Request:
Sign Up to Run API Requesthttps://api.exchangerate.host/live ? access_key = YOUR_ACCESS_KEY & currencies = AUD,CHF,EUR,GBP,PLN
The currencies
parameter is supported by each of the API's endpoints (except for the Currency Conversion Endpoint) and has no limits in size.
Example API Response:
Find below an API response containing only five specified output currencies. (AUD, CHF, EUR, GBP and PLN)
{ "success": true, "terms": "https://exchangerate.host/terms", "privacy": "https://exchangerate.host/privacy", "timestamp": 1430068515, "source": "USD", "quotes": { "USDAUD": 1.278384, "USDCHF": 0.953975, "USDEUR": 0.919677, "USDGBP": 0.658443, "USDPLN": 3.713873 } }
Why the use of this feature is highly recommended:
Limiting your API request to only the currencies you really need can reduce the API response's file size by a factor of 10x to 20x, which may have a substantial effect on the performance of your application.
Numbers speak for themselves: Requesting quotes for all 168 currencies from the API's
Source Currency Switching Available on: Basic Plan and higher
Definition: Source Currency
The Source Currency (often also referred to as "base currency") is the currency to which all quote values in an API result set are relative (default value: USD
). The Source Currency can be found in the API response's source
object. It is also the first 3-letter currency code of a returned currency pair. (e.g. USDEUR
, where USD
is the Source Currency)
Source Currency Switching
As a paid customer, you may request exchange rates relative to a different Source Currency than US Dollars, simply by attaching the source
parameter followed by the 3-letter currency code of your choice.
Example API Request:
Sign Up to Run API Requesthttps://api.exchangerate.host/live ? access_key = YOUR_ACCESS_KEY & source = GBP
The source
parameter is supported by each of the API's endpoints (except for the Currency Conversion Endpoint) and has no limits in size.
Example API Response:
Using this query all quote values will be returned relative to the Source Currency you specified (in our example: GBP
). The Source Currency can be found both in the result set's source
object and in the listed currency pairs themselves. (the first 3-letter code of each pair represents the Source Currency)
{ "success": true, "terms": "https://exchangerate.host/terms", "privacy": "https://exchangerate.host/privacy", "timestamp": 1430068515, "source": "USD", "quotes": { "USDAUD": 1.278384, "USDCHF": 0.953975, "USDEUR": 0.919677, "USDGBP": 0.658443, "USDPLN": 3.713873 } }
Please note that only currencies that are part of the respective result set can be set as source currency.
Currency Conversion Endpoint Available on: Basic Plan and higher
Using the convert
endpoint, you may request the exchangerate API to perform a Single currency conversion on your behalf.
To use this endpoint, simply specify a from
currency code, a to
Currency Code, and the amount
you would like to convert.
Example API Request:
Sign Up to Run API Requesthttps://api.exchangerate.host/convert ? access_key = YOUR_ACCESS_KEY & from = USD & to = GBP & amount = 10
Request Parameters:
Parameter | Description |
---|---|
access_key |
[Required] Your API Access Key. |
from |
[Required] Specify the currency to convert from. |
to |
[Required] Specify the currency to convert to. |
amount |
[Required] Specify the amount to convert. |
date |
[optional] Specify a date to use historical rates for this conversion. (Format: YYYY-MM-DD ) |
Example API Response:
A conversion API response contains more information than standard result sets. Your requested query
is returned in the query object. It contains the specified from
, to
, and amount
properties. Additionally, the API will return an info
object, which indicates how up-to-date the used exchange rates are (timestamp
) and at which conversion rate (rate
) your specified amount was converted.
At the end of the response, there will be a result
property containing your successfully converted amount.
{ "success": true, "terms": "https://exchangerate.host/terms", "privacy": "https://exchangerate.host/privacy", "query": { "from": "USD", "to": "GBP", "amount": 10 }, "info": { "timestamp": 1430068515, "quote": 0.658443 }, "result": 6.58443 }
API Response Properties:
Property | Description |
---|---|
success |
Returns true or false depending on whether or not your query succeeds. |
terms |
Returns a link to the exchangerate Terms & Conditions. |
privacy |
Returns a link to the exchangerate Privacy Policy. |
query > from |
Returns the currency the given amount is converted from. |
query > to |
Returns the currency the given amount is converted to. |
query > amount |
Returns the conversion amount. |
info > timestamp |
Returns the exact date and time (UNIX) the exchange rate was collected. |
info > quote |
Returns the exchange rate used for the conversion. |
result |
Returns your conversion result. |
Historical Currency Conversion Available on: Basic Plan and higher
The exchangerate API also supports currency conversions using historical exchange rates. Simply attach an additional date
property with a valid date (Format: YYYY-MM-DD
) to your query.
Example API Request:
Sign Up to Run API Requesthttps://api.exchangerate.host/convert ? access_key = YOUR_ACCESS_KEY & from = USD & to = GBP & amount = 10 & date = 2005-01-01
Request Parameters:
Parameter | Description |
---|---|
access_key |
[Required] Your API Access Key. |
from |
[Required] Specify the currency to convert from. |
to |
[Required] Specify the currency to convert to. |
amount |
[Required] Specify the amount to convert. |
date |
[Required] Specify the date to use for your conversion. (Format: YYYY-MM-DD ) |
Example API Response:
The API response for historical currency conversion is nearly identical to a standard currency conversion response. In addition to the properties returned for standard currency conversion requests, the API will return "historical":true
to confirm your request, and the
{ "success": true, "terms": "https://exchangerate.host/terms", "privacy": "https://exchangerate.host/privacy", "query": { "from": "USD", "to": "GBP", "amount": 10 }, "info": { "timestamp": 1104623999, "quote": 0.51961 }, "historical": true, "date": "2005-01-01", "result": 5.1961 }
API Response Properties:
Property | Description |
---|---|
success |
Returns true or false depending on whether or not your query succeeds. |
terms |
Returns a link to the exchangerate Terms & Conditions. |
privacy |
Returns a link to the exchangerate Privacy Policy. |
query > from |
Returns the currency the given amount is converted from. |
query > to |
Returns the currency the given amount is converted to. |
query > to |
Returns the conversion amount. |
info > timestamp |
Returns the exact date and time (UNIX) the exchange rate was collected. |
info > quote |
Returns the exchange rate used for the conversion. |
historical |
Returns true to confirm your historical currency conversion request. |
date |
Returns the date specified for your historical currency conversion request. |
result |
Returns your conversion result. |
Please note that historical currency conversions can only be performed if exchange rate data for the respective currencies are available at the specified date.
Time-Frame Queries Available on: Professional Plan and higher
If your subscription plan features the timeframe
API endpoint, you may request historical exchange rates for a time-period of your choice. (maximum range: 365 days)
To use this endpoint, simply specify your preferred time frame, consisting of a start_date
and an end_date
, both of the format YYYY-MM-DD
.
Example API Request:
Sign Up to Run API Requesthttps://api.exchangerate.host/timeframe ? access_key = YOUR_ACCESS_KEY & currencies = USD,GBP,EUR & start_date = 2010-03-01 & end_date = 2010-04-01
Request Parameters:
Parameter | Description |
---|---|
access_key |
[Required] Your API Access Key. |
start_date |
[Required] Specify the start date of your time frame. |
end_date |
[Required] Specify the end date of your time frame. |
source |
[optional] Specify a Source Currency other than the default USD. Supported on the Basic Plan and higher. |
currencies |
[optional] Specify a comma-separated list of currency codes to limit your API response to specific currencies. |
Example API Response:
Along with "timeframe":true
, the start_date
, and the end_date
, the API response's quotes object will contain the specified exchange rates divided into sub-objects for each of the days within the requested time-frame.
{ "success": true, "terms": "https://exchangerate.host/terms", "privacy": "https://exchangerate.host/privacy", "timeframe": true, "start_date": "2010-03-01", "end_date": "2010-04-01", "source": "USD", "quotes": { "2010-03-01": { "USDUSD": 1, "USDGBP": 0.668525, "USDEUR": 0.738541 }, "2010-03-02": { "USDUSD": 1, "USDGBP": 0.668827, "USDEUR": 0.736145 }, [...] } }
API Response Properties:
Property | Description |
---|---|
success |
Returns true or false depending on whether or not your query succeeds. |
terms |
Returns a link to the exchangerate Terms & Conditions. |
privacy |
Returns a link to the exchangerate Privacy Policy. |
timeframe |
Returns true to confirm your request to the Time-Frame endpoint. |
start_date |
Returns the specified start date. |
end_date |
Returns the specified end date. |
source |
Returns the currency to which all exchange rates are relative. (default: USD ) |
quotes > YYYY-MM-DD |
The quotes object will contain one sub-object with exchange rate data per day in your time frame. |
Please note: Since the exchangerate API allows time-frames of up to 365 days, not limiting your query in output currencies may result in very large file sizes. For optimum performance and a lower server-load, it is highly recommended to use this feature combined with the currencies
parameter, which allows you to output a custom selection of currencies.
Currency-Change Queries Available on: Business Plan and higher
Using the API's change
endpoint, you may request the change (both margin and percentage) of one or more currencies, relative to a Source Currency, within a specific time-frame (optional).
Unlike with Time-Frame Queries, performing a Currency-Change Query does not require you to specify a time-frame. If you do not provide a time-frame, the API will automatically return the change
values ranging from yesterday's EOD (End Of Day) data, to the latest available exchange rates of today.
However, if you decide to specify a start_date
and and end_date
(both of the format YYYY-MM-DD), the API will return change
values for your preferred time-frame.
Example API Request:
Sign Up to Run API Requesthttps://api.exchangerate.host/change ? access_key = YOUR_ACCESS_KEY & currencies = USD,GBP,EUR & start_date = 2010-03-01 & end_date = 2010-04-01
Request Parameters:
Parameter | Description |
---|---|
access_key |
[Required] Your API Access Key. |
start_date |
[Required] Specify the start date of your time frame. |
end_date |
[Required] Specify the end date of your time frame. |
source |
[optional] Specify a Source Currency other than the default USD. Supported on the Basic Plan and higher. |
currencies |
[optional] Specify a comma-separated list of currency codes to limit your API response to specific currencies. |
Example API Response:
To indicate that you are performing a change query, the API will return "change":true
. Right below, your specified start_date
and end_date
will be part of the API response as well.
Just like when performing a Time-Frame Query, the API response's quotes object will be divided in sub-objects (one for each requested currency).
The four properties contained in these sub-objects are explained below in Code View:
start_rate the respective currency's exchange rate at the beginning of the specified period end_rate the respective currency's exchange rate at the end of the specified period change the margin between the currency's start_rate end_rate change_pct the currency's percentage change within the specified time-frame
This is how the complete API response will look like:
{ "success": true, "terms": "https://exchangerate.host/terms", "privacy": "https://exchangerate.host/privacy", "change": true, "start_date": "2005-01-01", "end_date": "2010-01-01", "source": "USD", "quotes": { "USDAUD": { "start_rate": 1.281236, "end_rate": 1.108609, "change": -0.1726, "change_pct": -13.4735 }, "USDEUR": { "start_rate": 0.73618, "end_rate": 0.697253, "change": -0.0389, "change_pct": -5.2877 }, "USDMXN":{ "start_rate": 11.149362, "end_rate": 13.108757, "change": 1.9594, "change_pct": 17.5741 } } }
If the decimal values contained both in the change
and in the change_pct
property are positive, the value of the respective currency increased over the course of the specified time-frame. (e.g. "change_pct": 17.5741
would be a +17.57%
increase). If the values are negative, it decreased. (e.g. "change_pct": -5.2877
would be a -5.29%
decrease)
API Response Properties:
Property | Description |
---|---|
success |
Returns true or false depending on whether or not your query succeeds. |
terms |
Returns a link to the exchangerate Terms & Conditions. |
privacy |
Returns a link to the exchangerate Privacy Policy. |
change |
Returns true to confirm your request to the Currency-Change endpoint. |
start_date |
Returns the specified start date. |
end_date |
Returns the specified end date. |
source |
Returns the currency to which all exchange rates are relative. (default: USD ) |
quotes > YYYY-MM-DD |
The quotes object will contain one sub-object with exchange rate data per day in your time frame. |
[...] > start_rate |
The respective currency's exchange rate at the beginning of the specified period. |
[...] > end_rate |
The respective currency's exchange rate at the end of the specified period. |
[...] > change |
The margin between the currency's start_rate and end_rate . |
[...] > change_pct |
The currency's percentage change within the specified time frame. |
"change": 0
If the change
and change_pct
properties equal zero, either the specified currency's exchange rate value has not changed over the course of the entire time-frame, or an exchange rate value for the respective currency on at least one of the specified dates is "unavailable".
Please note: Since foreign exchange (forex) markets are only open from Sunday 5 PM ET to Friday 5 PM ET, change parameters may converge to zero during weekends.
Code Examples
PHP (CURL)
Accessing Real-time exchange rates:
Find below an example for how to access the latest exchange rate data via PHP (CURL):
// set API Endpoint and access key (and any options of your choice) $endpoint = 'live'; $access_key = 'YOUR_ACCESS_KEY'; // Initialize CURL: $ch = curl_init('https://api.exchangerate.host/'.$endpoint.'?access_key='.$access_key.''); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Store the data: $json = curl_exec($ch); curl_close($ch); // Decode JSON response: $exchangeRates = json_decode($json, true); // Access the exchange rate values, e.g. GBP: echo $exchangeRates['quotes']['USDGBP'];
Performing a Currency Conversion:
Converting one currency to another in PHP (CURL) is as simple as:
// set API Endpoint, access key, required parameters $endpoint = 'convert'; $access_key = 'YOUR_ACCESS_KEY'; $from = 'USD'; $to = 'EUR'; $amount = 10; // initialize CURL: $ch = curl_init('https://api.exchangerate.host/'.$endpoint.'?access_key='.$access_key.'&from='.$from.'&to='.$to.'&amount='.$amount.''); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // get the (still encoded) JSON data: $json = curl_exec($ch); curl_close($ch); // Decode JSON response: $conversionResult = json_decode($json, true); // access the conversion result echo $conversionResult['result'];
JavaScript (jQuery.ajax)
Echange Rates can be easily accessed by using jQuery to make an AJAX call. Using this method is widely used and highly recommend due to ease of integration.
Accessing Real-time exchange rates:
Find below an example for how to access the latest exchange rate data via jQuery.ajax:
// set endpoint and your access key endpoint = 'live' access_key = 'YOUR_ACCESS_KEY'; // get the most recent exchange rates via the "live" endpoint: $.ajax({ url: 'https://api.exchangerate.host/' + endpoint + '?access_key=' + access_key, dataType: 'jsonp', success: function(json) { // exchange rata data is stored in json.quotes alert(json.quotes.USDGBP); // source currency is stored in json.source alert(json.source); // timestamp can be accessed in json.timestamp alert(json.timestamp); } });
Performing a Currency Conversion:
Converting one currency to another in jQuery.ajax is as simple as:
// set endpoint and your access key endpoint = 'convert'; access_key = 'YOUR_ACCESS_KEY'; // define from currency, to currency, and amount from = 'EUR'; to = 'GBP'; amount = '10'; // execute the conversion using the "convert" endpoint: $.ajax({ url: 'https://api.exchangerate.host/' + endpoint + '?access_key=' + access_key +'&from=' + from + '&to=' + to + '&amount=' + amount, dataType: 'jsonp', success: function(json) { // access the conversion result in json.result alert(json.result); } });
Java
Making use of a variety of Apache HTTP Components, there is a fairly simple way to query the API using Java. Based on the following integration methods for the API's live and convert endpoints, we will try to provide a general idea of how exchangerate JSON data can be accessed using Java.
Accessing Real-time exchange rates:
Find below an example for how to access and display the latest exchange rate data using Java:
package org.json.poc; // necessary components are imported import java.io.BufferedReader; import java.io.IOException; import java.io.InputStreamReader; import java.text.DateFormat; import java.text.SimpleDateFormat; import java.util.Date; import org.apache.http.HttpEntity; import org.apache.http.ParseException; import org.apache.http.client.ClientProtocolException; import org.apache.http.client.methods.CloseableHttpResponse; import org.apache.http.client.methods.HttpGet; import org.apache.http.impl.client.CloseableHttpClient; import org.apache.http.impl.client.HttpClients; import org.apache.http.util.EntityUtils; import org.json.JSONException; import org.json.JSONObject; public class LiveResponseDemo{ // essential URL structure is built using constants public static final String ACCESS_KEY = "YOUR_ACCESS_KEY"; public static final String BASE_URL = "http://api.exchangerate.host/"; public static final String ENDPOINT = "live"; // this object is used for executing requests to the (REST) API static CloseableHttpClient httpClient = HttpClients.createDefault(); /** * * Notes: * * A JSON response of the form {"key":"value"} is considered a simple Java JSONObject. * To get a simple value from the JSONObject, use:.get ("key"); * * A JSON response of the form {"key":{"key":"value"}} is considered a complex Java JSONObject. * To get a complex value like another JSONObject, use: .getJSONObject("key") * * Values can also be JSONArray Objects. JSONArray objects are simple, consisting of multiple JSONObject Objects. * * */ // sendLiveRequest() function is created to request and retrieve the data public static void sendLiveRequest(){ // The following line initializes the HttpGet Object with the URL in order to send a request HttpGet get = new HttpGet(BASE_URL + ENDPOINT + "?access_key=" + ACCESS_KEY); try { CloseableHttpResponse response = httpClient.execute(get); HttpEntity entity = response.getEntity(); // the following line converts the JSON Response to an equivalent Java Object JSONObject exchangeRates = new JSONObject(EntityUtils.toString(entity)); System.out.println("Live Currency Exchange Rates"); // Parsed JSON Objects are accessed according to the JSON resonse's hierarchy, output strings are built Date timeStampDate = new Date((long)(exchangeRates.getLong("timestamp")*1000)); DateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss a"); String formattedDate = dateFormat.format(timeStampDate); System.out.println("1 " + exchangeRates.getString("source") + " in GBP : " + exchangeRates.getJSONObject("quotes").getDouble("USDGBP") + " (Date: " + formattedDate + ")"); System.out.println("\n"); response.close(); } catch (ClientProtocolException e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (IOException e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (ParseException e) { // TODO Auto-generated catch block e.printStackTrace(); } catch (JSONException e) { // TODO Auto-generated catch block e.printStackTrace(); } } // sendLiveRequest() function is executed public static void main(String[] args) throws IOException{ sendLiveRequest(); httpClient.close(); new BufferedReader(new InputStreamReader(System.in)).readLine(); } }
The Java Output will look like this:
Live Currency Exchange Rates 1 USD in GBP : 0.66046 (Date: 2015-05-02 21:26:15 PM)
HTML Currencies Table Download
Download a clean HTML <table>
containing all supported currencies:
<table> <thead> <tr> <th>Code</th> <th>Name</th> </tr> </thead> <tbody> <tr> <td>AED</td> <td>United Arab Emirates Dirham</td> </tr> <tr> <td>AFN</td> <td>Afghan Afghani</td> </tr> <tr> <td>ALL</td> <td>Albanian Lek</td> </tr> <tr> <td>AMD</td> <td>Armenian Dram</td> </tr> [...] </tbody> </table>
Business Continuity - API Overages
Ensuring our customers achieve success is paramount to what we do at APILayer. For this reason, we will be rolling out our Business Continuity plan guaranteeing your end users will never see a drop in coverage. Every plan has a certain amount of API calls that you can make in the given month. However, we would never want to cut your traffic or impact user experience negatively for your website or application in case you get more traffic.
What is an overage?
An overage occurs when you go over a quota for your API plan. When you reach your API calls limit, we will charge you a small amount for each new API call so we can make sure there will be no disruption in the service we provide to you and your website or application can continue running smoothly.
Prices for additional API calls will vary based on your plan. See table below for prices per call and example of an overage billing.
Plan Name | Monthly Price | Number of Calls | Overage Price per call | Overage | Total price |
---|---|---|---|---|---|
Basic | $14.99 | 10,000 | 0.0022485 | 2,000 | $19.49 |
Professional Plus | $59.99 | 100,000 | 0.00089985 | 20,000 | $77.99 |
Business | $99.99 | 500,000 | 0.00029997 | 100,000 | $129.99 |
Why does APILayer have overage fees?
Overage fees allow developers to continue using an API once a quota limit is reached and give them time to upgrade their plan based on projected future use while ensuring API providers get paid for higher usage.
How do I know if I will be charged for overages?
When you are close to reaching your API calls limit for the month, you will receive an automatic notification (at 75%, 90% and 100% of your monthly quota). However, it is your responsibility to review and monitor for the plan’s usage limitations. You are required to keep track of your quota usage to prevent overages. You can do this by tracking the number of API calls you make and checking the dashboard for up-to-date usage statistics.
How will I be charged for my API subscription?
You will be charged for your monthly subscription plan, plus any overage fees applied. Your credit card will be billed after the billing period has ended.
What happens if I don’t have any overage fees?
In this case, there will be no change to your monthly invoice. Only billing cycles that incur overages will see any difference in monthly charges. The Business Continuity plan is an insurance plan to be used only if needed and guarantees your end users never see a drop in coverage from you.
What if I consistently have more API calls than my plan allows?
If your site consistently surpasses the set limits each month, you may face additional charges for the excess usage. Nevertheless, as your monthly usage reaches a certain threshold, it becomes more practical to consider upgrading to the next plan. By doing so, you ensure a smoother and more accommodating experience for your growing customer base.
I would like to upgrade my plan. How can I do that?
You can easily upgrade your plan by going to your Dashboard and selecting the new plan that would be more suitable for your business needs. Additionally, you may contact your Account Manager to discuss a custom plan if you expect a continuous increase in usage.
Introducing Platinum Support - Enterprise-grade support for APILayer
Upgrade your APIlayer subscription with our exclusive Platinum Support, an exceptional offering designed to enhance your business’ API management journey. With Platinum Support, you gain access to a host of premium features that take your support experience to a whole new level.
What does Platinum Support include?
Standard Support | Platinum Support | |
---|---|---|
General review on the issue | ||
Access to knowledge base articles | ||
Email support communication | ||
Regular products updates and fixes | ||
Dedicated account team | ||
Priority Email Support with unlimited communication | ||
Priority bug and review updates | ||
Option for quarterly briefing call with product Management | ||
Features requests as priority roadmap input into product |
Priority Email Support: Experience unrivaled responsiveness with our priority email support. Rest assured that your inquiries receive top-priority attention, ensuring swift resolutions to any issues.
Unlimited Communication: Communication is key, and with Platinum Support, you enjoy unlimited access to our support team. No matter how complex your challenges are, our experts are here to assist you every step of the way.
Priority Bug Review and Fixes: Bugs can be a headache, but not with Platinum Support. Benefit from accelerated bug review and fixes, minimizing disruptions and maximizing your API performance.
Dedicated Account Team: We understand the value of personalized attention. That's why Platinum Support grants you a dedicated account team, ready to cater to your specific needs and provide tailored solutions.
Quarterly Briefing Call with Product Team: Stay in the loop with the latest updates and insights from our Product team. Engage in a quarterly briefing call to discuss new features, enhancements, and upcoming developments.
Priority Roadmap Input: Your input matters! As a Platinum Support subscriber, your feature requests receive top priority, shaping our product roadmap to align with your evolving requirements.
Don't settle for the standard when you can experience the exceptional. Upgrade to Platinum Support today and supercharge your APIlayer experience!