Documentation
This page has been created to help you understand how to use our powerful service.
Postman
Before we get into the details, if you're a Postman user, try our collection out via postman for the fastest setup.
Authentication
Once you have created an account, your account will be assigned a unique 36 character API key. Think of this like a secure password, keep it safe and do not share it with others.
Since you are not logged in, we supply a dummy API key. This key changes daily and is on the free tier.
Response
By default our API response is in JSON. You can select to output in XML on any of our API by passing the output parameter to equal xml, see examples below.
Currency List
We supply real-time live rates on 152 currencies, crypto-currencies and precious metals. To view the full list, please visit the currency list page.
Endpoints
Endpoints tell our application which one of our services you want to use (rates, convert, history etc).
Here are a list of endpoints we offer. NOTE: Access to endpoints depend on your subscription.
/* List All Supported Currencies */ https://currencyapi.net/api/v1/currencies /* Get Currency Rates */ https://currencyapi.net/api/v1/rates /* Get Currency Conversion */ https://currencyapi.net/api/v1/convert /* Get Historic Day Rates of a Currency */ https://currencyapi.net/api/v1/history /* Get Timeframe Rates of a Currency */ https://currencyapi.net/api/v1/timeframe
Once you have decided which endpoint you want to retrieve, simply add your API key and any other parameters and away you go.
Here is an example URL to retrieve the currency rates for the default currency (USD):
https://currencyapi.net/api/v1/rates?key=zlEK8WDsTQ43SR9nVOBXqTSXFVVddD7FLeZl
Currency Rates Endpoint
Use the rates endpoint to display all the conversions of a currency.
These values are updated every
- 60 seconds (Professional Plan)
- 10 minutes (StartUp Plan)
- 1 hour (Essential and FREE Plan).
Using the rates endpoint, you can select a base currency as a parameter (only available on paid accounts). This will display every currency conversion for that currency.
NOTE: By default the base currency is set to USD.
Parameter | Description |
---|---|
base |
The base currency you wish you receive the currency conversions for. This will output all currency conversions for that currency. Default: USD. |
output |
Response output in either JSON or XML. Default: JSON. |
https://currencyapi.net/api/v1/rates ? key=zlEK8WDsTQ43SR9nVOBXqTSXFVVddD7FLeZl & base=GBP & output=json
{ "valid": true, "updated": 1526293289, "base": "GBP", "rates": { "AED": 5.2204725081026, "AFN": 99.505376130096, "ALL": 148.13498464775, "AMD": 683.01869278444, "ANG": 2.5307798373799, ... } }
<?xml version="1.0" encoding="utf-8"?> <root> <valid>1</valid> <updated>1526293289</updated> <base>GBP</base> <rates> <AED>5.2204725081026</AED> <AFN>99.505376130096</AFN> <ALL>148.13498464775</ALL> <AMD>683.01869278444</AMD> <ANG>2.5307798373799</ANG> ... </rates> </root>
Convert Endpoint
Use the convert endpoint to convert a custom amount from one currency to another.
There are three required parameters you have to set in order make a successful call.
Parameter | Description |
---|---|
amount |
The value of the currency you want to convert from. This should be a number and can contain a decimal place. Required. |
from |
The currency you want to convert. This will be a three letter ISO 4217 currency code from one of the currencies we have rates for. Required. |
to |
The currency you want to convert the amount 'to'. Again this will be a three letter currency code from the ones we offer. Required. |
output |
Response output in either JSON or XML. Default: JSON. |
https://currencyapi.net/api/v1/convert ? key=zlEK8WDsTQ43SR9nVOBXqTSXFVVddD7FLeZl & amount=99.87 & from=GBP & to=BTC & output=json
{ "valid": true, "updated": 1527708277, "conversion": { "amount": 99.87, "from": "GBP", "to": "BTC", "result": 0.017462 } }
<?xml version="1.0" encoding="utf-8"?> <root> <valid>1</valid> <updated>1527708277</updated> <conversion> <amount>99.87</amount> <from>GBP</from> <to>BTC</to> <result>0.017462</result> </conversion> </root>
History Endpoint
Use the history endpoint to display the currency conversion's historical rates for a particular day.
Parameter | Description |
---|---|
date |
The historical date you wish to receive the currency conversions for. This should be formatted as YYYY-MM-DD. Required. |
base |
The base currency you wish you receive the currency conversions for. This will output all currency conversions for that currency. Default: USD. |
output |
Response output in either JSON or XML. Default: JSON. |
https://currencyapi.net/api/v1/history ? key=zlEK8WDsTQ43SR9nVOBXqTSXFVVddD7FLeZl & date=2010-12-25 & base=BTC & output=json
{ "valid": true, "updated": 1526293289, "base": "GBP", "date": "2010-12-25" "rates": { "AED": 5.2204725081026, "AFN": 99.505376130096, "ALL": 148.13498464775, "AMD": 683.01869278444, "ANG": 2.5307798373799, ... } }
<?xml version="1.0" encoding="utf-8"?> <root> <valid>1</valid> <updated>1526293289</updated> <base>GBP</base> <date>2010-12-25</date> <rates> <AED>5.2204725081026</AED> <AFN>99.505376130096</AFN> <ALL>148.13498464775</ALL> <AMD>683.01869278444</AMD> <ANG>2.5307798373799</ANG> ... </rates> </root>
Timeframe Endpoint
Use the timeframe endpoint to display a currency conversion's historical rates within a given timeframe.
NOTE: While we allow a timeframe of up to 1 year, please be aware requesting a long time period will take longer to execute.
Parameter | Description |
---|---|
start_date |
The historical date you wish to receive the currency conversions from. This should be formatted as YYYY-MM-DD. Required. |
end_date |
The historical date you wish to receive the currency conversions until. This should be formatted as YYYY-MM-DD. Required. |
base |
The base currency you wish you receive the currency conversions for. This will output all currency conversions for that currency. Default: USD. |
output |
Response output in either JSON or XML. Default: JSON. |
https://currencyapi.net/api/v1/timeframe ? key=zlEK8WDsTQ43SR9nVOBXqTSXFVVddD7FLeZl & start_date=2017-12-25 & end_date=2018-01-10 & base=GBP & output=json
{ "valid": true, "updated": 1526293289, "base": "GBP", "start_date": "2017-12-25", "end_date": "2018-01-10" "rates": { "AED": 5.2204725081026, "AFN": 99.505376130096, "ALL": 148.13498464775, "AMD": 683.01869278444, "ANG": 2.5307798373799, ... } }
<?xml version="1.0" encoding="utf-8"?> <root> <valid>1</valid> <updated>1526293289</updated> <base>GBP</base> <start_date>2017-12-25</start_date> <end_date>2018-01-10</end_date> <rates> <AED>5.2204725081026</AED> <AFN>99.505376130096</AFN> <ALL>148.13498464775</ALL> <AMD>683.01869278444</AMD> <ANG>2.5307798373799</ANG> ... </rates> </root>
Currencies Endpoint
Use the currencies endpoint to list each currency name and currency code we support.
Parameter | Description |
---|---|
output |
Response output in either JSON or XML. Default: JSON. |
https://currencyapi.net/api/v1/currencies ? key=zlEK8WDsTQ43SR9nVOBXqTSXFVVddD7FLeZl & output=json
{ "valid": true, "updated": 1527714871, "currencies": { "AED": "United Arab Emirates Dirham", "AFN": "Afghan Afghani", "ALL": "Albanian Lek", "AMD": "Armenian Dram", "ANG": "Netherlands Antillean Guilder", ... } }
<?xml version="1.0" encoding="utf-8"?> <root> <valid>1</valid> <updated>1527714871</updated> <currencies> <AED>United Arab Emirates Dirham</AED> <AFN>Afghan Afghani</AFN> <ALL>Albanian Lek</ALL> <AMD>Armenian Dram</AMD> <ANG>Netherlands Antillean Guilder</ANG> ... </currencies> </root>
Error codes
If your API fails we will supply you with a three digit error code and a human readable message for why the failure happened.
Below are a list of codes and messages we return:
Code | Description |
---|---|
400 |
You did not supply an API key |
401 |
Your API key is not valid |
402 |
Your requesting an API function that does not exist. Please check the docs |
403 |
You requested a pair that does not exist |
405 |
You have hit your monthly subscription allowance. |
406 |
You've requested a base currency that doesn't exist |
407 |
Your subscription plan does not allow you to use secure HTTPS encryption. |
408 |
Your subscription plan does not allow you to select a base currency. |
410 |
The 'from' parameter was not set. |
411 |
The 'to' parameter was not set. |
412 |
The 'amount' parameter was not set |
413 |
The value you entered for the amount parameter is incorrect. Please make sure it is numeric and greater than 0. |
414 |
One or more of the currencies is not a currency we support or has been entered invalid. |
415 |
One or more of the currencies you wanted to receive (limit) is not a currency we support or has been entered invalid. |
416 |
Your subscription plan does not allow you to use the %s endpoint |
417 |
There is no historical data for %s for the date supplied. |
418 |
One or more of the dates you supplied were not in the correct format (eg 2017-12-25). |
419 |
We allow a maximum of 365 days. Please change this and try again. |
500 |
There seems to be a technical fault our end |