{"_id":"56a480315fb2530d00421b75","editedParams2":true,"project":"55312174c68f493900aebb3f","editedParams":true,"category":{"_id":"566b59110506f40d0034f148","__v":5,"pages":["566b5afcec4a320d00a8ca76","566b63213d25d00d0066b00a","56a47942e5e9190d00ad6200","56a480315fb2530d00421b75","56a489ae9093960d00f9ab31"],"project":"55312174c68f493900aebb3f","version":"55312174c68f493900aebb42","sync":{"url":"","isSync":false},"reference":true,"createdAt":"2015-12-11T23:15:29.864Z","from_sync":false,"order":2,"slug":"extra-parameters","title":"Extra Parameters"},"user":"5531215e29603d2300011341","version":{"_id":"55312174c68f493900aebb42","project":"55312174c68f493900aebb3f","__v":10,"createdAt":"2015-04-17T15:06:28.598Z","releaseDate":"2015-04-17T15:06:28.598Z","categories":["55312175c68f493900aebb43","566b431d03b4b20d00d02c3a","566b58f212bc0517005d3068","566b59110506f40d0034f148","566b7cc94d1a4d0d00801c00","566b82d130cdb417008d217d","566b855b4d1a4d0d00801c04","566b856f03870a0d008ee7a7","566c42d2f0a5dc0d009acbab","566c443d85dc790d0062c134"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"0.7.0","version":"0.7"},"__v":1,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-01-24T07:41:37.678Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"results":{"codes":[]},"settings":"","auth":"required","params":[{"_id":"566b5afcec4a320d00a8ca77","ref":"","in":"body","required":false,"desc":"","default":"USD","type":"string","name":"base"},{"_id":"566cabbef0a5dc0d009acbc6","ref":"","in":"body","required":false,"desc":"","default":"","type":"string","name":"app_id"}],"url":"/latest.json"},"isReference":true,"order":3,"body":"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](doc:supported-currencies#alternative-black-market-and-alternative-digital-currencies)**.\n\nSome 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). \n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"\",\n  \"body\": \"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).\\n\\nYou may contact us with any feedback or questions about this feature and the returned rates at support:::at:::openexchangerates.org.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Upcoming change in ETH and LTC currencies status – 1st November 2017\",\n  \"body\": \"On 1st October 2017, **ETH** (Ether) and **LTC** (Litecoin) will move from our Alternative rates to our regular set of currency rates, meaning they will be available to all users without using the special `show_alternative` parameter.\\n\\nIf 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. You don't need to change your integration. \\n\\nHowever, if you use the (deprecated) `only_alternative` parameter to fetch LTC or ETH, you will need to modify your integration to use `show_alternative` instead. After 1st October 2017, `only_alternative` will no longer return ETH or LTC.\\n\\nPlease contact us if you need any help or support making this change, or have any questions about these rates.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Request Latest 'Alternative' Rates\"\n}\n[/block]\nAppend the `show_alternative` query parameter to your `latest.json`, `historical/` or `time-series.json` API request, like so:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"https://openexchangerates.org/api/latest.json\\n    ?app_id=YOUR_APP_ID\\n    &show_alternative=1\",\n      \"language\": \"http\"\n    },\n    {\n      \"code\": \"$.get('https://openexchangerates.org/api/latest.json', {app_id: 'YOUR_APP_ID', show_alternative: 1}, function(data) {\\n    console.log(data);\\n});\",\n      \"language\": \"javascript\",\n      \"name\": \"jQuery\"\n    }\n  ]\n}\n[/block]\nThe response format is exactly the same as the standard API response, with additional rates added to the `rates` object:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    disclaimer: \\\"https://openexchangerates.org/terms/\\\",\\n    license: \\\"https://openexchangerates.org/license/\\\",\\n    \\\"timestamp\\\": 1500652863,\\n    \\\"base\\\": \\\"USD\\\",\\n    \\\"rates\\\": {\\n        \\\"AED\\\": 3.673018,\\n        /* ... */\\n        \\\"VEF_BLKMKT\\\": 8570.78,\\n        \\\"VEF_DICOM\\\": 2700,\\n        \\\"VEF_DIPRO\\\": 10,\\n        /* ... */\\n    }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nEach new symbol can be set as the [base currency](doc:changing-base-currency), if available in the returned data set (default is USD). \n\nNB: Only currencies in the returned list can be set as a base currency.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Alternative rate symbols are not limited to standard international 3-letter ISO codes, and may have fewer or more characters (such as \\\"VEF_BLKMKT\\\"). \\n\\nYou can find a full list via the `currencies.json` route (see below), and our [list of supported currencies](doc:supported-currencies#unofficial-black-market-and-alternative-digital-cu).\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Get List Of Available Alternative Currencies\"\n}\n[/block]\nThe `show_alternative` query option can be added to requests for our `currencies.json` endpoint, to include alternative rate symbols and full currency names:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"https://openexchangerates.org/api/currencies.json\\n    ?show_alternative=1\",\n      \"language\": \"http\"\n    }\n  ]\n}\n[/block]\nYou can view a list of supported alternative rates **[here](doc:supported-currencies#alternative-black-market-and-alternative-digital-currencies)**.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Basic Code Samples\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$.get('https://openexchangerates.org/api/latest.json', {app_id: 'YOUR_APP_ID', show_alternative: 1}, function(data) {\\n    console.log(\\\"1 USD equals \\\" + data.rates.DOGE + \\\" DogeCoin.\\\");\\n    console.log(\\\"1 USD equals \\\" + data.rates.VEF_BLKMKT + \\\" Venezuelan Bolivar on the black market.\\\");\\n});\",\n      \"language\": \"javascript\",\n      \"name\": \"jQuery\"\n    },\n    {\n      \"code\": \"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.\",\n      \"language\": \"text\",\n      \"name\": \"Others...\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Combining Parameters\"\n}\n[/block]\nAlternative, digital and black-market rates can be combined with all other parameters on the latest.json endpoint:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"https://openexchangerates.org/api/latest.json\\n    ?app_id=YOUR_APP_ID\\n    &base=LTC\\n    &show_alternative=1\\n    &symbols=ETH,VEF,VEF_DIPRO,VEF_DICOM,VEF_BLKMKT,BTC,NEM\\n    &prettyprint=0\",\n      \"language\": \"http\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Changes to Alternative rates parameter\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"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.\\n\\nAlthough we will continue to support the legacy 'experimental' syntax, we strongly recommend updating your integration to the new parameter name.\",\n  \"title\": \"What happened to \\\"experimental\\\" rates?\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"What happened to the \\\"only_alternative\\\" / \\\"only_experimental\\\" parameter?\",\n  \"body\": \"The `only_alternative` (and previously, `only_experimental`) parameters enabled you to see **only** alternative rates in your API response (excluding the standard list).\\n\\nThis 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.\"\n}\n[/block]","excerpt":"Certain alternative rates aren't suitable for our primary API endpoints, but have been commonly requested by our clients (such as Dicom, Dipro and black market rates for Venezuelan Bolìvar, and a variety of digital currencies).\n\nYou may now request latest and historical rates for unofficial, black market and alternative digital currencies  by adding a simple API parameter onto your request.\n\nPlease contact us if you would like to receive data for an alternative rate or digital currency that we do not currently provide.","slug":"alternative-currencies","type":"basic","title":"Alternative Rates ('show_alternative')"}

Alternative Rates ('show_alternative')

Certain alternative rates aren't suitable for our primary API endpoints, but have been commonly requested by our clients (such as Dicom, Dipro and black market rates for Venezuelan Bolìvar, and a variety of digital currencies). You may now request latest and historical rates for unofficial, black market and alternative digital currencies by adding a simple API parameter onto your request. Please contact us if you would like to receive data for an alternative rate or digital currency that we do not currently provide.

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](doc:supported-currencies#alternative-black-market-and-alternative-digital-currencies)**. 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). [block:callout] { "type": "info", "title": "", "body": "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).\n\nYou may contact us with any feedback or questions about this feature and the returned rates at support@openexchangerates.org." } [/block] [block:callout] { "type": "warning", "title": "Upcoming change in ETH and LTC currencies status – 1st November 2017", "body": "On 1st October 2017, **ETH** (Ether) and **LTC** (Litecoin) will move from our Alternative rates to our regular set of currency rates, meaning they will be available to all users without using the special `show_alternative` parameter.\n\nIf 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. You don't need to change your integration. \n\nHowever, if you use the (deprecated) `only_alternative` parameter to fetch LTC or ETH, you will need to modify your integration to use `show_alternative` instead. After 1st October 2017, `only_alternative` will no longer return ETH or LTC.\n\nPlease contact us if you need any help or support making this change, or have any questions about these rates." } [/block] [block:api-header] { "type": "basic", "title": "Request Latest 'Alternative' Rates" } [/block] Append the `show_alternative` query parameter to your `latest.json`, `historical/` or `time-series.json` API request, like so: [block:code] { "codes": [ { "code": "https://openexchangerates.org/api/latest.json\n ?app_id=YOUR_APP_ID\n &show_alternative=1", "language": "http" }, { "code": "$.get('https://openexchangerates.org/api/latest.json', {app_id: 'YOUR_APP_ID', show_alternative: 1}, function(data) {\n console.log(data);\n});", "language": "javascript", "name": "jQuery" } ] } [/block] The response format is exactly the same as the standard API response, with additional rates added to the `rates` object: [block:code] { "codes": [ { "code": "{\n disclaimer: \"https://openexchangerates.org/terms/\",\n license: \"https://openexchangerates.org/license/\",\n \"timestamp\": 1500652863,\n \"base\": \"USD\",\n \"rates\": {\n \"AED\": 3.673018,\n /* ... */\n \"VEF_BLKMKT\": 8570.78,\n \"VEF_DICOM\": 2700,\n \"VEF_DIPRO\": 10,\n /* ... */\n }\n}", "language": "json" } ] } [/block] Each new symbol can be set as the [base currency](doc:changing-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. [block:callout] { "type": "info", "body": "Alternative rate symbols are not limited to standard international 3-letter ISO codes, and may have fewer or more characters (such as \"VEF_BLKMKT\"). \n\nYou can find a full list via the `currencies.json` route (see below), and our [list of supported currencies](doc:supported-currencies#unofficial-black-market-and-alternative-digital-cu)." } [/block] [block:api-header] { "type": "basic", "title": "Get List Of Available Alternative Currencies" } [/block] The `show_alternative` query option can be added to requests for our `currencies.json` endpoint, to include alternative rate symbols and full currency names: [block:code] { "codes": [ { "code": "https://openexchangerates.org/api/currencies.json\n ?show_alternative=1", "language": "http" } ] } [/block] You can view a list of supported alternative rates **[here](doc:supported-currencies#alternative-black-market-and-alternative-digital-currencies)**. [block:api-header] { "type": "basic", "title": "Basic Code Samples" } [/block] [block:code] { "codes": [ { "code": "$.get('https://openexchangerates.org/api/latest.json', {app_id: 'YOUR_APP_ID', show_alternative: 1}, function(data) {\n console.log(\"1 USD equals \" + data.rates.DOGE + \" DogeCoin.\");\n console.log(\"1 USD equals \" + data.rates.VEF_BLKMKT + \" Venezuelan Bolivar on the black market.\");\n});", "language": "javascript", "name": "jQuery" }, { "code": "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.", "language": "text", "name": "Others..." } ] } [/block] [block:api-header] { "type": "basic", "title": "Combining Parameters" } [/block] Alternative, digital and black-market rates can be combined with all other parameters on the latest.json endpoint: [block:code] { "codes": [ { "code": "https://openexchangerates.org/api/latest.json\n ?app_id=YOUR_APP_ID\n &base=LTC\n &show_alternative=1\n &symbols=ETH,VEF,VEF_DIPRO,VEF_DICOM,VEF_BLKMKT,BTC,NEM\n &prettyprint=0", "language": "http" } ] } [/block] [block:api-header] { "title": "Changes to Alternative rates parameter" } [/block] [block:callout] { "type": "warning", "body": "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.\n\nAlthough we will continue to support the legacy 'experimental' syntax, we strongly recommend updating your integration to the new parameter name.", "title": "What happened to \"experimental\" rates?" } [/block] [block:callout] { "type": "warning", "title": "What happened to the \"only_alternative\" / \"only_experimental\" parameter?", "body": "The `only_alternative` (and previously, `only_experimental`) parameters enabled you to see **only** alternative rates in your API response (excluding the standard list).\n\nThis 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." } [/block]