Alternative Rates ('show_alternative')

You may add data for all supported unofficial, black market and alternative digital currencies by adding the show_alternative query parameter to your API request. The list of supported 'alternative' currencies is here.

Some of these rates are due to be added to the primary API (such as LTC/Litecoin and ETH/Ether), while others will remain available only through the show_alternative API parameter (such as VEF_DIPRO and VEF_DICOM).

📘

Alternative currencies data are available for all clients, and the feature is currently in stable beta. The request and response format may change and currencies may be added and removed (but we'll post an update via our Status Page whenever this happens).

You may contact us with any feedback or questions about this feature and the returned rates at [email protected].

🚧

Future inclusion of ETH and LTC symbols in primary API results

In early 2018, we intend to merge ETH (Ethereum) and LTC (Litecoin) with our 'primary' API results. This means they'll be available to all users, without using the special show_alternative parameter.

If you rely on ETH or LTC data in your integration and you use the show_alternative parameter to fetch them, then you will still receive them after this change, exactly as before and will not need to change your integration.

However, if you use the (now deprecated) only_alternative parameter to fetch LTC or ETH, you will need to modify your integration to use show_alternative instead. After this change, only_alternative will no longer return ETH or LTC. We will send an email update ahead of this change, giving you ample time to make any needed adjustments.

Please contact us if you need any help or support making this change, or have any questions about these rates.

Request Latest 'Alternative' Rates

Append the show_alternative query parameter to your latest.json, historical/ or time-series.json API request, like so:

https://openexchangerates.org/api/latest.json
    ?app_id=YOUR_APP_ID
    &show_alternative=1

$.get('https://openexchangerates.org/api/latest.json', {app_id: 'YOUR_APP_ID', show_alternative: 1}, function(data) {
    console.log(data);
});

The response format is exactly the same as the standard API response, with additional rates added to the rates object:

{
    disclaimer: "https://openexchangerates.org/terms/",
    license: "https://openexchangerates.org/license/",
    "timestamp": 1500652863,
    "base": "USD",
    "rates": {
        "AED": 3.673018,
        /* ... */
        "VEF_BLKMKT": 8570.78,
        "VEF_DICOM": 2700,
        "VEF_DIPRO": 10,
        /* ... */
    }
}

Each new symbol can be set as the base currency, if available in the returned data set (default is USD).

NB: Only currencies in the returned list can be set as a base currency.

📘

Alternative rate symbols are not limited to standard international 3-letter ISO codes, and may have fewer or more characters (such as "VEF_BLKMKT").

You can find a full list via the currencies.json route (see below), and our list of supported currencies.

Get List Of Available Alternative Currencies

The show_alternative query option can be added to requests for our currencies.json endpoint, to include alternative rate symbols and full currency names:

https://openexchangerates.org/api/currencies.json
    ?show_alternative=1

You can view a list of supported alternative rates here.

Basic Code Samples

$.get('https://openexchangerates.org/api/latest.json', {app_id: 'YOUR_APP_ID', show_alternative: 1}, function(data) {
    console.log("1 USD equals " + data.rates.DOGE + " DogeCoin.");
    console.log("1 USD equals " + data.rates.VEF_BLKMKT + " Venezuelan Bolivar on the black market.");
});

More code samples are on their way! Please get in touch if you'd like to submit a new/improved code sample in your languague or framework.

Combining Parameters

Alternative, digital and black-market rates can be combined with all other parameters on the latest.json endpoint:

https://openexchangerates.org/api/latest.json
    ?app_id=YOUR_APP_ID
    &base=LTC
    &show_alternative=1
    &symbols=ETH,VEF,VEF_DIPRO,VEF_DICOM,VEF_BLKMKT,BTC,NEM
    &prettyprint=0

Changes to Alternative rates parameter

🚧

What happened to "experimental" rates?

On 31st January 2017, we updated the terminology for this API option from show_experimental to show_alternative, to reflect the fact that these currencies are not generally considered to be experimental. The parameter functions exactly as before.

Although we will continue to support the legacy 'experimental' syntax, we strongly recommend updating your integration to the new parameter name.

🚧

What happened to the "only_alternative" / "only_experimental" parameter?

The only_alternative (and previously, only_experimental) parameters enabled you to see only alternative rates in your API response (excluding the standard list).

This parameter has been deprecated as of July 2017, and may be removed in future. We strongly advise using show_alternative instead, and using the symbols parameter to limit the returned results.