Getting Started

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 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 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:

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:

Exchangerate 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 exchangerate API's list endpoint:

Example API Request:

Sign Up to Run API Request

Example API Response:

API Response Properties:

API Endpoints

The Exchangerate API offers up to 5 customizable endpoints, each providing different kinds of data. Below is a short summary of all available endpoints. They will be explained in detail throughout the API Features section.

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 appending your API access key when making API requests.

256-bit HTTPS Encryption

All 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:

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.

Common API Errors:

JSONP Callbacks

The Exchangerate 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:

Sign Up to Run API Request

Example API Response:

Please note: The API also supports Access-Control (CORS) headers.

JSON Formatting

To enhance readability during debugging, the Exchangerate 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:

Sign Up to Run API Request

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 Exchangerate API has built-in support for HTTP ETags. These may be very useful for 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:
Requesting the Exchangerate 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.