Introduction
CurrencyBeacon provides a simple REST API with real-time and historical exchange rates for 168 world currencies. We deliver currency pairs and data in a universally usable JSON format—compatible with any programming language or application.
Our real-time and historical exchange rate data is retrieved from several major forex data providers, central banks, and various commercial vendors in real-time. It is then validated, processed, and delivered within milliseconds of the market window.
By providing the most representative forex market value available ("midpoint" value) for every API request, our API powers currency converters, mobile applications, financial software components, and back-office systems around the world.
Central banks and currency traders define the rates at which they are willing to buy/sell a specific currency. The real-time mid-market rate is the midpoint between supply and demand at any given time, making it the most accurate rate. This is the rate you will find on independent sources such as Yahoo Finance, Google Finance, Xignite, and XE.
Please note that most commercial applications add a margin to cover processing costs before rates are provided to retail consumers.
API Base URL
All requests to our API should be directed to the URL below:
https://api.currencybeacon.com/v1
Authentication
An API key is required for every request to the CurrencyBeacon API. Your API key is used to
authenticate you with our API, and it should be provided as a api_key URL parameter.
The API key can be retrieved from your account pages. If you do not have an API key, please sign up for a free account key.
?api_key=baa9dc110aa712sd3a9fa2a3dwb6c01d4c875950dc32vs
The api_key should be appended to the URL request, as shown in the example below:
curl -G https://api.currencybeacon.com/v1/latest?api_key=YOUR_API_KEY
Alternatively, you can add an Authorization header to the request with your API Key as the token in the following form:
Authorization: Bearer baa9dc110aa712sd3a9fa2a3dwb6c01d4c875950dc32vs
So, a complete API request using the Authorization header would follow the example below:
curl -X GET "https://api.currencybeacon.com/v1/latest" -H "Authorization: Bearer baa9dc110aa712sd3a9fa2a3dwb6c01d4c875950dc32vs"
API Endpoints
CurrencyBeacon currently supports five API endpoints:
latest, historical, timeseries, currencies,
and convert. Below is a list of the parameters each endpoint requires and a description
of what the API does.
| Service | API Endpoint | Description |
|---|---|---|
latest
|
https://api.currencybeacon.com/v1/latest
|
This endpoint provides real-time exchange rates for all supported currencies. Please note these are mid-market rates; margins are typically added by users before consumers receive them. The endpoint requires the base currency and a list of symbols to be returned. You can view all supported currencies here. |
historical
|
https://api.currencybeacon.com/v1/historical
|
This endpoint provides historical exchange rate data for past dates going back
to 1996. Simply attach the date parameter with a valid date to the
API’s historical endpoint. You can also specify a base currency and a list of
symbols to be returned. View all supported
currencies here.
|
timeseries
|
https://api.currencybeacon.com/v1/timeseries
|
If you have the Startup or Professional plan, you have access to the
timeseries endpoint. This lets you request historical exchange rates
for a given time period. To use this endpoint, specify both
start_date and end_date to define the date range.
|
currencies
|
https://api.currencybeacon.com/v1/currencies
|
This endpoint gives you access to all supported currencies, including each currency’s name and a list of the countries that use it. You can view all supported currencies here. |
convert
|
https://api.currencybeacon.com/v1/convert
|
Using the convert endpoint, you can request our API to perform a
single currency conversion. Simply specify the from currency, the
to currency, and the amount to be converted.
|
HTTP Response Codes
Every API request returns an appropriate HTTP response code. Below is a list of what they mean in the context of our API:
200 |
Success. Everything went smoothly. |
401 |
Unauthorized. Missing or incorrect API token in the header. |
422 |
Unprocessable Entity. Something isn’t quite right (e.g., malformed JSON or incorrect fields). The response body contains JSON with an API error code and message detailing what went wrong. |
500 |
Internal Server Error. An issue occurred with CurrencyBeacon’s servers while processing your request. In most cases, the message is lost during the process, but we are notified so we can investigate the problem. |
503 |
Service Unavailable. During planned service outages, CurrencyBeacon API services will return this HTTP response with an associated JSON body. |
429 |
Too many requests. API rate limits have been reached. |
API Error Codes
Whenever the CurrencyBeacon server detects an input error, it will return an HTTP 422 status code along with a JSON object containing error details:
600 |
Maintenance - The CurrencyBeacon API is offline for maintenance. |
601 |
Unauthorized. Missing or incorrect API token. |
602 |
Invalid query parameters. |
603 |
Authorized Subscription level required. |
JSONP/CORS Requests
JSONP and CORS are supported, allowing you to use the CurrencyBeacon API entirely in client-side
code. For JSONP, you just need to specify the callback parameter, for example:
https://currencybeacon.com/?callback=callback
Most JavaScript libraries will automatically handle this for you.
We have a gallery of code samples here to show you how to use our API in multiple programming languages.
If you have any issues or questions about our API, feel free to reach out at [email protected].