v1.3.0

Author: metalpriceapi-user

README.md

@@ -16,7 +16,30 @@ from metalpriceapi.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
+
+MetalpriceAPI provides two regional endpoints. Choose the one closest to your servers for optimal performance.
+
+| Region | Base URL |
+|--------|----------|
+| United States (default) | `https://api.metalpriceapi.com/v1` |
+| Europe | `https://api-eu.metalpriceapi.com/v1` |
+
+```python
+from metalpriceapi.client import Client
+
+# Default (US)
+client = Client('SET_YOUR_API_KEY_HERE')
+
+# Europe
+client = Client('SET_YOUR_API_KEY_HERE', server='eu')
+```
+
 ---
 ## Documentation
 
@@ -28,32 +51,62 @@ client.fetchSymbols()
 [Link](https://metalpriceapi.com/documentation#api_symbol)
 
 ---
-#### fetchLive(base, currencies)
+#### setServer(server)
+
+- `server` <[string]> Pass `'eu'` to use the EU server (`api-eu.metalpriceapi.com`), or `'us'` for the US server. Defaults to US if not specified.
+
+```python
+client.setServer('eu')
+```
+
+---
+#### fetchLive(base, currencies, unit, purity, 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.
+- `currencies` <[List]<[string]>> Optional. Pass in a list of currencies to return values for.
+- `unit` <[string]> Optional. Pass in a unit for metal prices (e.g. `troy_oz`, `gram`, `kilogram`).
+- `purity` <[string]> Optional. Pass in a purity level for metal prices.
+- `math` <[string]> Optional. Pass in a math expression to apply to the rates.
 
 ```python
-client.fetchLive(base='USD', currencies=['XAU', 'XAG', 'XPD', 'XPT'])
+client.fetchLive(base='USD', currencies=['XAU', 'XAG', 'XPD', 'XPT'], unit='troy_oz')
 ```
 
 [Link](https://metalpriceapi.com/documentation#api_realtime)
 
 ---
-#### fetchHistorical(date, base, currencies)
+#### fetchHistorical(date, base, currencies, unit)
 
 - `date` <[string]> Required. Pass in a string with 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.
+- `currencies` <[List]<[string]>> Optional. Pass in a list of currencies to return values for.
+- `unit` <[string]> Optional. Pass in a unit for metal prices (e.g. `troy_oz`, `gram`, `kilogram`).
 
 ```python
-client.fetchHistorical(date='2024-02-05', base='USD', currencies=['XAU', 'XAG', 'XPD', 'XPT'])
+client.fetchHistorical(date='2024-02-05', base='USD', currencies=['XAU', 'XAG', 'XPD', 'XPT'], unit='troy_oz')
 ```
 
 [Link](https://metalpriceapi.com/documentation#api_historical)
 
 ---
-#### fetchOHLC(base, currency, date, unit, dateType)
+#### hourly(base, currency, unit, 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.
+- `unit` <[string]> Optional. Pass in a unit for metal prices (e.g. `troy_oz`, `gram`, `kilogram`).
+- `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='XAU', unit='troy_oz', start_date='2025-11-03', end_date='2025-11-03')
+```
+
+[Link](https://metalpriceapi.com/documentation#api_hourly)
+
+---
+#### fetchOHLC(base, currency, date, unit, date_type)
 
 - `base` <[string]> Optional. Pass in a base currency, defaults to USD.
 - `currency` <[string]> Required. Specify currency you would like to get OHLC for.
@@ -62,18 +115,19 @@ client.fetchHistorical(date='2024-02-05', base='USD', currencies=['XAU', 'XAG',
 - `date_type` <[string]> Optional. Pass in a date type, overrides date parameter if passed in.
 
 ```python
-client.fetchOHLC(base='USD', currency='XAU', date='2024-02-05', unit='troy_oz', date_type=None)
+client.fetchOHLC(base='USD', currency='XAU', date='2024-02-05', unit='troy_oz')
 ```
 
 [Link](https://metalpriceapi.com/documentation#api_ohlc)
 
 ---
-#### convert(from_currency, to_currency, amount, date)
+#### convert(from_currency, to_currency, amount, date, unit)
 
 - `from_currency` <[string]> Optional. Pass in a base currency, defaults to USD.
 - `to_currency` <[string]> Required. Specify currency you would like to convert to.
 - `amount` <[number]> Required. The amount to convert.
 - `date` <[string]> Optional. Specify date to use historical midpoint value for conversion with format `YYYY-MM-DD`. Otherwise, it will use live exchange rate date if value not passed in.
+- `unit` <[string]> Optional. Pass in a unit for metal prices (e.g. `troy_oz`, `gram`, `kilogram`).
 
 ```python
 client.convert(from_currency='USD', to_currency='EUR', amount=100, date='2024-02-05')
@@ -82,26 +136,28 @@ client.convert(from_currency='USD', to_currency='EUR', amount=100, date='2024-02
 [Link](https://metalpriceapi.com/documentation#api_convert)
 
 ---
-#### timeframe(start_date, end_date, base, currencies)
+#### timeframe(start_date, end_date, base, currencies, unit)
 
 - `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.
+- `currencies` <[List]<[string]>> Optional. Pass in a list of currencies to return values for.
+- `unit` <[string]> Optional. Pass in a unit for metal prices (e.g. `troy_oz`, `gram`, `kilogram`).
 
 ```python
-client.timeframe(start_date='2024-02-05', end_date='2024-02-06', base='USD', currencies=['XAU', 'XAG', 'XPD', 'XPT'])
+client.timeframe(start_date='2024-02-05', end_date='2024-02-06', base='USD', currencies=['XAU', 'XAG', 'XPD', 'XPT'], unit='troy_oz')
 ```
 
 [Link](https://metalpriceapi.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.
+- `currencies` <[List]<[string]>> Optional. Pass in a 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=['XAU', 'XAG', 'XPD', 'XPT'])
@@ -110,13 +166,14 @@ client.change(start_date='2024-02-05', end_date='2024-02-06', base='USD', curren
 [Link](https://metalpriceapi.com/documentation#api_change)
 
 ---
-#### carat(base, date)
+#### carat(base, currency, date)
 
 - `base` <[string]> Optional. Pass in a base currency, defaults to USD.
+- `currency` <[string]> Optional. Pass in a metal code to get carat prices for (defaults to XAU).
 - `date` <[string]> Optional. Specify date to get Carat for specific date using format `YYYY-MM-DD`. If not specified, uses live rates.
 
 ```python
-client.carat(base='USD', date='2024-02-05')
+client.carat(base='USD', currency='XAU', date='2024-02-05')
 ```
 
 [Link](https://metalpriceapi.com/documentation#api_carat)

example.py

@@ -3,28 +3,34 @@
 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=['XAU', 'XAG', 'XPD', 'XPT'])
+result = client.fetchLive(base='USD', currencies=['XAU', 'XAG', 'XPD', 'XPT'], unit='troy_oz')
+print(result)
+
+result = client.fetchHistorical(date='2024-02-05', base='USD', currencies=['XAU', 'XAG', 'XPD', 'XPT'], unit='troy_oz')
 print(result)
 
-result = client.fetchHistorical(date='2024-02-05', base='USD', currencies=['XAU', 'XAG', 'XPD', 'XPT'])
+result = client.hourly(base='USD', currency='XAU', unit='troy_oz', start_date='2025-11-03', end_date='2025-11-03')
 print(result)
 
-result = client.fetchOHLC(base='USD', currency='XAU', date='2024-02-06', unit='troy_oz', date_type=None)
+result = client.fetchOHLC(base='USD', currency='XAU', date='2024-02-06', unit='troy_oz')
 print(result)
 
 result = client.convert(from_currency='USD', to_currency='EUR', amount=100, date='2024-02-05')
 print(result)
 
-result = client.timeframe(start_date='2024-02-05', end_date='2024-02-06', base='USD', currencies=['XAU', 'XAG', 'XPD', 'XPT'])
+result = client.timeframe(start_date='2024-02-05', end_date='2024-02-06', base='USD', currencies=['XAU', 'XAG', 'XPD', 'XPT'], unit='troy_oz')
 print(result)
 
 result = client.change(start_date='2024-02-05', end_date='2024-02-06', base='USD', currencies=['XAU', 'XAG', 'XPD', 'XPT'])
 print(result)
 
-result = client.carat(base='USD', date='2024-02-06')
+result = client.carat(base='USD', currency='XAU', date='2024-02-06')
 print(result)
 
 result = client.usage()

metalpriceapi/client.py

@@ -1,79 +1,107 @@
 import requests
 
 class Client(object):
-    base_url = 'https://api.metalpriceapi.com/v1'
+    SERVERS = {
+        'us': 'https://api.metalpriceapi.com/v1',
+        'eu': 'https://api-eu.metalpriceapi.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, unit='', purity='', math=''):
         params = self._removeEmpty({
             'base': base,
-            'currencies': ','.join(currencies)
+            'currencies': ','.join(currencies or []),
+            'unit': unit,
+            'purity': purity,
+            '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, unit=''):
         params = self._removeEmpty({
             'base': base,
-            'currencies': ','.join(currencies)
+            'currencies': ','.join(currencies or []),
+            'unit': unit,
         })
         response = self.client.get(f'{self.base_url}/{date}', params=params)
         return response.json()
 
+    def hourly(self, base='', currency='', unit='', start_date='', end_date='', math='', date_type=''):
+        params = self._removeEmpty({
+            'base': base,
+            'currency': currency,
+            'unit': unit,
+            '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 fetchOHLC(self, base='', currency='', date='', unit='', date_type=''):
         params = self._removeEmpty({
             'base': base,
             'currency': currency,
             'date': date,
             'unit': unit,
-            'date_type': date_type
+            '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='', unit=''):
         params = self._removeEmpty({
             'from': from_currency,
             'to': to_currency,
             'amount': amount,
-            'date': date
+            'date': date,
+            'unit': unit,
         })
         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, unit=''):
         params = self._removeEmpty({
             'start_date': start_date,
             'end_date': end_date,
             'base': base,
-            'currencies': ','.join(currencies)
+            'currencies': ','.join(currencies or []),
+            'unit': unit,
         })
         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 carat(self, base='', date = ''):
+    def carat(self, base='', currency='', date=''):
         params = self._removeEmpty({
             'base': base,
+            'currency': currency,
             'date': date,
         })
         response = self.client.get(f'{self.base_url}/carat', params=params)

setup.py

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