STOXR - Currency Conversion Software - Open Exchange Rates API

From Svendsen Tech PowerShell Wiki
Jump to: navigation, search

STOXR is short for Svendsen Tech Open Exchange Rates. It is extremely automation-friendly currency conversion software/shareware, with a free trial version, that accesses the Open Exchange Rates API and provides highly flexible currency conversion features, including fuzzy matching of currencies. It is primarily meant to be used by developers in its current form. It is used from the command line, not a graphical user interface. It is written in .NET / PowerShell.

The software uses the Open Exchange Rates API and is entirely dependent on this for data. You will enter a separate contract with them when registering for the API key / App ID.

Open Exchange Rates has a free plan that can be used for testing, or indefinitely, which you can sign up for here. It takes only about a minute to sign up, and as a user of their services for several years myself, I can say I have never received a single spam email from them, and for my purposes the service has been very reliable.

My software depends entirely on Open Exchange Rates web API access working. It does cache data locally upon initial retrieval for a default of 30 minutes. The time interval is set on first run to a default of 60 seconds * 30 (30 minutes) and stored on disk.

You can view and change this value (in seconds) with the functions Set-STOXRCacheInterval and Get-STOXRCacheInterval.

I strongly recommend you purchase a plan with Open Exchange Rates if you plan to use this API a lot and if you want their service to continue existing, by supporting them and also abiding by their terms if you want faster updates, shorter cache times, etc.

NB! You need to know how to start powershell.exe or powershell_ise.exe and preferrably a bit about how to use PowerShell in order to use this software in its current form. Such as how to install a module (put it in $Env:PSModulePath) and run functions.

It is written primarily for developers who want to save time - and possibly don't possess the skill set to do the same - by another developer.

First run

Here is an example of running the software for the first time and installing a free Open Exchange Rates App ID (get it here - spam-free) and then successfully converting from USD to NOK.

STOXR-trial-version-example-first-run-install-open-exchange-rates-app-ID-convert-currency.png

The same as text:

PS C:\> Import-Module STOXR
WARNING: This is a trial version of the product. You can only change to or from one single currency (both ways). The currency is 'USD' by default. In the trial software it can be changed once every 12 hours. Change to for example British Pound Sterling with Set-STOXRTrialCurrency -Currency GBP. To display the currently set trial currency, use Get-STOXRTrialCurrency. To list all supported currencies, use Get-STOXRCurrencyList.
WARNING: No Open Exchange Rates App ID has been set. You need to set it to use this software. This can be obtained at https://openexchangerates.org/ . Use Set-STOXRAppID to set it.
WARNING: You need to set the Open Exchange Rates app ID with Set-STOXRAppID before using this software.

PS C:\> Set-STOXRAppID -AppID "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

PS C:\> Convert-STOXRCurrency -Amount 1 -FromCurrency USD -ToCurrency NOK


FromAmount          : 1.0000
FromAmountNumerical : 1
FromCurrency        : USD
FromCurrencyText    : United States Dollar
ToAmount            : 7.8185
ToAmountNumerical   : 7.818513
ToCurrency          : NOK
ToCurrencyText      : Norwegian Krone
FromCurrencyPerUSD  : 1.0000
ToCurrencyPerUSD    : 7.8185
Date                : 2017-09-26 03:49:05
Precision           : 4

Example use

PS C:\> Get-STOXRCurrencyList | Select-Object -First 15 |
foreach {
    $Result = Convert-STOXRCurrency 1 $_.Name USD -Precision 3
    "1.000 $($_.Name) ($($_.Description)) is $($Result.ToAmount) United States Dollars"
}
1.000 AED (United Arab Emirates Dirham) is 0.272 United States Dollars
1.000 AFN (Afghan Afghani) is 0.015 United States Dollars
1.000 ALL (Albanian Lek) is 0.009 United States Dollars
1.000 AMD (Armenian Dram) is 0.002 United States Dollars
1.000 ANG (Netherlands Antillean Guilder) is 0.562 United States Dollars
1.000 AOA (Angolan Kwanza) is 0.006 United States Dollars
1.000 ARS (Argentine Peso) is 0.057 United States Dollars
1.000 AUD (Australian Dollar) is 0.782 United States Dollars
1.000 AWG (Aruban Florin) is 0.557 United States Dollars
1.000 AZN (Azerbaijani Manat) is 0.588 United States Dollars
1.000 BAM (Bosnia-Herzegovina Convertible Mark) is 0.601 United States Dollars
1.000 BBD (Barbadian Dollar) is 0.500 United States Dollars
1.000 BDT (Bangladeshi Taka) is 0.012 United States Dollars
1.000 BGN (Bulgarian Lev) is 0.600 United States Dollars
1.000 BHD (Bahraini Dinar) is 2.652 United States Dollars

STOXR-example-use2.png


To Excel very easily, like this:


STOXR-example-use-Excel.png


As text:

PS C:\> Get-STOXRCurrencyList | ForEach-Object {
    Convert-STOXRCurrency -Amount 1 -From USD -To $_.Name
} | Export-Csv -UseCulture -Path C:\temp\currencies.csv -NoTypeInformation

PS C:\> C:\temp\currencies.csv

Built-in help

Remember that there is default, built-in help for all the functions you will need to use, so you can always type:

Get-Help Verb-STOXRFunctionName

e.g.:

Get-Help Set-STOXRAppID

The software in its current form is not optimized for speed or efficiency with regards to resource usage, but provides extreme convenience and saves you the tedious task of writing a lot of code to perform similar tasks, probably less feature-rich than I've invested time in making it as well.

Being built entirely in PowerShell, the built-in shell and scripting langauge and automation framework in Microsoft Windows operating systems, STOXR is extremely automation-friendly. It can also quite seamlessly be integrated with other .NET languages accessing these PowerShell functions to do the heavy lifting - languages such as C# and VB.NET. You can also integrate it with ASP.NET and other web frameworks if you so desire.

Requirements

  • PowerShell / Windows Management Framework version 3 or higher.
  • .NET Framework version 4.0 or higher (required for PowerShell version 3).
  • An Open Exchange Rates App ID / API key (sign up here on their site - they have a free plan for indefinite use, and send no spam).
  • Web access to the Open Exchange Rates API.
  • Optionally a STOXR software module license key to unlock full functionality. See the bottom of the article for that.

NB! The proxy features are currently untested since I don't have access to a test environment of that nature.

Limitations of the trial version

  • The trial version of STOXR can only convert between one currency (default is USD) and another currency, both to and from / both ways. This means you can convert from USD to GBP and from USD to EUR, and the other way around, but not from GBP to EUR directly. In the registered version this limitation does not exist and you can freely convert between all currencies. At the time of writing (2017, September), there are 168 available currencies in the Open Exchange Rates API.
  • The trial currency can be changed once every 12 hours. The first change is immediately available.
  • The -FuzzyInput parameter does not work properly in the trial version, it will always complain that one currency is not USD or the currently set trial currency.

All exported functions/commands

PS C:\> Get-Command -Module STOXR | Format-Table -AutoSize

CommandType Name                   Version Source
----------- ----                   ------- ------
Function    Convert-STOXRCurrency  1.0.0.7 stoxr 
Function    Get-STOXRAppID         1.0.0.7 stoxr 
Function    Get-STOXRCacheInterval 1.0.0.7 stoxr 
Function    Get-STOXRCurrencyList  1.0.0.7 stoxr 
Function    Get-STOXRDebugInfo     1.0.0.7 stoxr 
Function    Get-STOXRProxy         1.0.0.7 stoxr 
Function    Get-STOXRTrialCurrency 1.0.0.7 stoxr 
Function    Register-STOXR         1.0.0.7 stoxr 
Function    Set-STOXRAppID         1.0.0.7 stoxr 
Function    Set-STOXRCacheInterval 1.0.0.7 stoxr 
Function    Set-STOXRProxy         1.0.0.7 stoxr 
Function    Set-STOXRTrialCurrency 1.0.0.7 stoxr 
Function    Unregister-STOXR       1.0.0.7 stoxr 

NB! The proxy functions are currently untested! I will investigate upon receiving feedback, if necessary. I have no access to such a testing environment currently.

Fuzzy currency name matching

This does not work properly in the trial version. The error you will get when trying a fuzzy trial currency, with the trial version, is:

PS C:\> $Result = Convert-STOXRCurrency -Amount 1 -FromCurrency "united states" -ToCurrency swedish
WARNING: This product is not registered, so the limitations apply that either the 'From' or 'To' currency needs to be 'USD' (default USD) - and that -FuzzyInput does not work. The trial currency can be changed once every 12 hours with the command Set-STOXRTrialCurrency. Register the product to unlock full functionality.

If you specify the currency abbreviation "USD", or the trial currency you changed to, explicitly, it works with fuzzy matching on the other currency.

Registering the software

Go to my sales and license retrieval link provider MyCommerce/Share-It from here and buy the license you need, then register the software using the command Register-STOXR. Internet access is not required for registration, but you need it to get the license in the first place.

Here I register the software using a license, using the function Register-STOXR.

PS C:\> help Register-STOXR

NAME
    Register-STOXR
    
SYNOPSIS
    Use the license key you bought and received to register the Svendsen Tech 
    Open Exchange Rates module.
    This unlocks the full functionality and allows you to convert between 
    any/multiple currencies.
    
    
SYNTAX
    Register-STOXR [[-LicenseKey] <String>] [-RefreshUsingExistingLicense] 
    [<CommonParameters>]

... and then I register it like this:

PS C:\> Register-STOXR -LicenseKey 'xxxxx-xxxxxxxxxxxx-xxxxxxxxxx'
Successfully registered the Svendsen Tech Open Exchange Rates module.

Then we return to the fuzzy matching

If there is a space in the text you enter, you need to surround it with quotes. Single or double quotes work (and other unicode quote signs).

This time around it works better.

PS C:\> $Result = Convert-STOXRCurrency -Amount 1 -FromCurrency "united states" `
    -ToCurrency swedish
WARNING: Performing first-run operation of setting currency exchange data refresh interval to 30 * 60 seconds (30 minutes). Use Set-STOXRCacheInterval to change it.


PS C:\> $Result


FromAmount          : 1.0000
FromAmountNumerical : 1
FromCurrency        : USD
FromCurrencyText    : United States Dollar
ToAmount            : 8.0393
ToAmountNumerical   : 8.039254
ToCurrency          : SEK
ToCurrencyText      : Swedish Krona
FromCurrencyPerUSD  : 1.0000
ToCurrencyPerUSD    : 8.0393
Date                : 2017-09-26 03:49:05
Precision           : 4

More than one fuzzy currency match

If there's more than one from or to currency match, you will be presented with a warning and a list of all the currencies that matched according to my algorithm.

Examples with pound, dollar and Scandinavian currencies (krone/krona - which incidentally means "crown", for some random linguistic elucidation of the masses):

PS C:\> Convert-STOXRCurrency 1 USD -To pound
WARNING: Multiple hits (12) for "to" currency:
EGP, Egyptian Pound
FKP, Falkland Islands Pound
GBP, British Pound Sterling
GGP, Guernsey Pound
GIP, Gibraltar Pound
IMP, Manx pound
JEP, Jersey Pound
LBP, Lebanese Pound
SDG, Sudanese Pound
SHP, Saint Helena Pound
SSP, South Sudanese Pound
SYP, Syrian Pound

PS C:\> Convert-STOXRCurrency 1 USD -To dollar
WARNING: Multiple hits (23) for "to" currency:
AUD, Australian Dollar
BBD, Barbadian Dollar
BMD, Bermudan Dollar
BND, Brunei Dollar
BSD, Bahamian Dollar
BZD, Belize Dollar
CAD, Canadian Dollar
FJD, Fijian Dollar
GYD, Guyanaese Dollar
HKD, Hong Kong Dollar
JMD, Jamaican Dollar
KYD, Cayman Islands Dollar
LRD, Liberian Dollar
NAD, Namibian Dollar
NZD, New Zealand Dollar
SBD, Solomon Islands Dollar
SGD, Singapore Dollar
SRD, Surinamese Dollar
TTD, Trinidad and Tobago Dollar
TWD, New Taiwan Dollar
USD, United States Dollar
XCD, East Caribbean Dollar
ZWL, Zimbabwean Dollar

PS C:\> Convert-STOXRCurrency 1 USD -To kron
WARNING: Multiple hits (3) for "to" currency:
DKK, Danish Krone
NOK, Norwegian Krone
SEK, Swedish Krona

A list of all currently supported currencies

Use the command Get-STOXRCurrencyList to list all the available currencies to convert to and from. This depends entirely on what's available in the Open Exchange Rates API. The list is dynamically retrieved, not hard-coded.

As of 2017-09-26 the list is as follows:

PS C:\> Get-STOXRCurrencyList -AutoSizeTable

Name Description                        
---- -----------                        
AED  United Arab Emirates Dirham        
AFN  Afghan Afghani                     
ALL  Albanian Lek                       
AMD  Armenian Dram                      
ANG  Netherlands Antillean Guilder      
AOA  Angolan Kwanza                     
ARS  Argentine Peso                     
AUD  Australian Dollar                  
AWG  Aruban Florin                      
AZN  Azerbaijani Manat                  
BAM  Bosnia-Herzegovina Convertible Mark
BBD  Barbadian Dollar                   
BDT  Bangladeshi Taka                   
BGN  Bulgarian Lev                      
BHD  Bahraini Dinar                     
BIF  Burundian Franc                    
BMD  Bermudan Dollar                    
BND  Brunei Dollar                      
BOB  Bolivian Boliviano                 
BRL  Brazilian Real                     
BSD  Bahamian Dollar                    
BTC  Bitcoin                            
BTN  Bhutanese Ngultrum                 
BWP  Botswanan Pula                     
BYN  Belarusian Ruble                   
BZD  Belize Dollar                      
CAD  Canadian Dollar                    
CDF  Congolese Franc                    
CHF  Swiss Franc                        
CLF  Chilean Unit of Account (UF)       
CLP  Chilean Peso                       
CNH  Chinese Yuan (Offshore)            
CNY  Chinese Yuan                       
COP  Colombian Peso                     
CRC  Costa Rican Colón                  
CUC  Cuban Convertible Peso             
CUP  Cuban Peso                         
CVE  Cape Verdean Escudo                
CZK  Czech Republic Koruna              
DJF  Djiboutian Franc                   
DKK  Danish Krone                       
DOP  Dominican Peso                     
DZD  Algerian Dinar                     
EGP  Egyptian Pound                     
ERN  Eritrean Nakfa                     
ETB  Ethiopian Birr                     
EUR  Euro                               
FJD  Fijian Dollar                      
FKP  Falkland Islands Pound             
GBP  British Pound Sterling             
GEL  Georgian Lari                      
GGP  Guernsey Pound                     
GHS  Ghanaian Cedi                      
GIP  Gibraltar Pound                    
GMD  Gambian Dalasi                     
GNF  Guinean Franc                      
GTQ  Guatemalan Quetzal                 
GYD  Guyanaese Dollar                   
HKD  Hong Kong Dollar                   
HNL  Honduran Lempira                   
HRK  Croatian Kuna                      
HTG  Haitian Gourde                     
HUF  Hungarian Forint                   
IDR  Indonesian Rupiah                  
ILS  Israeli New Sheqel                 
IMP  Manx pound                         
INR  Indian Rupee                       
IQD  Iraqi Dinar                        
IRR  Iranian Rial                       
ISK  Icelandic Króna                    
JEP  Jersey Pound                       
JMD  Jamaican Dollar                    
JOD  Jordanian Dinar                    
JPY  Japanese Yen                       
KES  Kenyan Shilling                    
KGS  Kyrgystani Som                     
KHR  Cambodian Riel                     
KMF  Comorian Franc                     
KPW  North Korean Won                   
KRW  South Korean Won                   
KWD  Kuwaiti Dinar                      
KYD  Cayman Islands Dollar              
KZT  Kazakhstani Tenge                  
LAK  Laotian Kip                        
LBP  Lebanese Pound                     
LKR  Sri Lankan Rupee                   
LRD  Liberian Dollar                    
LSL  Lesotho Loti                       
LYD  Libyan Dinar                       
MAD  Moroccan Dirham                    
MDL  Moldovan Leu                       
MGA  Malagasy Ariary                    
MKD  Macedonian Denar                   
MMK  Myanma Kyat                        
MNT  Mongolian Tugrik                   
MOP  Macanese Pataca                    
MRO  Mauritanian Ouguiya                
MUR  Mauritian Rupee                    
MVR  Maldivian Rufiyaa                  
MWK  Malawian Kwacha                    
MXN  Mexican Peso                       
MYR  Malaysian Ringgit                  
MZN  Mozambican Metical                 
NAD  Namibian Dollar                    
NGN  Nigerian Naira                     
NIO  Nicaraguan Córdoba                 
NOK  Norwegian Krone                    
NPR  Nepalese Rupee                     
NZD  New Zealand Dollar                 
OMR  Omani Rial                         
PAB  Panamanian Balboa                  
PEN  Peruvian Nuevo Sol                 
PGK  Papua New Guinean Kina             
PHP  Philippine Peso                    
PKR  Pakistani Rupee                    
PLN  Polish Zloty                       
PYG  Paraguayan Guarani                 
QAR  Qatari Rial                        
RON  Romanian Leu                       
RSD  Serbian Dinar                      
RUB  Russian Ruble                      
RWF  Rwandan Franc                      
SAR  Saudi Riyal                        
SBD  Solomon Islands Dollar             
SCR  Seychellois Rupee                  
SDG  Sudanese Pound                     
SEK  Swedish Krona                      
SGD  Singapore Dollar                   
SHP  Saint Helena Pound                 
SLL  Sierra Leonean Leone               
SOS  Somali Shilling                    
SRD  Surinamese Dollar                  
SSP  South Sudanese Pound               
STD  São Tomé and Príncipe Dobra        
SVC  Salvadoran Colón                   
SYP  Syrian Pound                       
SZL  Swazi Lilangeni                    
THB  Thai Baht                          
TJS  Tajikistani Somoni                 
TMT  Turkmenistani Manat                
TND  Tunisian Dinar                     
TOP  Tongan Pa'anga                     
TRY  Turkish Lira                       
TTD  Trinidad and Tobago Dollar         
TWD  New Taiwan Dollar                  
TZS  Tanzanian Shilling                 
UAH  Ukrainian Hryvnia                  
UGX  Ugandan Shilling                   
USD  United States Dollar               
UYU  Uruguayan Peso                     
UZS  Uzbekistan Som                     
VEF  Venezuelan Bolívar Fuerte          
VND  Vietnamese Dong                    
VUV  Vanuatu Vatu                       
WST  Samoan Tala                        
XAF  CFA Franc BEAC                     
XAG  Silver Ounce                       
XAU  Gold Ounce                         
XCD  East Caribbean Dollar              
XDR  Special Drawing Rights             
XOF  CFA Franc BCEAO                    
XPD  Palladium Ounce                    
XPF  CFP Franc                          
XPT  Platinum Ounce                     
YER  Yemeni Rial                        
ZAR  South African Rand                 
ZMW  Zambian Kwacha                     
ZWL  Zimbabwean Dollar                  

The -FuzzyInput parameter in the full version

If you want to enter in text in a string more like a human, you can do that too, with the -FuzzyInput parameter, but it does not work in the trial version.

PS C:\> Convert-STOXRCurrency -FuzzyInput '1 norwegian in swedi'


FromAmount          : 1.0000
FromAmountNumerical : 1
FromCurrency        : NOK
FromCurrencyText    : Norwegian Krone
ToAmount            : 1.0282
ToAmountNumerical   : 1.0282331179854788244260769276
ToCurrency          : SEK
ToCurrencyText      : Swedish Krona
FromCurrencyPerUSD  : 7.8185
ToCurrencyPerUSD    : 8.0393
Date                : 2017-09-26 03:49:05
Precision           : 4

The -AsString and -Precision parameters

If you want to get the currency conversion results back in a more condensed, human-readable string format, you can use the parameter -AsString and I also demonstrate how the parameter -Precision works.

PS C:\> Convert-STOXRCurrency 1 dkk nok -AsString
1.0000 DKK (Danish Krone at 6.2739/USD) is 1.2459 NOK (Norwegian Krone, 7.8169/USD). Date: 2017-09-26 04:19:19.

Rounded to two digits only with "-Precision 2".

PS C:\> Convert-STOXRCurrency 1 dkk nok -AsString -Precision 2
1.00 DKK (Danish Krone at 6.27/USD) is 1.25 NOK (Norwegian Krone, 7.82/USD). Date: 2017-09-26 04:19:19.

PS C:\> Convert-STOXRCurrency 1 usd dkk -Precision 2


FromAmount          : 1.00
FromAmountNumerical : 1
FromCurrency        : USD
FromCurrencyText    : United States Dollar
ToAmount            : 6.27
ToAmountNumerical   : 6.27387
ToCurrency          : DKK
ToCurrencyText      : Danish Krone
FromCurrencyPerUSD  : 1.00
ToCurrencyPerUSD    : 6.27
Date                : 2017-09-26 04:19:19
Precision           : 2

Potential use and features

  • Convert currencies easily, programmatically using .NET framework software and PowerShell.
  • Comprehensive list of currencies reliably provided by Open Exchange Rates (OXR). Easy App ID / API key registration. Spam-free.
  • Fuzzy/partial currency matching.
  • Nearly feature-complete as an automation tool as-is.
  • Build CSV files (Get-Help Export-Csv) with currency data collected at once - or over time using Windows scheduled tasks, a service or simply a while loop you initiate manually - or automatically - for a specific timeframe on-demand.
  • Excel reports are easy since CSV files are read natively by Excel. Use a PSExcel PowerShell module or similar to create XLS/XLSX files directly.
  • Generate HTML reports with the desired currency exchange rates collected with STOXR (Get-Help ConvertTo-Html, then add some CSS in the -Head).
  • Build currency graphs over time using this software in combination with other software. Svendsen Tech plans to build a GUI and to include this, but has no time estimate for when at this point.

Download and/or buy a license

  • STOXR.zip download - download the trial version of the software. All you need to unlock full functionality is a text license key later. Remember to unblock the zip file before extracting.

You can always download the latest version here or from the PowerShell gallery, where I will keep the software up-to-date. Old keys will work for new software unless I provide a significantly different product (GUI and graphs are on the to do list), for which a new license will apply. Previous customers will get a significant discount.

If you have Windows Management Framework 5 / PowerShell version 5 or higher (default in Windows 10 / Server 2016 and up), you can install the module from Microsoft's PowerShell gallery site where it has also been published in the trial version:

Install-Module STOXR # requires admin console, installs for all users, by default in $Env:ProgramFiles\WindowsPowerShell\Modules

or:

Install-Module STOXR -Scope CurrentUser # installs in your profile directory for your user only

or to update the module:

Update-Module -Name STOXR

or:

Save-Module -Path X:\SomeDirectory\STOXR # to download and inspect the code

The pricing model for STOXR is as follows:


  • 1 site/individual license: USD $299


Order-now-button.png


One license entitles you to use the software freely indefinitely, combined with the Open Exchange Rates terms you and they agree upon when you register for an App ID / API key on their website (sign up here). Free plan available - no spam.

"Use" means within one (part of an) organization/company or as one private individual.

Here are the license terms. It's a simple, slightly modified MIT license.

If you have questions, please contact Svendsen Tech at sales@svendsentech.no or support@svendsentech.no (legacy mail: svendsentech@gmail.com ).

My sales and license key provider is MyCommerce/Share-It, a Digital River company.

You can purchase the software by clicking this link, or the order button above, completing the payment process and getting immediate access to the license key.

To get in touch with MyCommerce customer service and refer to my vendor ID, use this link.

Version history: File:STOXR.zip - latest update: 2017-10-15. Fix breaking syntax error.


Keywords: convert currency, currency converter software in .NET, CSV, Excel, convert USD to EUR, .xls, .xlsx, currency conversion software, convert EUR to USD, convert between any currency, currencies, all currencies, .NET currency conversion software, business, business software, ASP.NET, VB.NET, C#, F#, Visual Basic, automation framework, Microsoft Windows, PowerShell/.NET, PowerShell version 3, bitcoin, Japanese Yen, Chinese Yen, Australian Dollars, Euro, .NET framework, bank, banking, finance, financial currency conversion, enterprise, comprehensive list of currencies, convert USD to any currency, free trial currency software, shareware, automation, DevOps, objects, PowerShell objects