API Access Key & Authentication

After signing up, every user is assigned a personal API access key, a unique combination of letters and digits that provides access to 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 Request

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:

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:

Supported Currencies           

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:                                                                          Available on: All plans

The currencylayer API offers up to 5 customizable endpoints, all of which provide 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

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

Important: The request URLs have been shortened for simplicity purposes. Please do not forget to append your API access key when making API requests.

256-bit HTTPS Encryption

All 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:                                                                         Available on: All Plans

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.

Common API Errors:

JSONP Callbacks

The currencylayer API also supports JSONP Callbacks. To use this feature, simply attach:

to any API endpoint, and the result set will be returned as the callback function you specified.

Example API Request:                                                                                                          

Example API Response:

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 a typically JSON-structured format.

To enable this function, simply attach format=1 to any valid API endpoint URL:

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 file size of the API response, which may have a negative impact on your application's performance.

HTTP ETags

To reduce your request bandwidth, the Currencylayer API provides built-in support for HTTP ETags. These may be very useful in 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 remains unchanged.

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:

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:

Step 3:
Now, what happens next depends on whether or not the rates have changed 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.2 KB 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 usual - via the API's live endpoint.