Documentation | currencylayer API

currencylayer API

Currencylayer 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 currencylayer 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 currencylayer 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 currencylayer API:

Sign Up to Run API Requesthttps://api.currencylayer.com/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://currencylayer.com/terms",
    "privacy": "https://currencylayer.com/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:

currencylayer 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 currencylayer Terms & Conditions.
`privacy`	Returns a link to the currencylayer 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 currencylayer API's list endpoint:

Example API Request:

Sign Up to Run API Requesthttps://api.currencylayer.com/list
    ? access_key = YOUR_ACCESS_KEY

Example API Response:

{
    "success": true,
    "terms": "https://currencylayer.com/terms",
    "privacy": "https://currencylayer.com/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 currencylayer Terms & Conditions.
`privacy`	Returns a link to the currencylayer Privacy Policy.
`currencies`	Returns all currencies supported by the currencylayer API.

API Endpoints

The currencylayer 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.currencylayer.com/

Available Endpoints: Take a look at the following API endpoints:

// "live" - get the most recent exchange rate data
https://api.currencylayer.com/live

// "historical" - get historical rates for a specific day  
https://api.currencylayer.com/historical?date=YYYY-MM-DD

// "convert" - convert one currency to another  
https://api.currencylayer.com/convert?from=EUR&to=GBP&amount=100

// "timeframe" - request exchange rates for a specific period of time 
https://api.currencylayer.com/timeframe?start_date=2015-01-01&end_date=2015-05-01

// "change" - request any currency's change parameters (margin, percentage) 
https://api.currencylayer.com/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 currencylayer 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.currencylayer.com/live?access_key=YOUR_ACCESS_KEY

API Error Codes

If your query fails, the currencylayer 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 currencylayer 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.currencylayer.com/live
    ? access_key = YOUR_ACCESS_KEY
    & callback = CALLBACK_FUNCTION

Example API Response:

CALLBACK_FUNCTION ({
    "success": true,
    "terms": "https://currencylayer.com/terms",
    "privacy": "https://currencylayer.com/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 currencylayer 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.currencylayer.com/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.

HTTP ETags

In order to reduce your request bandwidth, the currencylayer API has built in support for HTTP ETags. These may be very useful optimizing the performance of your application.

Definition:

An Etag ("Entity Tag") is an HTTP response header used to determine whether the content stored in the browser cache still matches the content or entity on the server. As long as the content at that URL is not modified in any way, the Etag remains identical. If that content ever changes, a new and different ETag is assigned.

In our case, ETags allow you to check whether or not exchange rates have changed since your last API request. If the rates have not been modified, your API response will be considerably smaller in size than if they have. Practically, ETags provide a mechanism to cache exchange rate data as long as it is not updated.

HTTP ETags - A Quickstart Guide

Step 1:
Making a request to the currencylayer API will create both an ETag and a Date entry. The ETag works like a fingerprint for the specific result set returned by the API. The Date represents the time at which this data was last modified. Find below examples for both of these properties:

ETag: "1872ade88f3013edeb33decd74a4f947"
Date: Fri, 10 Apr 2015 12:10:04 GMT

Now you need to cache the entire API result set, including the ETag and Date headers.

Step 2:
The next time you query the API, you need to add the If-None-Match header (containing the ETag value of your previous API request). You also need to include the If-Modified-Since header (containing the Date value of your previous successful API request).

Find below an example of the described headers:

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

Step 3:
Now, what happens next depends on whether or not the rates have changes since your last request:

304 – Not Modified will be returned if the data has not changed. In this case, the API response will only be around 0.2kb in size. (the whole idea of ETags is to save bandwidth)
If the data has changed since your last request, the most up-to-date rates will be returned - as ususal - via the API's live endpoint.

API Features

Real-time Rates Available on: All plans

Both free and paid users may access real-time exchange rates using the currencylayer 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.currencylayer.com/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://currencylayer.com/terms",
    "privacy": "https://currencylayer.com/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 currencylayer Terms & Conditions.
`privacy`	Returns a link to the currencylayer 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 currencylayer 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.currencylayer.com/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://currencylayer.com/terms",
    "privacy": "https://currencylayer.com/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.currencylayer.com/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://currencylayer.com/terms",
    "privacy": "https://currencylayer.com/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 live endpoint results in a file size of slightly over 4KB. Limiting the query to only 6 specific currencies, the response size drops to less than 600B. The illustrated margin is even more significant when wotking with Time-Frame Queries.

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.currencylayer.com/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://currencylayer.com/terms",
    "privacy": "https://currencylayer.com/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 currencylayer 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.currencylayer.com/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://currencylayer.com/terms",
    "privacy": "https://currencylayer.com/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 currencylayer Terms & Conditions.
`privacy`	Returns a link to the currencylayer 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 currencylayer 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.currencylayer.com/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 date you specified.

{
    "success": true,
    "terms": "https://currencylayer.com/terms",
    "privacy": "https://currencylayer.com/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 currencylayer Terms & Conditions.
`privacy`	Returns a link to the currencylayer 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.currencylayer.com/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://currencylayer.com/terms",
    "privacy": "https://currencylayer.com/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 currencylayer Terms & Conditions.
`privacy`	Returns a link to the currencylayer 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 currencylayer 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.currencylayer.com/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://currencylayer.com/terms",
    "privacy": "https://currencylayer.com/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 currencylayer Terms & Conditions.
`privacy`	Returns a link to the currencylayer 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.currencylayer.com/'.$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.currencylayer.com/'.$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.currencylayer.com/' + 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.currencylayer.com/' + 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 Entire Code (Github)

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 currencylayer 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.currencylayer.com/";
    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)

The entire Java demo source code, along with all necessary components, is available for download at our GitHub Repository.

Downloads

HTML Select-Option Menu Download

Get a full list of all supported currencies wrapped in HTML <select><option> tags:

<select name='currencies'>
    <option value='AED' title='United Arab Emirates Dirham'>AED</option>
    <option value='AFN' title='Afghan Afghani'>AFN</option>
    <option value='ALL' title='Albanian Lek'>ALL</option>
    <option value='AMD' title='Armenian Dram'>AMD</option>
    <option value='ANG' title='Netherlands Antillean Guilder'>ANG</option>
    [...]
</select>

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.0017988	2000	$18.59
Pro Plus	$59.99	100,000	0.00071988	20,000	$74.39
Business Plus	$99.99	500,000	0.00023997	100,000	$123.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!

Upgrade now

3-Step Quickstart Guide

Code Examples

currencylayer API

Specs & Overview

API Access Key & Authentication

API Response

Supported Currencies Available on: All plans

API Endpoints

256-bit HTTPS Encryption Available on: Basic Plan and higher

API Error Codes

JSONP Callbacks

JSON Formatting

HTTP ETags

API Features

Real-time Rates Available on: All plans

Historical Rates Available on: All plans

Specify Output Currencies Available on: All plans

Source Currency Switching Available on: Basic Plan and higher

Currency Conversion Endpoint Available on: Basic Plan and higher

Historical Currency Conversion Available on: Basic Plan and higher

Time-Frame Queries Available on: Professional Plan and higher

Currency-Change Queries Available on: Business Plan and higher

Code Examples

PHP (CURL)

JavaScript (jQuery.ajax)

Java Entire Code (Github)

Downloads

HTML Select-Option Menu Download

HTML Currencies Table Download

Business Continuity - API Overages

What is an overage?

Why does APILayer have overage fees?

How do I know if I will be charged for overages?

How will I be charged for my API subscription?

What happens if I don’t have any overage fees?

What if I consistently have more API calls than my plan allows?

I would like to upgrade my plan. How can I do that?

Introducing Platinum Support - Enterprise-grade support for APILayer

What does Platinum Support include?