Currency

API Documentation

{api}

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, each of the code examples below will display the placeholder api key, YOUR_API_KEY.

Signup today or login to see the code examples complete with your api key.

Packages & Collections

Before we get into the details, if you're a Postman user, try our collection out via postman for the fastest setup.

Alternatively, you may prefer using our of our NodeJs (NPM) or PHP (Composer) packages.

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.

Correctly formatted requests return a 200 HTTP response code.

Incorrect or incomplete requests return a 400 HTTP response code.

We also return an error code in the body of our response to help you identify the issue with the request. See the full list of these below.

JSON | XML 
{
  "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>

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.

Each endpoint only accepts a GET request.

/* GET - 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

Currency List Endpoint

- GET /api/v1/currencies

We supply real-time live rates on 152 currencies, crypto-currencies and precious metals.

To view the full list, you can hit our endpoint, or you can visit the currency list page.

Parameter Description
output Response output in either JSON or XML. Default: JSON.

Request

JSON | XML
  • cURL
  • PHP
  • NodeJs
  • Python
  • Ruby
  • Java
  • Go
  • jQuery

Response

{
  "valid": true,
  "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>
    <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>

Currency Rates Endpoint

- GET /api/v1/rates

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.

Request

JSON | XML
  • cURL
  • PHP
  • NodeJs
  • Python
  • Ruby
  • Java
  • Go
  • jQuery

Response

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

- GET /api/v1/convert

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.

Request

JSON | XML
  • cURL
  • PHP
  • NodeJs
  • Python
  • Ruby
  • Java
  • Go
  • jQuery

Response

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

- GET /api/v1/history

Use the history endpoint to display the currency conversion's historical rates for a particular day.

At the end of each day (23:59 GMT) we store the rate as it was this time.

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.

Request

JSON | XML
  • cURL
  • PHP
  • NodeJs
  • Python
  • Ruby
  • Java
  • Go
  • jQuery

Response

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

- GET /api/v1/timeframe

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.

Request

JSON | XML
  • cURL
  • PHP
  • NodeJs
  • Python
  • Ruby
  • Java
  • Go
  • jQuery

Response

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

More info

For more information about our services, check out our Exchange Rate API page.

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.
420 You have requested either today's date or a date in the future. For timeframe and history endpoints, we store the data at 23:59 GTM of the current day.
500 There seems to be a technical fault our end 
<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => 'https://currencyapi.net/api/v1/rates?key=YOUR_API_KEY&output=JSON',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
]);
$response = curl_exec($curl);
curl_close($curl);

echo $response;

curl --location --request GET 'https://currencyapi.net/api/v1/rates?key=YOUR_API_KEY&output=JSON'

var request = require('request');
var options = {
  'method': 'GET',
  'url': 'https://currencyapi.net/api/v1/rates?key=YOUR_API_KEY&output=JSON',
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});


import requests

url = "https://currencyapi.net/api/v1/rates?key=YOUR_API_KEY&output=JSON"
response = requests.request("GET", url)

print(response.text)

require "uri"
require "net/http"

url = URI("https://currencyapi.net/api/v1/rates?key=YOUR_API_KEY&output=JSON")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Get.new(url)

response = https.request(request)
puts response.read_body

Unirest.setTimeouts(0, 0);
HttpResponse<String> response = Unirest.get("https://currencyapi.net/api/v1/rates?key=YOUR_API_KEY&output=JSON")
  .asString();

package main
import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {
  url := "https://currencyapi.net/api/v1/rates?key=YOUR_API_KEY&output=JSON"
  method := "GET"
  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, nil)
  if err != nil {
    fmt.Println(err)
    return
  }
  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()
  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

var settings = {
  "url": "https://currencyapi.net/api/v1/rates?key=YOUR_API_KEY&output=JSON",
  "method": "GET",
  "timeout": 0,
};

$.ajax(settings).done(function (response) {
  console.log(response);
});
Your experience on this site will be improved by allowing cookies.