Merge pull request #2 from nklsla/feature/add-price-array-call

Author: alexwox

README.md

@@ -1,5 +1,7 @@
 # Borsdata API Client
+
 ### [NOT AFFILIATED WITH BÖRSDATA]
+
 ### [THIS IS A THIRD PARTY LIBRARY]
 
 This is a modern Python client for the Borsdata API, featuring:
@@ -11,7 +13,7 @@ This is a modern Python client for the Borsdata API, featuring:
 - Context manager support
 - Intuitive API design
 
-For the official documentation check out: 
+For the official documentation check out:
 [https://github.com/Borsdata-Sweden/API]
 
 ## Installation
@@ -106,19 +108,23 @@ Comprehensive documentation is available in the `docs` directory:
 - `get_branches()` - Get all branches/industries
 - `get_countries()` - Get all countries
 - `get_markets()` - Get all markets
+- `get_sectors()` - Get all sectors
 - `get_instruments()` - Get all Nordic instruments
 - `get_global_instruments()` - Get all global instruments (Pro+ subscription required)
 - `get_stock_prices()` - Get stock prices for an instrument
+- `get_stock_prices_batch()` - Get stock prices for a batch of instrument
 - `get_reports()` - Get financial reports for an instrument
+- `get_reports_metadata()` - Get metadata for all financial report values
 - `get_kpi_metadata()` - Get metadata for all KPIs
+- `get_kpi_updated()` - Get last update time for KPIs
+- `get_kpi_history()` - Get one KPIs history for an instrument
+- `get_kpi_summary()` - Get summary of KPIs history for an instrument (Note: Not all kpi's)
 - `get_insider_holdings()` - Get insider holdings for instruments
 - `get_short_positions()` - Get short positions for all instruments
 - `get_buybacks()` - Get buybacks for instruments
 - `get_instrument_descriptions()` - Get descriptions for instruments
 - `get_report_calendar()` - Get report calendar for instruments
 - `get_dividend_calendar()` - Get dividend calendar for instruments
-- `get_kpi_history()` - Get KPI history for an instrument
-- `get_kpi_updated()` - Get last update time for KPIs
 - `get_last_stock_prices()` - Get last stock prices for all instruments
 - `get_last_global_stock_prices()` - Get last stock prices for all global instruments
 - `get_stock_prices_by_date()` - Get stock prices for all instruments on a specific date
@@ -140,6 +146,8 @@ except BorsdataClientError as e:
     print(f"API request failed: {e}")
 ```
 
+Retries five times by default if reaching the APIs rate limit (100 requests / 10 seconds).
+
 ## Data Models
 
 All API responses are validated and converted to Pydantic models. See the [Models Reference](docs/api/models.md) for details.
@@ -151,6 +159,7 @@ All API responses are validated and converted to Pydantic models. See the [Model
 - httpx>=0.25.2
 - python-dateutil>=2.8.2
 - typing-extensions>=4.8.0
+- tenacity>=9.0.0
 
 ## License
 

docs/examples/advanced_usage.md

@@ -11,7 +11,7 @@ from datetime import datetime
 
 api_key = os.environ.get("BORSDATA_API_KEY")
 
-with BorsdataClient(api_key) as client:
+with BorsdataClient(api_key, retry=True, max_retries=5) as client:
     # Get all instruments
     instruments = client.get_instruments()
 

requirements-dev.txt

@@ -5,4 +5,5 @@ seaborn>=0.13.0
 pytest>=7.4.0
 pytest-cov>=4.1.0
 pytest-mock>=3.11.1
-httpx>=0.25.2 
+httpx>=0.25.2 
+tenacity>=9.0.0

requirements.txt

@@ -3,3 +3,4 @@ httpx>=0.25.2
 python-dateutil>=2.8.2
 typing-extensions>=4.8.0 
 python-dotenv>=1.0.0
+tenacity>=9.0.0

src/borsdata_client/client.py

@@ -4,6 +4,12 @@
 from typing import Any, Dict, List, Optional
 
 import httpx
+from tenacity import (
+    Retrying,
+    retry_if_exception,
+    stop_after_attempt,
+    wait_random_exponential,
+)
 
 from .models import (
     Branch,
@@ -33,6 +39,8 @@
     StockPrice,
     StockPriceLastResponse,
     StockPriceLastValue,
+    StockPricesArrayResp,
+    StockPricesArrayRespList,
     StockPricesResponse,
     StockSplit,
     StockSplitResponse,
@@ -51,14 +59,34 @@ class BorsdataClient:
 
     BASE_URL = "https://apiservice.borsdata.se/v1"
 
-    def __init__(self, api_key: str):
+    def __init__(self, api_key: str, retry: bool = True, max_retries: int = 5):
         """Initialize the Borsdata API client.
 
         Args:
             api_key: Your Borsdata API authentication key
+            retry: Whether to enable retry on rate limit errors
+            max_retries: Maximum number of retries for rate limit errors
         """
         self.api_key = api_key
         self._client = httpx.Client(timeout=30.0)
+        self.retry = retry
+        self.retryer = None
+
+        def is_retryable_exception(exception):
+            """Check if the exception is retryable."""
+            if isinstance(exception, httpx.HTTPStatusError):
+                # Retry for 429 Too Many Requests
+                if exception.response.status_code == 429:
+                    print("Rate limit exceeded. Retrying...")
+                    return True
+            return False
+
+        self.retryer = Retrying(
+            wait=wait_random_exponential(multiplier=1, min=1, max=20),
+            stop=stop_after_attempt(max_retries),
+            reraise=True,
+            retry=retry_if_exception(is_retryable_exception),
+        )
 
     def _get(
         self, endpoint: str, params: Optional[Dict[str, Any]] = None
@@ -79,10 +107,23 @@ def _get(
             params = {}
         params["authKey"] = self.api_key
 
-        try:
-            response = self._client.get(f"{self.BASE_URL}{endpoint}", params=params)
-            response.raise_for_status()  # This will raise an HTTPError for 4XX/5XX responses
+        def _get_wrapper(api_endpoint=endpoint, params=params):
+            response = self._client.get(api_endpoint, params=params)
+            response.raise_for_status()  # This raises HTTPStatusError for 4xx/5xx codes
             return response.json()
+
+        try:
+            if self.retry:
+                return self.retryer(
+                    _get_wrapper,
+                    api_endpoint=f"{self.BASE_URL}{endpoint}",
+                    params=params,
+                )
+            else:
+                return _get_wrapper(
+                    api_endpoint=f"{self.BASE_URL}{endpoint}", params=params
+                )
+
         except httpx.HTTPStatusError as e:
             error_msg = str(e)
             status_code = e.response.status_code
@@ -177,6 +218,38 @@ def get_stock_prices(
         # Convert each stock price dict to a StockPrice object
         return [StockPrice(**price) for price in response_model.stockPricesList]
 
+    def get_stock_prices_batch(
+        self,
+        instrument_ids: list[int],
+        from_date: Optional[datetime] = None,
+        to_date: Optional[datetime] = None,
+    ) -> List[StockPricesArrayRespList]:
+        """Get stock prices for multiple instruments, max 50 instruments per call.
+
+        Args:
+            instrument_ids: List of instrument IDs
+            from_date: Start date for price data
+            to_date: End date for price data
+
+        Returns:
+            List of StockPrice objects
+        """
+        assert isinstance(instrument_ids, list), "instrument_ids must be a list"
+        assert len(instrument_ids) <= 50, "Max 50 instrument IDs allowed per request"
+
+        params = {"instList": ",".join(map(str, instrument_ids))}
+
+        if from_date:
+            params["from"] = from_date.strftime("%Y-%m-%d")
+        if to_date:
+            params["to"] = to_date.strftime("%Y-%m-%d")
+
+        response = self._get("/instruments/stockprices", params)
+        response_model = StockPricesArrayResp(**response)
+
+        # Return list of instrument stock prices
+        return response_model.stockPricesArrayList
+
     def get_reports(
         self,
         instrument_id: int,
@@ -238,6 +311,58 @@ def get_kpi_updated(self) -> datetime:
         response = self._get("/instruments/kpis/updated")
         return KpiCalcUpdatedResponse(**response).kpis_calc_updated
 
+    def get_kpi_history(
+        self,
+        instrument_id: str,
+        kpi_id: int,
+        report_type: str,
+        price_type: str = "mean",
+        max_count: Optional[int] = None,
+    ) -> List[KpiAllResponse]:
+        """Get KPI history for an instrument.
+
+        Args:
+            instrument_id: ID of the instrument
+            kpi_id: ID of the KPI
+            report_type: Type of report ('year', 'r12', 'quarter')
+            price_type: Type of price calculation
+            max_count: Maximum number of results to return
+
+        Returns:
+            List of KPI responses
+        """
+        params = {}
+        if max_count:
+            params["maxCount"] = str(max_count)
+
+        response = self._get(
+            f"/instruments/{instrument_id}/kpis/{kpi_id}/{report_type}/{price_type}/history",
+            params,
+        )
+        return KpiAllResponse(**response)
+
+    def get_kpi_summary(
+        self, instrument_id: str, report_type: str, max_count: Optional[int] = None
+    ) -> List[KpiSummaryGroup]:
+        """Get all KPI history for an instrument.
+
+        Args:
+            instrument_id: ID of the instrument
+            report_type: Type of report ('year', 'r12', 'quarter')
+            max_count: Maximum number of results to return
+
+        Returns:
+            List of all KPI responses
+        """
+        params = {}
+        if max_count:
+            params["maxCount"] = str(max_count)
+
+        response = self._get(
+            f"/instruments/{instrument_id}/kpis/{report_type}/summary", params
+        )
+        return KpisSummaryResponse(**response).kpis or []
+
     def get_insider_holdings(
         self, instrument_ids: List[int]
     ) -> List[InsiderListResponse]:
@@ -320,58 +445,6 @@ def get_dividend_calendar(
         response = self._get("/instruments/dividend/calendar", params)
         return DividendCalendarListResponse(**response).list or []
 
-    def get_kpi_history(
-        self,
-        instrument_id: str,
-        kpi_id: int,
-        report_type: str,
-        price_type: str = "mean",
-        max_count: Optional[int] = None,
-    ) -> List[KpiAllResponse]:
-        """Get KPI history for an instrument.
-
-        Args:
-            instrument_id: ID of the instrument
-            kpi_id: ID of the KPI
-            report_type: Type of report ('year', 'r12', 'quarter')
-            price_type: Type of price calculation
-            max_count: Maximum number of results to return
-
-        Returns:
-            List of KPI responses
-        """
-        params = {}
-        if max_count:
-            params["maxCount"] = str(max_count)
-
-        response = self._get(
-            f"/instruments/{instrument_id}/kpis/{kpi_id}/{report_type}/{price_type}/history",
-            params,
-        )
-        return KpiAllResponse(**response)
-
-    def get_kpi_summary(
-        self, instrument_id: str, report_type: str, max_count: Optional[int] = None
-    ) -> List[KpiSummaryGroup]:
-        """Get all KPI history for an instrument.
-
-        Args:
-            instrument_id: ID of the instrument
-            report_type: Type of report ('year', 'r12', 'quarter')
-            max_count: Maximum number of results to return
-
-        Returns:
-            List of all KPI responses
-        """
-        params = {}
-        if max_count:
-            params["maxCount"] = str(max_count)
-
-        response = self._get(
-            f"/instruments/{instrument_id}/kpis/{report_type}/summary", params
-        )
-        return KpisSummaryResponse(**response).kpis or []
-
     def get_last_stock_prices(self) -> List[StockPriceLastValue]:
         """Get last stock prices for all instruments.
 

src/borsdata_client/models.py

@@ -58,18 +58,20 @@ class Instrument(BaseModel):
 
 
 class StockPrice(BaseModel):
-    """Stock price data model."""
+    """Single stock price entry."""
 
-    d: str = Field(description="Date string in format YYYY-MM-DD")
-    h: float = Field(description="High price")
-    l: float = Field(description="Low price")
-    c: float = Field(description="Closing price")
-    o: float = Field(description="Opening price")
-    v: int = Field(description="Volume")
+    d: Optional[str] = Field(None, description="Date string in format YYYY-MM-DD")
+    h: Optional[float] = Field(None, description="Highest price")
+    l: Optional[float] = Field(None, description="Lowest price")
+    c: float = Field(..., description="Closing price")
+    o: Optional[float] = Field(None, description="Opening price")
+    v: Optional[int] = Field(None, description="Total volume")
 
-    def get_date(self) -> datetime:
+    def get_date(self) -> Optional[datetime]:
         """Convert the date string to a datetime object."""
-        return datetime.strptime(self.d, "%Y-%m-%d")
+        if isinstance(self.d, str):
+            return datetime.strptime(self.d, "%Y-%m-%d")
+        return None
 
 
 class KpiMetadata(BaseModel):
@@ -204,6 +206,24 @@ class StockPricesResponse(BaseModel):
     stockPricesList: List[Dict[str, Any]]  # The actual field name from the API
 
 
+class StockPricesArrayRespList(BaseModel):
+    """Stock prices list response for an instrument."""
+
+    instrument: int = Field(..., description="Instrument ID")
+    error: Optional[str] = Field(None, description="Error message, if any")
+    stockPricesList: Optional[List[StockPrice]] = Field(
+        None, description="List of stock prices"
+    )
+
+
+class StockPricesArrayResp(BaseModel):
+    """Top-level response for stock prices array."""
+
+    stockPricesArrayList: Optional[List[StockPricesArrayRespList]] = Field(
+        None, description="List of stock prices per instrument"
+    )
+
+
 class InsiderRow(BaseModel):
     """Model for insider trading data."""
 
@@ -370,10 +390,10 @@ class StockPriceLastValue(BaseModel):
 
     i: int = Field(description="Instrument Id")
     d: str = Field(description="Date string in format YYYY-MM-DD")
+    o: float = Field(description="Opening price")
     h: float = Field(description="High price")
     l: float = Field(description="Low price")
     c: float = Field(description="Closing price")
-    o: float = Field(description="Opening price")
     v: Optional[int] = Field(None, description="Volume")