v1.3.0 — add hourly endpoint, EU server support, math/date_type params

Author: forexrateapi

README.md

@@ -20,6 +20,24 @@ const api = require('forexrateapi');
 api.setAPIKey('SET_YOUR_API_KEY_HERE');
 await api.fetchLive('USD', ['AUD', 'CAD', 'GBP', 'JPY']);
 ```
+---
+## Server Regions
+
+ForexRateAPI provides two regional endpoints. Choose the one closest to your servers for optimal performance.
+
+| Region | Base URL |
+|--------|----------|
+| United States (default) | `https://api.forexrateapi.com/v1` |
+| Europe | `https://api-eu.forexrateapi.com/v1` |
+
+```js
+api.setAPIKey('SET_YOUR_API_KEY_HERE');
+
+// Default is US server
+// Switch to EU server:
+api.setServer('eu');
+```
+
 ---
 ## Documentation
 
@@ -32,6 +50,15 @@ In order to use this library, you must first call this function with an API key.
 ```js
 api.setAPIKey('SET_YOUR_API_KEY_HERE');
 ```
+---
+#### setServer(server)
+
+- `server` <[string]> Pass `'eu'` to use the EU server (`api-eu.forexrateapi.com`), or `'us'` for the US server. Defaults to US if not specified.
+
+```js
+api.setServer('eu');
+```
+
 ---
 #### fetchSymbols()
 ```js
@@ -41,10 +68,11 @@ await api.fetchSymbols();
 [Link](https://forexrateapi.com/documentation#api_symbol)
 
 ---
-#### fetchLive(base, currencies)
+#### fetchLive(base, currencies, math)
 
 - `base` <[string]> Optional. Pass in a base currency, defaults to USD.
 - `currencies` <[Array]<[string]>> Optional. Pass in an array of currencies to return values for.
+- `math` <[string]> Optional. Pass in a math expression to apply to the rates.
 
 ```js
 await api.fetchLive('USD', ['AUD', 'CAD', 'GBP', 'JPY']);
@@ -65,6 +93,22 @@ await api.fetchHistorical('2024-02-05', 'USD', ['AUD', 'CAD', 'GBP', 'JPY']);
 
 [Link](https://forexrateapi.com/documentation#api_historical)
 
+---
+#### hourly(base, currency, startDate, endDate, math, dateType)
+
+- `base` <[string]> Optional. Pass in a base currency, defaults to USD.
+- `currency` <[string]> Required. Specify currency you would like to get hourly rates for.
+- `startDate` <[string]> Required. Specify the start date using the format `YYYY-MM-DD`.
+- `endDate` <[string]> Required. Specify the end date using the format `YYYY-MM-DD`.
+- `math` <[string]> Optional. Pass in a math expression to apply to the rates.
+- `dateType` <[string]> Optional. Pass in a date type, overrides date parameters if passed in.
+
+```js
+await api.hourly('USD', 'EUR', '2024-02-05', '2024-02-05');
+```
+
+[Link](https://forexrateapi.com/documentation#api_hourly)
+
 ---
 #### ohlc(base, currency, date, dateType)
 
@@ -94,10 +138,10 @@ await api.convert('USD', 'EUR', 100, '2024-02-05');
 [Link](https://forexrateapi.com/documentation#api_convert)
 
 ---
-#### timeframe(start_date, end_date, base, currencies)
+#### timeframe(startDate, endDate, base, currencies)
 
-- `start_date` <[string]> Required. Specify the start date of your timeframe using the format `YYYY-MM-DD`.
-- `end_date` <[string]> Required. Specify the end date of your timeframe using the format `YYYY-MM-DD`.
+- `startDate` <[string]> Required. Specify the start date of your timeframe using the format `YYYY-MM-DD`.
+- `endDate` <[string]> Required. Specify the end date of your timeframe using the format `YYYY-MM-DD`.
 - `base` <[string]> Optional. Pass in a base currency, defaults to USD.
 - `currencies` <[Array]<[string]>> Optional. Pass in an array of currencies to return values for.
 
@@ -108,12 +152,13 @@ await api.timeframe('2024-02-05', '2024-02-06', 'USD', ['AUD', 'CAD', 'GBP', 'JP
 [Link](https://forexrateapi.com/documentation#api_timeframe)
 
 ---
-#### change(start_date, end_date, base, currencies)
+#### change(startDate, endDate, base, currencies, dateType)
 
-- `start_date` <[string]> Required. Specify the start date of your timeframe using the format `YYYY-MM-DD`.
-- `end_date` <[string]> Required. Specify the end date of your timeframe using the format `YYYY-MM-DD`.
+- `startDate` <[string]> Required. Specify the start date of your timeframe using the format `YYYY-MM-DD`.
+- `endDate` <[string]> Required. Specify the end date of your timeframe using the format `YYYY-MM-DD`.
 - `base` <[string]> Optional. Pass in a base currency, defaults to USD.
 - `currencies` <[Array]<[string]>> Optional. Pass in an array of currencies to return values for.
+- `dateType` <[string]> Optional. Pass in a date type, overrides date parameters if passed in.
 
 ```js
 await api.change('2024-02-05', '2024-02-06', 'USD', ['AUD', 'CAD', 'GBP', 'JPY']);
@@ -153,4 +198,4 @@ For support, get in touch using [this form](https://forexrateapi.com/contact).
 
 [array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array 'Array'
 [number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type 'Number'
-[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type 'String'
+[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type 'String'

example/index.js

@@ -5,6 +5,9 @@ const apiKey = 'REPLACE_ME';
 (async function() {
   api.setAPIKey(apiKey);
 
+  // Or use EU server:
+  // api.setServer('eu');
+
   var result;
 
   result = await api.fetchSymbols();
@@ -16,6 +19,9 @@ const apiKey = 'REPLACE_ME';
   result = await api.fetchHistorical('2024-02-05', 'USD', ['AUD', 'CAD', 'GBP', 'JPY']);
   console.log(result.data);
 
+  result = await api.hourly('USD', 'EUR', '2024-02-05', '2024-02-05');
+  console.log(result.data);
+
   result = await api.ohlc('USD', 'EUR', '2024-02-05', null);
   console.log(result.data);
 

index.js

@@ -1,11 +1,17 @@
 (function() {
   const axios = require('axios');
 
+  const SERVERS = {
+    us: 'https://api.forexrateapi.com/v1',
+    eu: 'https://api-eu.forexrateapi.com/v1'
+  };
+
   var apiKey;
+  var baseUrl = SERVERS.us;
 
   function removeEmpty(obj) {
     for (var propName in obj) {
-      if (obj[propName] === null || obj[propName] === undefined || obj[propName] == '') {
+      if (obj[propName] === null || obj[propName] === undefined || obj[propName] === '') {
         delete obj[propName];
       }
     }
@@ -16,29 +22,34 @@
     this.apiKey = apiKey;
   };
 
+  exports.setServer = function(server) {
+    baseUrl = SERVERS[server] || SERVERS.us;
+  };
+
   exports.fetchSymbols = function() {
     return axios({
-      url: 'https://api.forexrateapi.com/v1/symbols',
+      url: `${baseUrl}/symbols`,
       params: {
         api_key: this.apiKey,
       },
     });
   };
 
-  exports.fetchLive = function(base, currencies) {
+  exports.fetchLive = function(base, currencies, math) {
     return axios({
-      url: 'https://api.forexrateapi.com/v1/latest',
+      url: `${baseUrl}/latest`,
       params: removeEmpty({
         api_key: this.apiKey,
         base: base,
         currencies: (currencies || []).join(','),
+        math: math,
       }),
     });
   };
 
   exports.fetchHistorical = function(date, base, currencies) {
     return axios({
-      url: `https://api.forexrateapi.com/v1/${date}`,
+      url: `${baseUrl}/${date}`,
       params: removeEmpty({
         api_key: this.apiKey,
         base: base,
@@ -47,9 +58,24 @@
     });
   };
 
+  exports.hourly = function(base, currency, startDate, endDate, math, dateType) {
+    return axios({
+      url: `${baseUrl}/hourly`,
+      params: removeEmpty({
+        api_key: this.apiKey,
+        base: base,
+        currency: currency,
+        start_date: startDate,
+        end_date: endDate,
+        math: math,
+        date_type: dateType,
+      }),
+    });
+  };
+
   exports.ohlc = function(base, currency, date, dateType) {
     return axios({
-      url: 'https://api.forexrateapi.com/v1/ohlc',
+      url: `${baseUrl}/ohlc`,
       params: removeEmpty({
         api_key: this.apiKey,
         base: base,
@@ -62,7 +88,7 @@
 
   exports.convert = function(from, to, amount, date) {
     return axios({
-      url: 'https://api.forexrateapi.com/v1/convert',
+      url: `${baseUrl}/convert`,
       params: removeEmpty({
         api_key: this.apiKey,
         from: from,
@@ -75,7 +101,7 @@
 
   exports.timeframe = function(startDate, endDate, base, currencies) {
     return axios({
-      url: 'https://api.forexrateapi.com/v1/timeframe',
+      url: `${baseUrl}/timeframe`,
       params: removeEmpty({
         api_key: this.apiKey,
         start_date: startDate,
@@ -86,22 +112,23 @@
     });
   };
 
-  exports.change = function(startDate, endDate, base, currencies) {
+  exports.change = function(startDate, endDate, base, currencies, dateType) {
     return axios({
-      url: 'https://api.forexrateapi.com/v1/change',
+      url: `${baseUrl}/change`,
       params: removeEmpty({
         api_key: this.apiKey,
         start_date: startDate,
         end_date: endDate,
         base: base,
         currencies: (currencies || []).join(','),
+        date_type: dateType,
       }),
     });
   }
 
-  exports.usage = function(base, currency) {
+  exports.usage = function() {
     return axios({
-      url: 'https://api.forexrateapi.com/v1/usage',
+      url: `${baseUrl}/usage`,
       params: removeEmpty({
         api_key: this.apiKey,
       }),

package.json

@@ -1,6 +1,6 @@
 {
   "name": "forexrateapi",
-  "version": "1.1.2",
+  "version": "1.3.0",
   "description": "Official Node.js Library for ForexRateAPI",
   "main": "index.js",
   "scripts": {
@@ -9,7 +9,7 @@
   "author": "ForexRateAPI",
   "license": "MIT",
   "dependencies": {
-    "axios": "^1.6.7"
+    "axios": "^1.13.5"
   },
   "homepage": "https://forexrateapi.com",
   "repository": {
@@ -19,7 +19,7 @@
   "keywords": [
     "foreign exchange rates",
     "forex",
-    "currency coversion",
+    "currency conversion",
     "currency price",
     "currency rates",
     "api"