Getting Started

Definitions

API Key

Your API Key is the unique key that is passed into the API base URL's access_key parameter in order to authenticate with the Fixer API.

Base URL:

Append your API Key: Here is how to authenticate with the Fixer API:

Sign Up to Run API Request

API Response

Exchange rates delivered by the Fixer API are, by default, relative to EUR. All data is returned in standard JSON format and can be parsed easily using any programming language.

Example Response: Below you will find an example API response carrying a number of common world currencies, all relative to the currency EUR and time-stamped at the exact time they were collected.

As illustrated above, the API's response - when queried for real-time exchange rates - always contains a timestamp object containing a standard UNIX time stamp indicating the time the given exchange rate data was collected, a base object containing the three-letter currency code of the base currency, a date object containing the date the given exchange rate data was collected, and a rates object containing the actual exchange rate data.

Further below, in the Endpoints section, the API response structure will be discussed in detail.

Available Endpoints

The Fixer API includes X API endpoints, each providing a different function. Please note that, depending on your subscription plan, certain API endpoints may be available or not.

• Supported symbols endpoint - Retrieve a list of all available currency codes and names.
• Latest rates endpoint - Returns real-time exchange rate data for all available or a specific set of currencies.
• Convert endpoint - Allows for the conversion of any amount from one currency to another.
• Historical rates endpoint - Returns historical exchange rate data for all available or a specific set of currencies.
• Time-Series data endpoint - Returns daily historical exchange rate data between two specified dates for all available or a specific set of currencies.
• Fluctuation data endpoint - Returns fluctuation data between two specified dates for all available or a specific set of currencies.

SSL Connection

All plans available on Fixer come with 256-bit SSL encryption. To connect to the API via SSL, simply use the https protocol instead of standard http.

JSONP Callbacks

The Fixer API supports JSONP Callbacks. This feature enables you to specify a function name, pass it into the API's callback GET parameter and cause the API to return your requested API response wrapped inside that function.

Example Call:

Sign Up to Run API Request

In the example call above, we are requesting the API to use the callback name MY_FUNCTION.

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

Access-Control / CORS

Fixer also supports Cross-Origin Resource Sharing (CORS) and Access-Control Headers. This will enable you to use the Fixer API via Cross-Origin HTTP Requests.

Learn more about CORS »

HTTP ETags

HTTP ETags are a way to reduce load on your back-end by requesting new Fixer data only when rates have changed since the last API response.

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 on a server, and if that resource is ever updated, the ETag changes.

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

Step 1

Your initial request to the Fixer API will create an ETag object containing a unique ETag key and a Date object containing the exact date and time at which the data was last modified. This data must be cached along with the entire API response for ETags to work.

Step 2

Once you make another API request, make sure to include the If-None-Match HTTP header and set it 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.

Step 3

Depending on whether or not your result set has updated since your last API request, the API will return either:

• The results from your initial API request, along with a 304 – Not Modified HTTP header indicating that no change has occurred. In this case, the size of the API response will be as small as 0.2 KB;
• or new results with an entirely new set of ETag and Date objects indicating that new data has been accessed. In this case, the size of your API response will be normal.

Potential Errors

Whenever a requested resource is not available or an API call fails for another reason, a JSON error is returned. Errors always come with an error code and a description.

Example Error: The following error is returned when your monthly API request volume is exceeded.

Other Errors: