Documentation

This page has been created to help you understand how to use our powerful service.


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 named demo. This key has very limited daily use 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.


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=demo

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.
limit Limit which currency conversions are returned using the limit param. Comma separated (no space) values. Optional
https://currencyapi.net/api/v1/rates
? key=demo
& base=GBP
JSON | XML
{
  "valid": true,
  "timestamp": 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>
    <timestamp>1526293289</timestamp>
    <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>

You can also select the currencies that are returned by using the limit parameter. To return multiple currencies use a comma to separate each three letter currency code.

https://currencyapi.net/api/v1/rates
? key=demo
& base=GBP
& limit=USD,EUR,JPY
& output=json
JSON | XML
{
  "valid": true,
  "timestamp": 1526293289,
  "base": "GBP",
  "rates": {
      "USD": 1.331535,
      "EUR": 1.140065,
      "JPY": 146.022773

  }
}
<?xml version="1.0" encoding="utf-8"?>
<root>
    <valid>1</valid>
    <timestamp>1526293289</timestamp>
    <base>GBP</base>
    <rates>
        <USD>1.331535</USD>
        <EUR>1.140065</EUR>
        <JPY>146.022773</JPY>
    </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=demo
& amount=99.87
& from=GBP
& to=BTC
& output=json
JSON | XML
{

    "valid": true,
    "timestamp": 1527708277,
    "conversion": {
        "amount": 99.87,
        "from": "GBP",
        "to": "BTC",
        "result": 0.017462
    }
}
<?xml version="1.0" encoding="utf-8"?>
<root>
    <valid>1</valid>
    <timestamp>1527708277</timestamp>
    <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=demo
& date=2010-12-25
& base=BTC
& output=json
JSON | XML
{
  "valid": true,
  "timestamp": 1526293289,
  "base": "GBP",
  "date": "2010-12-25"
  "historical": true,
  "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>
    <timestamp>1526293289</timestamp>
    <base>GBP</base>
    <date>2010-12-25</date>
    <historical>1</historical>
    <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=demo
& start_date=2017-12-25
& end_date=2018-01-10
& base=GBP
& output=json
JSON | XML
{
  "valid": true,
  "timestamp": 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>
    <timestamp>1526293289</timestamp>
    <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=demo
& output=json
JSON | XML
{
  "valid": true,
  "timestamp": 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>
    <timestamp>1527714871</timestamp>
    <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.
999 There seems to be a technical fault our end