Exchange Rates API

With over 15 exchange rate data sources, the Exchangerates API is delivering exchanging rates data for more than 170 world currencies. This API has several endpoints, where each of them serves a different purpose, use case. The endpoints include functionalities like receiving the latest exchange rates information for a specific set, or for all currencies; conversion from one to another currency; receiving data Time-series for multiple or for one currency, and preserving the API daily for the fluctuation data.

In this document, you will find out about the API structure, the methods, and the potential errors and code examples. If you still have questions and doubts, please do not hesitate to contact us, our team will do their best to help you.

API Key

The API has a unique identifier as an API key that gets passed into the API as an URL parameter access_key. This parameter serves as a unique identifying authentication with the Exchangerates API.

Base URL:

https://api.exchangeratesapi.io/v1/

Append your API Key: See an example of how to authenticate the Exchangerates API with the access_key parameter:

https://api.exchangeratesapi.io/v1/latest
    ? access_key = API_KEY

API Response

The delivered exchange rates with the API, are by default connected to the Euro. The data gets returned in a standard JSON format and easily can be reparsed in any programming language.

Example Response: See below an example of an API response that provides information about several world currencies that are commonly used, all in connection with the Euro currency and time-stamped with time information of the collected information.

{
    "success": true,
    "timestamp": 1519296206,
    "base": "EUR",
    "date": "2021-03-17",
    "rates": {
        "AUD": 1.566015,
        "CAD": 1.560132,
        "CHF": 1.154727,
        "CNY": 7.827874,
        "GBP": 0.882047,
        "JPY": 132.360679,
        "USD": 1.23396,
    [...]
    }
}

As we can see from the example above, when it is queried for exchange rates in real-time, the API response always contains a timestamp object which is a standard UNIX timestamp that shows the time when the provided exchange rate information was collected. Also, we have a base object which contains the short currency code of the currency, have an object which contains the date when the given exchange rate information was collected, and rates object that contains the exchange rate data.

Below, in the Endpoints section, we will discuss the API response structure more in detail.

Available Endpoints

The API comes with a number of endpoints where each of them provides different functionality. Please have in mind that depending on your subscribed plan, some endpoints will be available and some may not be available.

• Endpoint for latest rates:This endpoint returns exchange rate data in real-time for all available currencies or for a specific set.
• Endpoint for conversion:With this endpoint, we have any amount conversion from one currency to another.
• Endpoint for historical rates:Endpoint for receiving historical exchange rate information for all available currencies or for a set of currencies.
• Endpoint for Time-Series Data:It returns the daily historical data for exchange rates, between two specified dates. The data can be returned for all available currency or for specified ones.
• Endpoint for fluctuation data:This endpoint returns the fluctuation data between specified dates. The data can be for all available currencies or for a specific set.

SSL Connection

Every paid subscription plan on Exchangerates.io is with 256-bit SSL encryption. Simply use the https protocol instead of http in order to connect to the API through SSL.

JSONP Callbacks

The JSONP Callbacks is a feature included in the Exchangerates API. With this feature, you can specify the function name and send it into the API’s callback GET parameter and make the API respond to your request with the API response wrapped in that function.

Example Call:

https://api.exchangeratesapi.io/v1/latest
    ? access_key = API_KEY
    & callback = MY_FUNCTION

From the above example, we can see a request from the API to use the callback function MY_FUNCTION.

Example Response: Your API response will be wrapped inside your preferred callback function.

({
    "success": true,
    "timestamp": 1519296206,
    "base": "EUR",
    "date": "2021-03-17",
    "rates": {
        "AUD": 1.566015,
        "CAD": 1.560132,
        "CHF": 1.154727,
        "CNY": 7.827874,
        "GBP": 0.882047,
        "JPY": 132.360679,
        "USD": 1.23396,
    [...]
    }
})

Access-Control / CORS

Cross-Origin Resource Sharing (CORS) and Access-Control Headers are also supported into the Exchangerates API. This gives you the possibility to use the Exchangerates API via Cross-Origin HTTP Requests.

Learn more about CORS »

HTTP ETags

You can request new Exchangerates API data only in cases if there are changes into the rates data since your last API response, this can be done with HTTP ETags.

What are ETags?

An ETag is a part of the HTTP protocol and one of the several mechanisms used for cache validation. The ETag is an identifier assigned to a data resource in a server, and if that resource is ever updated at the server, the ETag is changed.

Whenever a resource is requested (via its URL), the data and ETag are retrieved and stored in the Web cache, and the ETag is sent along with subsequent requests. If the ETag at the server has not changed, a "Not Modified" message is returned, and the cached data is used. (Definition by pcmag.com)

ETags - Quickstart Guide

The primary request sent to Exchangerates API will create an ETag object that will contain a unique ETag key and a Date object containing the exact date and time at which the data was last modified. This data, along with the entire API response, must be cached in order for ETags to work.

ETag: "202567a75aef2e66a3ebf2366bff048f"
Date: Mon, 12 Apr 2018 11:30:01 GMT

When you will make another API request, be sure to include the If-None-Match HTTP header abd set ut to your previously generated ETag value. Moreover, you will need to add the If-Modified-Since HTTP header to your API request containing the date and time data from your last request.

If-None-Match: "1872ade88f3013edeb33decd74a4f947"
If-Modified-Since: Fri, 10 Apr 2015 12:10:04 GMT

Based on if your result set has updated or not, since your last API request, the API will return:

• same results as your initial API request along with a 304 – Not Modified HTTP header which indicates that no change has happened. In this case, the size of the API response will be very small 0.2kb;
• or new results containing a completely new set of ETag and Date objects that will indicate that new data has been accessed. In this case, the size of your API response will be normal.

Potential Errors

When we send API requests but the requested data is not available or the API call fails for some reason, a JSON error is returned. Errors always come together with an error code and a description.

Example Error: The following error is returned if your monthly API request volume has been exceeded.

{
  "success": false,
  "error": {
    "code": 104,
    "info": "Your monthly API request volume has been reached. Please upgrade your plan."
  }
}

Other Errors:

Endpoints

Supported Symbols Endpoint

The API comes with an updated endpoint that returns all of the available currencies. To receive the list, make an API request to the symbols endpoint.

API Request:

https://api.exchangeratesapi.io/v1/symbols
    ? access_key = API_KEY

Request Parameters:

API Response:

{
  "success": true,
  "symbols": {
    "AED": "United Arab Emirates Dirham",
    "AFN": "Afghan Afghani",
    "ALL": "Albanian Lek",
    "AMD": "Armenian Dram",
    [...]
    }
}

Response Objects:

Latest Rates Endpoint

This endpoint, depending on your subscription plan will return real-time exchange rate data which gets updated every 60 minutes, every 10 minutes, or every 60 seconds.

API Request:

https://api.exchangeratesapi.io/v1/latest
    ? access_key = API_KEY
    & base = USD
    & symbols = GBP,JPY,EUR

Request Parameters:

API Response:

{
    "success": true,
    "timestamp": 1519296206,
    "base": "USD",
    "date": "2021-03-17",
    "rates": {
        "GBP": 0.72007,
        "JPY": 107.346001,
        "EUR": 0.813399,
    }
}

Response Objects:

Historical Rates Endpoint

With this endpoint we have the possibility to see historical rates of the currencies back to 1999, most of the currencies data are available until 1999. You can query the Exchangerates API for historical rates by appending a date (format YYYY-MM-DD) to the base URL.

API Request:

https://api.exchangeratesapi.io/v1/2013-12-24
    ? access_key = API_KEY
    & base = GBP
    & symbols = USD,CAD,EUR

Request Parameters:

API Response:

{
    "success": true,
    "historical": true,
    "date": "2013-12-24",
    "timestamp": 1387929599,
    "base": "GBP",
    "rates": {
        "USD": 1.636492,
        "EUR": 1.196476,
        "CAD": 1.739516
    }
}

Response Objects:

Specify Symbols

In order to have reduced bandwidth, you can limit the number of output currencies to a specific set of your choice on most API endpoints. To do this, simply append the Exchangerates API's symbols parameter to your API request and set it to one or more comma-separated currency codes.

Example:

https://api.exchangeratesapi.io/v1/latest
    ? access_key = API_KEY
    & symbols = USD,CAD,JPY

The API's response for the request above will be limited to the currencies USD, CAD and JPY.

Changing base currency

Provided changing base currency is supported on your subscription plan, you can change the currency to which your output currency rates are relative to by appending the base parameter to your API request URL and setting it to the three-letter code of your preferred base currency.

Example:

https://api.exchangeratesapi.io/v1/latest
    ? access_key = API_KEY
    & base = USD

Please note: The default base currency is EUR.

Convert Endpoint

This is a separate endpoint for currency conversion that comes with the Exchangerates API and can be used to convert an amount from one currency to another. Please use this API endpoint for the conversion of any currency.

It is also possible to convert currencies using historical exchange rate data. To do this, please also use the API's date parameter and set it to your preferred date. (format YYYY-MM-DD).

API Request:

https://api.exchangeratesapi.io/v1/convert
    ? access_key = API_KEY
    & from = GBP
    & to = JPY
    & amount = 25

Request Parameters:

API Response:

{
    "success": true,
    "query": {
        "from": "GBP",
        "to": "JPY",
        "amount": 25
    },
    "info": {
        "timestamp": 1519328414,
        "rate": 148.972231
    },
    "historical": ""
    "date": "2018-02-22"
    "result": 3724.305775
}

Response Objects:

Time-Series Endpoint

If supported by your subscription plan, the Exchangerates API's time series endpoint lets you query the API for daily historical rates between two dates of your choice, with a maximum time frame of 365 days.

API Request:

https://api.exchangeratesapi.io/v1/timeseries
    ? access_key = API_KEY
    & start_date = 2012-05-01
    & end_date = 2012-05-25

Request Parameters:

API Response:

{
    "success": true,
    "timeseries": true,
    "start_date": "2012-05-01",
    "end_date": "2012-05-03",
    "base": "EUR",
    "rates": {
        "2012-05-01":{
          "USD": 1.322891,
          "AUD": 1.278047,
          "CAD": 1.302303
        },
        "2012-05-02": {
          "USD": 1.315066,
          "AUD": 1.274202,
          "CAD": 1.299083
        },
        "2012-05-03": {
          "USD": 1.314491,
          "AUD": 1.280135,
          "CAD": 1.296868
        },
        [...]
    }
}

Response Objects:

Fluctuation Endpoint

With the fluctuation API endpoint, you can receive information about the currency’s fluctuation on a day-to-day basis. To be able to use this feature, add the start_date and end_date and select which currencies (symbols) you would like to receive info for from the API. Please note that the maximum allowed timeframe is 365 days.

API Request:

https://api.exchangeratesapi.io/v1/fluctuation
    ? access_key = API_KEY
    & start_date = 2015-12-01
    & end_date = 2015-12-24

Request Parameters:

API Response:

{
    "success":true,
    "fluctuation":true,
    "start_date":"2018-02-25",
    "end_date":"2018-02-26",
    "base":"EUR",
    "rates":{
        "USD":{
            "start_rate":1.228952,
            "end_rate":1.232735,
            "change":0.0038,
            "change_pct":0.3078
        },
        "JPY":{
            "start_rate":131.587611,
            "end_rate":131.651142,
            "change":0.0635,
            "change_pct":0.0483
        },
        [...]
    }
}

Response Objects:

Sample Code

PHP (cURL)

Real-time rates: Find below a simple PHP example for getting exchange rate data via the Exchangerates API's latest endpoint.

// set API Endpoint and API key
$endpoint = 'latest';
$access_key = 'API_KEY';

// Initialize CURL:
$ch = curl_init('https://api.exchangeratesapi.io/v1/'.$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['rates']['GBP'];

Convert currencies: Here is how to convert currencies using PHP cURL.

// set API Endpoint, access key, required parameters
$endpoint = 'convert';
$access_key = 'API_KEY';

$from = 'USD';
$to = 'EUR';
$amount = 10;

// initialize CURL:
$ch = curl_init('https://api.exchangeratesapi.io/v1/'.$endpoint.'?access_key='.$access_key.'&from='.$from.'&to='.$to.'&amount='.$amount.'');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

// get the 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)

Real-time rates: Find below a simple jQuery.ajax example for getting exchange rate data via the Exchangerates API's latest endpoint.

// set endpoint and your access key
endpoint = 'latest'
access_key = 'API_KEY';

// get the most recent exchange rates via the "latest" endpoint:
$.ajax({
    url: 'https://api.exchangeratesapi.io/v1/' + endpoint + '?access_key=' + access_key,
    dataType: 'jsonp',
    success: function(json) {

        // exchange rata data is stored in json.rates
        alert(json.rates.GBP);

        // base currency is stored in json.base
        alert(json.base);

        // timestamp can be accessed in json.timestamp
        alert(json.timestamp);

    }
});

Convert currencies: Here is how to convert currencies using jQuery.ajax.

// set endpoint and your API key
endpoint = 'convert';
access_key = 'API_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.exchangeratesapi.io/v1/' + 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);

    }
});

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.

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!