API Documentation

Introduction

Currency Conversion API provides a simple REST API with real-time and historical exchange rates for 161 world currencies, delivering currency pairs in universally usable JSON format - compatible with any of your applications.

Spot exchange rate data is retrieved from several major forex data providers in real-time, validated, processed and delivered hourly, every 10 minutes, or even within the 60-second market window.

Providing the most representative forex market value available ("midpoint" value) for every API request, the Currency Conversion API powers currency converters, mobile applications, financial software components and back-office systems all around the world. 

                        
                        https://currencyconversionapi.com/api/v1/

Authentication

After signing up you will receive an API access key (shown in your dashboard) used to access any of the API endpoints.

To authenticate with the API, you must provide your API access key in the access_key parameter of the API endpoint URL: 

                                    
                                   curl --url 'https://currencyconversionapi.com/api/v1/live?access_key=YOUR_ACCESS_KEY'
                                
                        
                                    <?php
// configure request
$endpoint = 'https://currencyconversionapi.com/api/v1/live?access_key=YOUR_ACCESS_KEY';

// init curl
$ch = curl_init();

// set curl options
curl_setopt($ch, CURLOPT_URL, $endpoint);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);

$response = curl_exec($ch);

curl_close($ch);

// print response as json
header('Content-Type: application/json');

// print response
print_r($response);

Responses

All API data is returned in an easily parsable JSON format.

Below is an example response using the convert endpoint to convert currencies.

{
  "success": true,
  "terms": "https://currencyconversionapi.com/terms-and-conditions",
  "privacy": "https://currencyconversionapi.com/privacy-policy",
  "query": {
     "from": "USD",
     "to": "GBP",
     "amount": 10
  },
  "info": {
     "timestamp": 1430068515,
     "quota": 0.658443
  },
  "result": 6.58443
}

Errors

If your request fails, the API will return a 3-digit error-code along with an internal error type and a plain text "info" parameter containing suggestions for the user.

Below is an example error caused by providing an invalid API Access Key. 

{
  "success": false,
  "error": {
    "code": 102,
    "title": "invalid_access_key",
    "info": "You supplied an invalid Access Key."
  }
}

API errors and codes:

Code Type Description
101 missing_access_key You did not supply an Access Key.
102 invalid_access_key You supplied an invalid Access Key.
104 usage_limit_reached You have reached your subscription plan's monthly API request allowance.
105 access_restricted Your current subscription plan does not support this API function.
106 invalid_callback_function_name You have not supplied a valid callback function name.
301 missing_property A required parameter has not been supplied.
404 404_not_found The requested API resource does not exist.
405 method_not_allowed Method not allowed. Supported methods: GET, POST.
500 server_error Something went wrong - Internal server error.

Please Note: This is not a complete list of errors. If you come receive an error message you are not sure about please contact our support.

JSONP Callbacks

The API also supports JSONP callbacks so you can use the service in javascript.

To specify the javascript function to be called, provide the callback= parameter to any of the endpoints.

Not sure what JSONP is? Here's an explanation Stack Overflow. 

                        

// Set the endpoint and the callback function name
var endpoint = 'https://currencyconversionapi.com/api/v1/live?access_key=YOUR_ACCESS_KEY&callback=my_callback_function';

// Define the callback function
function my_callback_function(json){
    //log to the console
    console.log('json', json);
    // Alert the result object properties
    alert(json.success);
    alert(json.info.timestamp);
    alert(json.info.quota);
    alert(json.result);
}

// Validate VAT number via jQuery AJAX call with JSONP callback
$.ajax(
    url: endpoint,
    dataType: 'jsonp',
    jsonpCallback: 'my_callback_function',
    jsonp: 'callback',
});

                    
                                        my_callback_function({
  {
    "success": true,
    "terms": "https://currencyconversionapi.com/terms-and-conditions",
    "privacy": "https://currencyconversionapi.com/privacy-policy",
    "query": {
       "from": "USD",
       "to": "EUR",
       "amount": 10
    },
    "info": {
       "timestamp": 1430068515,
       "quota": 0.658443
    },
    "result": 6.58443
  }
})

Supported Currencies

A full list of supported currencies can be accessed both in JSON Format (access key required) and on this website.

In order to access a JSON file containing all currently supported currencies (3-letter currency code and full currency name), simply attach your access_key to the Currency Conversion API list endpoint:

Response Attributes

success

boolean

Contains true if the request was processed successfully and did not generate any errors and false if there was a problem.

terms

string

Returns a link to the Currency Conversion API Terms & Conditions.

privacy

string

Returns a link to the Currency Conversion API Privacy Policy.

currencies

object

Returns all currencies supported by the Currency Conversion API. 

                                    
                                   curl --url 'https://currencyconversionapi.com/api/v1/list?access_key=YOUR_ACCESS_KEY'
                                
                        
                                    <?php
// configure request
$endpoint = 'https://currencyconversionapi.com/api/v1/list?access_key=YOUR_ACCESS_KEY';

// init curl
$ch = curl_init();

// set curl options
curl_setopt($ch, CURLOPT_URL, $endpoint);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);

$response = curl_exec($ch);

curl_close($ch);

// print response as json
header('Content-Type: application/json');

// print response
print_r($response);
                                
                                        {
  "success": true,
  "terms": "https://currencyconversionapi.com/terms-and-conditions",
  "privacy": "https://currencyconversionapi.com/privacy-policy",
  "currencies": {
     "ALL": "Albania Lek",
     "AFN": "Afghanistan Afghani",
     "ARS": "Argentina Peso",
     "AWG": "Aruba Guilder",
     [...]
  }
}

Real-time Rates

Both free and paid users may access real-time exchange rates using the Currency Conversion API live endpoint.

Optionally, it is possible to define an additional source currency and specific output currencies using the targets parameter. Both of these options will be discussed in detail throughout this documentation.

Request Parameters:
Response Attributes

success

boolean

Contains true if the request was processed successfully and did not generate any errors and false if there was a problem.

terms

string

Returns a link to the Currency Conversion API Terms & Conditions.

privacy

string

Returns a link to the Currency Conversion API Privacy Policy.

timestamp

integer

Returns the exact date and time (UNIX) the exchange rates were collected.

source

string

Returns the currency to which all exchange rates are relative. (default: USD)

quotes

object

Contains all exchange rate values, consisting of the currency pairs and their respective conversion rates. 

                                    
                                   curl --url 'https://currencyconversionapi.com/api/v1/live?access_key=YOUR_ACCESS_KEY'
                                
                        
                                    <?php
// configure request
$endpoint = 'https://currencyconversionapi.com/api/v1/live?access_key=YOUR_ACCESS_KEY';

// init curl
$ch = curl_init();

// set curl options
curl_setopt($ch, CURLOPT_URL, $endpoint);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);

$response = curl_exec($ch);

curl_close($ch);

// print response as json
header('Content-Type: application/json');

// print response
print_r($response);
                                
                                        {
  "success": true,
  "terms": "https://currencyconversionapi.com/terms-and-conditions",
  "privacy": "https://currencyconversionapi.com/privacy-policy",
  "timestamp": 1430068515,
  "source": "USD",
  "quotes": {
     "USDAUD": 1.278342,
     "USDEUR": 1.278342,
     "USDGBP": 0.908019,
     "USDPLN": 3.731504,
     [...]
  }
}

Historical Rates

The Currency Conversion API provides accurate historical exchange rate data for every past day all the way back to the year of 1999.

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.

Request Parameters:
Response Attributes

success

boolean

Contains true if the request was processed successfully and did not generate any errors and false if there was a problem.

terms

string

Returns a link to the Currency Conversion API Terms & Conditions.

privacy

string

Returns a link to the Currency Conversion API Privacy Policy.

historical

boolean

Returns true to confirm your request to the Historical endpoint.

date

string

Contains selected date.

timestamp

integer

Returns the exact date and time (UNIX) the exchange rates were collected.

source

string

Returns the currency to which all exchange rates are relative. (default: USD)

quotes

object

Contains all exchange rate values, consisting of the currency pairs and their respective conversion rates. 

                                    
                                   curl --url 'https://currencyconversionapi.com/api/v1/historical?access_key=YOUR_ACCESS_KEY&date=2005-02-01'
                                
                        
                                    <?php
// configure request
$endpoint = 'https://currencyconversionapi.com/api/v1/historical?access_key=YOUR_ACCESS_KEY&date=2005-02-01';

// init curl
$ch = curl_init();

// set curl options
curl_setopt($ch, CURLOPT_URL, $endpoint);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);

$response = curl_exec($ch);

curl_close($ch);

// print response as json
header('Content-Type: application/json');

// print response
print_r($response);
                                
                                        {
  "success": true,
  "terms": "https://currencyconversionapi.com/terms-and-conditions",
  "privacy": "https://currencyconversionapi.com/privacy-policy",
  "historical": true,
  "date": "2005-02-01",
  "timestamp": 1430068515,
  "source": "USD",
  "quotes": {
     "USDAUD": 1.278342,
     "USDEUR": 1.278342,
     "USDGBP": 0.908019,
     "USDPLN": 3.731504,
     [...]
  }
}

Currency Conversion Endpoint

Using the convert endpoint, you may request the Currency Conversion 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.

Request Parameters:
Response Attributes

success

boolean

Contains true if the request was processed successfully and did not generate any errors and false if there was a problem.

terms

string

Returns a link to the Currency Conversion API Terms & Conditions.

privacy

string

Returns a link to the Currency Conversion API Privacy Policy.

query > from

string

Returns the currency the given amount is converted from.

query > to

string

Returns the currency the given amount is converted to.

query > amount

double

Returns the conversion amount.

info > timestamp

integer

Returns the exact date and time (UNIX) the exchange rate was collected.

info > quote

double

Returns the exchange rate used for the conversion.

historical

boolean

Returns true to confirm your historical currency conversion request.

date

string

Returns the date specified for your historical currency conversion request.

result

double

Returns your conversion result. 

                                    
                                   curl --url 'https://currencyconversionapi.com/api/v1/convert?access_key=YOUR_ACCESS_KEY&from=USD&to=GBP&amount=10'
                                
                        
                                    <?php
// configure request
$endpoint = 'https://currencyconversionapi.com/api/v1/convert?access_key=YOUR_ACCESS_KEY&from=USD&to=GBP&amount=10';

// init curl
$ch = curl_init();

// set curl options
curl_setopt($ch, CURLOPT_URL, $endpoint);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);

$response = curl_exec($ch);

curl_close($ch);

// print response as json
header('Content-Type: application/json');

// print response
print_r($response);
                                
                                        {
  "success": true,
  "terms": "https://currencyconversionapi.com/terms-and-conditions",
  "privacy": "https://currencyconversionapi.com/privacy-policy",
  "query": {
     "from": "USD",
     "to": "GBP",
     "amount": 10
  },
  "info": {
     "timestamp": 1430068515,
     "quota": 0.658443
  },
  "result": 6.58443
}

Time-Frame Queries

If your subscription plan features the timeframe API endpoint, you may request historical exchange rates for a time-period of your choice. (maximum range: 365 days)

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.

Request Parameters:
Response Attributes

success

boolean

Contains true if the request was processed successfully and did not generate any errors and false if there was a problem.

terms

string

Returns a link to the Currency Conversion API Terms & Conditions.

privacy

string

Returns a link to the Currency Conversion API Privacy Policy.

timeframe

boolean

Returns true to confirm your request to the Time-Frame endpoint.

start_date

string

Returns the specified start date.

end_date

string

Returns the specified end date.

source

string

Returns the currency to which all exchange rates are relative. (default: USD)

quotes

object

The quotes object will contain one sub-object with exchange rate data per day in your time frame. 

                                    
                                   curl --url 'https://currencyconversionapi.com/api/v1/timeframe?access_key=YOUR_ACCESS_KEY&start_date=2010-03-01&end_date=2010-04-01'
                                
                        
                                    <?php
// configure request
$endpoint = 'https://currencyconversionapi.com/api/v1/timeframe?access_key=YOUR_ACCESS_KEY&start_date=2010-03-01&end_date=2010-04-01';

// init curl
$ch = curl_init();

// set curl options
curl_setopt($ch, CURLOPT_URL, $endpoint);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);

$response = curl_exec($ch);

curl_close($ch);

// print response as json
header('Content-Type: application/json');

// print response
print_r($response);
                                
                                        {
  "success": true,
  "terms": "https://currencyconversionapi.com/terms-and-conditions",
  "privacy": "https://currencyconversionapi.com/privacy-policy",
  "timeframe": true,
  "start_date": "2005-02-01",
  "end_date": "2005-02-01",
  "source": "USD",
  "quotes": {
      "2010-03-01": {
          "USDAUD": 1.278342,
          "USDEUR": 1.278342,
          "USDGBP": 0.908019,
          "USDPLN": 3.731504,
      },
      [...]
  }
}

Currency-Change Queries

Using the API's change endpoint, you may request the change (both margin and percentage) of one or more currencies, relative to a Source Currency, within a specific time-frame (optional).

Unlike with Time-Frame Queries, performing a Currency-Change Query does not require you to specify a time-frame. If you do not provide a time-frame, the API will automatically return the change values ranging from yesterday's EOD (End Of Day) data, to the latest available exchange rates of today.

However, if you decide to specify a start_date and and end_date (both of the format YYYY-MM-DD), the API will return change values for your preferred time-frame.

Request Parameters:
Response Attributes

success

boolean

Contains true if the request was processed successfully and did not generate any errors and false if there was a problem.

terms

string

Returns a link to the Currency Conversion API Terms & Conditions.

privacy

string

Returns a link to the Currency Conversion API Privacy Policy.

change

boolean

Returns true to confirm your request to the Currency-Change endpoint.

start_date

string

Returns the specified start date.

end_date

string

Returns the specified end date.

source

string

Returns the currency to which all exchange rates are relative. (default: USD)

quotes

object

The quotes object will contain one sub-object with exchange rate data per day in your time frame. 

                                    
                                   curl --url 'https://currencyconversionapi.com/api/v1/change?access_key=YOUR_ACCESS_KEY&start_date=2010-03-01&end_date=2010-04-01'
                                
                        
                                    <?php
// configure request
$endpoint = 'https://currencyconversionapi.com/api/v1/change?access_key=YOUR_ACCESS_KEY&start_date=2010-03-01&end_date=2010-04-01';

// init curl
$ch = curl_init();

// set curl options
curl_setopt($ch, CURLOPT_URL, $endpoint);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);

$response = curl_exec($ch);

curl_close($ch);

// print response as json
header('Content-Type: application/json');

// print response
print_r($response);
                                
                                        {
  "success": true,
  "terms": "https://currencyconversionapi.com/terms-and-conditions",
  "privacy": "https://currencyconversionapi.com/privacy-policy",
  "change": true,
  "start_date": "2005-02-01",
  "end_date": "2005-02-01",
  "source": "USD",
  "quotes": {
      "USDAUD": {
          "start_rate": 1.281236,
          "end_rate": 1.108609,
          "change": -0.1726,
          "change_pct": -13.4735,
      },
      [...]
  }
}

Downloads

HTML Select-Option Menu Download

Get a full list of all supported currencies wrapped in HTML <select><option> tags: 

                        <select name='currencies'>
    <option value='AED' title='United Arab Emirates Dirham'>AED</option>
    <option value='AFN' title='Afghan Afghani'>AFN</option>
    <option value='ALL' title='Albanian Lek'>ALL</option>
    <option value='AMD' title='Armenian Dram'>AMD</option>
    <option value='ANG' title='Netherlands Antillean Guilder'>ANG</option>
    [...]
</select>
HTML Currencies Table Download

Download a clean HTML <table> containing all supported currencies: 

                        <table>
    <thead>
        <tr>
            <th>Code</th>
            <th>Name</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>AED</td>
            <td>United Arab Emirates Dirham</td>
        </tr>
        <tr>
            <td>AFN</td>
            <td>Afghan Afghani</td>
        </tr>
        <tr>
            <td>ALL</td>
            <td>Albanian Lek</td>
        </tr>
        <tr>
            <td>AMD</td>
            <td>Armenian Dram</td>
        </tr>
        <tr>
            <td>ANG</td>
            <td>Netherlands Antillean Guilder</td>
        </tr>
        [...]
    </tbody>
</table>