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

Author: forexrateapi

README.md

@@ -16,7 +16,28 @@ from forexrateapi.client import Client
 
 api_key = 'SET_YOUR_API_KEY_HERE'
 client = Client(api_key)
+
+# Or use EU server:
+# client = Client(api_key, server='eu')
+```
+---
+## 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` |
+
+```python
+# Default (US)
+client = Client('SET_YOUR_API_KEY_HERE')
+
+# Europe
+client = Client('SET_YOUR_API_KEY_HERE', server='eu')
 ```
+
 ---
 ## Documentation
 
@@ -28,10 +49,20 @@ client.fetchSymbols()
 [Link](https://forexrateapi.com/documentation#api_symbol)
 
 ---
-#### fetchLive(base, currencies)
+#### 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.
+
+```python
+client.setServer('eu')
+```
+
+---
+#### fetchLive(base, currencies, math)
 
 - `base` <[string]> Optional. Pass in a base currency, defaults to USD.
 - `currencies` <[List]<[string]>> Optional. Pass in an list of currencies to return values for.
+- `math` <[string]> Optional. Pass in a math expression to apply to the rates.
 
 ```python
 client.fetchLive(base='USD', currencies=['AUD', 'CAD', 'GBP', 'JPY'])
@@ -52,6 +83,22 @@ client.fetchHistorical(date='2024-02-05', base='USD', currencies=['AUD', 'CAD',
 
 [Link](https://forexrateapi.com/documentation#api_historical)
 
+---
+#### hourly(base, currency, start_date, end_date, math, date_type)
+
+- `base` <[string]> Optional. Pass in a base currency, defaults to USD.
+- `currency` <[string]> Required. Specify currency you would like to get hourly rates for.
+- `start_date` <[string]> Required. Specify the start date using the format `YYYY-MM-DD`.
+- `end_date` <[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.
+- `date_type` <[string]> Optional. Pass in a date type, overrides date parameters if passed in.
+
+```python
+client.hourly(base='USD', currency='EUR', start_date='2024-02-05', end_date='2024-02-05')
+```
+
+[Link](https://forexrateapi.com/documentation#api_hourly)
+
 ---
 #### ohlc(base, currency, date, date_type)
 
@@ -95,12 +142,13 @@ client.timeframe(start_date='2024-02-05', end_date='2024-02-06', base='USD', cur
 [Link](https://forexrateapi.com/documentation#api_timeframe)
 
 ---
-#### change(start_date, end_date, base, currencies)
+#### change(start_date, end_date, base, currencies, date_type)
 
 - `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`.
 - `base` <[string]> Optional. Pass in a base currency, defaults to USD.
 - `currencies` <[List]<[string]>> Optional. Pass in an list of currencies to return values for.
+- `date_type` <[string]> Optional. Pass in a date type, overrides date parameters if passed in.
 
 ```python
 client.change(start_date='2024-02-05', end_date='2024-02-06', base='USD', currencies=['AUD', 'CAD', 'GBP', 'JPY'])
@@ -139,4 +187,4 @@ For support, get in touch using [this form](https://forexrateapi.com/contact).
 
 [List]: https://www.w3schools.com/python/python_datatypes.asp 'List'
 [number]: https://www.w3schools.com/python/python_datatypes.asp 'Number'
-[string]: https://www.w3schools.com/python/python_datatypes.asp 'String'
+[string]: https://www.w3schools.com/python/python_datatypes.asp 'String'

example.py

@@ -3,25 +3,31 @@
 api_key = 'REPLACE_ME'
 client = Client(api_key)
 
+# Or use EU server:
+# client = Client(api_key, server='eu')
+
 result = client.fetchSymbols()
 print(result)
 
 result = client.fetchLive(base='USD', currencies=['AUD', 'CAD', 'GBP', 'JPY'])
 print(result)
 
-result = client.fetchHistorical(date='2021-04-05', base='USD', currencies=['AUD', 'CAD', 'GBP', 'JPY'])
+result = client.fetchHistorical(date='2024-02-05', base='USD', currencies=['AUD', 'CAD', 'GBP', 'JPY'])
+print(result)
+
+result = client.hourly(base='USD', currency='EUR', start_date='2024-02-05', end_date='2024-02-05')
 print(result)
 
-result = client.ohlc(base='USD', currency='EUR', date='2021-04-05', date_type=None)
+result = client.ohlc(base='USD', currency='EUR', date='2024-02-05', date_type=None)
 print(result)
 
-result = client.convert(from_currency='USD', to_currency='EUR', amount=100, date='2021-04-05')
+result = client.convert(from_currency='USD', to_currency='EUR', amount=100, date='2024-02-05')
 print(result)
 
-result = client.timeframe(start_date='2021-04-05', end_date='2021-04-06', base='USD', currencies=['AUD', 'CAD', 'GBP', 'JPY'])
+result = client.timeframe(start_date='2024-02-05', end_date='2024-02-06', base='USD', currencies=['AUD', 'CAD', 'GBP', 'JPY'])
 print(result)
 
-result = client.change(start_date='2021-04-05', end_date='2021-04-06', base='USD', currencies=['AUD', 'CAD', 'GBP', 'JPY'])
+result = client.change(start_date='2024-02-05', end_date='2024-02-06', base='USD', currencies=['AUD', 'CAD', 'GBP', 'JPY'])
 print(result)
 
 result = client.usage()

forexrateapi/client.py

@@ -1,75 +1,96 @@
 import requests
 
 class Client(object):
-    base_url = 'https://api.forexrateapi.com/v1'
+    SERVERS = {
+        'us': 'https://api.forexrateapi.com/v1',
+        'eu': 'https://api-eu.forexrateapi.com/v1'
+    }
 
     def _removeEmpty(self, params):
-        return {key:value for key,value in params.items() if value != ''}
+        return {key: value for key, value in params.items() if value is not None and value != ''}
 
-    def __init__(self, api_key):
+    def __init__(self, api_key, server='us'):
+        self.base_url = self.SERVERS.get(server, self.SERVERS['us'])
         self.client = requests.Session()
         self.client.params.update({'api_key': api_key})
 
+    def setServer(self, server):
+        self.base_url = self.SERVERS.get(server, self.SERVERS['us'])
+
     def fetchSymbols(self):
         response = self.client.get(f'{self.base_url}/symbols')
         return response.json()
 
-    def fetchLive(self, base='', currencies=[]):
+    def fetchLive(self, base='', currencies=None, math=''):
         params = self._removeEmpty({
             'base': base,
-            'currencies': ','.join(currencies)
+            'currencies': ','.join(currencies or []),
+            'math': math,
         })
         response = self.client.get(f'{self.base_url}/latest', params=params)
         return response.json()
 
-    def fetchHistorical(self, date, base='', currencies=[]):
+    def fetchHistorical(self, date, base='', currencies=None):
         params = self._removeEmpty({
             'base': base,
-            'currencies': ','.join(currencies)
+            'currencies': ','.join(currencies or []),
         })
         response = self.client.get(f'{self.base_url}/{date}', params=params)
         return response.json()
 
-    def ohlc(self, base, currency, date, date_type):
+    def hourly(self, base='', currency='', start_date='', end_date='', math='', date_type=''):
         params = self._removeEmpty({
             'base': base,
             'currency': currency,
-            'date': date,
+            'start_date': start_date,
+            'end_date': end_date,
+            'math': math,
             'date_type': date_type
         })
+        response = self.client.get(f'{self.base_url}/hourly', params=params)
+        return response.json()
+
+    def ohlc(self, base='', currency='', date='', date_type=''):
+        params = self._removeEmpty({
+            'base': base,
+            'currency': currency,
+            'date': date,
+            'date_type': date_type,
+        })
         response = self.client.get(f'{self.base_url}/ohlc', params=params)
         return response.json()
 
-    def convert(self, to_currency, amount, from_currency='', date=''):
+    def convert(self, from_currency='', to_currency='', amount='', date=''):
         params = self._removeEmpty({
             'from': from_currency,
             'to': to_currency,
             'amount': amount,
-            'date': date
+            'date': date,
         })
         response = self.client.get(f'{self.base_url}/convert', params=params)
         return response.json()
 
-    def timeframe(self, start_date, end_date, base='', currencies=[]):
+    def timeframe(self, start_date, end_date, base='', currencies=None):
         params = self._removeEmpty({
             'start_date': start_date,
             'end_date': end_date,
             'base': base,
-            'currencies': ','.join(currencies)
+            'currencies': ','.join(currencies or []),
         })
         response = self.client.get(f'{self.base_url}/timeframe', params=params)
         return response.json()
 
-    def change(self, start_date, end_date, base='', currencies=[]):
+    def change(self, start_date, end_date, base='', currencies=None, date_type=''):
         params = self._removeEmpty({
             'start_date': start_date,
             'end_date': end_date,
             'base': base,
-            'currencies': ','.join(currencies)
+            'currencies': ','.join(currencies or []),
+            'date_type': date_type,
         })
         response = self.client.get(f'{self.base_url}/change', params=params)
         return response.json()
 
     def usage(self):
         response = self.client.get(f'{self.base_url}/usage')
-        return response.json()
+        return response.json()

setup.py

@@ -2,10 +2,10 @@
 
 setuptools.setup(
     name="forexrateapi",
-    version="1.1.2",
+    version="1.3.0",
     url="https://github.com/forexrateapi/forexrateapi-python",
 
-    license_files=('LICENSE'),
+    license_files=('LICENSE',),
 
     author="ForexRateAPI",
     author_email="contact@forexrateapi.com",