Documentation for live currency api

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"
  "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>
    <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