Global Currency Data API Documentation

CurrencyBeacon provides a simple REST API with real-time and historical exchange rates for 168 world currencies. We deliver currency pairs and data in universally usable JSON format - compatible with any programming languages and any of your applications.

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, validated, processed and delivered in seconds within 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 all 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 demand and supply at any point in time, making it the most accurate rate. The mid-market rate is the rate you will find on independent sources such as Yahoo Finance, Google Finance, Xignite and XE.

Please note that most commercial application add a margin to cover processing costs before rates are given to consumers.

API Base URL

All requests to our API should be directed to the URL below:

https://api.currencybeacon.com/v1

API Endpoints

CurrencyBeacon currently supports 5 API endpoints. These are latest, historical, timeseries, currencies and convert. Below you will find a list of parameter that each endpoint requires and a description of what the API does.

Service	API Endpoint	Description
`latest`	`https://api.currencybeacon.com/v1/latest` `base` - Required - The base currency you would like to use for your rates. `symbols` - A list of currencies you will like to see the rates for. You can refer to a list all supported currencies here.	This endpoint provides real-time rates of all currencies we support. Please note that these are mid-market rates and margins are typically added by our users before consumers have access to this endpoint. The endpoint requires the base currency and a list of symbols to be returned. You can refer to a list all supported currencies here.
`historical`	`https://api.currencybeacon.com/v1/historical` `base` - Required - The base currency you would like to use for your rates. `date` - Required - The historical date you wouldlike to access. `symbols` - A list of currencies you will like to see the rates for. You can refer to a list all supported currencies here.	This service provides historical exchange rate data for every past day all the way back to the year of 1996. 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. We support the base currency and list of symbols to be returned. View all supported currencies here.
`timeseries`	`https://api.currencybeacon.com/v1/timeseries` `base` - Required - The base currency you would like to use for your rates. `start_date` - Required - The start date for the time series you would like to access `end_date` - Required - The end date for the time series you would like to access `symbols` - A list of currencies you will like to see the rates for. You can refer to a list all supported currencies here.	If you have the startup or the professional plan, then you have access to the timeframe API service, you may request historical exchange rates for a time-period of your choice. 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`.
`currencies`	`https://api.currencybeacon.com/v1/currencies` `type` - Required - The type of currencies, eitheer `fiat` or `crypto`	This endpoint gives you access to all the currencies we support together with the name of the currencies and the list of countries that use that currency. You can view a list of all supported currencies here.
`convert`	`https://api.currencybeacon.com/v1/convert` `from` - Required - The base currency you would like to use for your rates. `to` - The currency you would like to convert to `amount` - Required - The amount to convert	Using the `convert` endpoint, you may request our 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.

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 the account pages. If you do know your API key please signup for a free account key.

?api_key=baa9dc110aa712sd3a9fa2a3dwb6c01d4c875950dc32vs

The api_key should be appended to the url request like in the example below

 curl -G https://api.currencybeacon.com/v1/latest?api_key=baa9dc110aa712sd3a9fa2a3dwb6c01d4c875950dc32vs

HTTP response codes

Every API request returns an appropriate HTTP reponse code and below is a list of what they mean with regards to the API

`200`	Success Everything went smooth.
`401`	Unauthorized Missing or incorrect API token in header.
`422`	Unprocessable Entity meaning something with the message isn’t quite right, this could be malformed JSON or incorrect fields. In this case, the response body contains JSON with an API error code and message containing details on what went wrong.
`500`	Internal Server Error This is an issue with CurrencyBeacon's servers processing your request. In most cases the message is lost during the process, and we are notified so that we can investigate the issue.
`503`	Service Unavailable During planned service outages, CurrencyBeacon API services will return this HTTP response and associated JSON body.
`429`	Too many requests. API limits 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 CurrencyBeacon API entirely in client-side code. For JSONP You just need to specify the callback parameter, eg.

https://currencybeacon.com/?callback=callback

Most javascript libraries will automatically handle this for you though.

We have a gallery of code samples here. Learn how to use out APi in multiple programming languages.

Feel free to reach out to us if you have an issue with out API our with any questions you might have at [email protected].