volt-client 1.0.0__py3-none-any.whl

volt_client/__init__.py

@@ -0,0 +1,28 @@
+"""
+Volt Client - Python client for Volt Power Analytics API.
+
+Usage:
+    from volt_client import VoltClient
+
+    client = VoltClient(api_key="volt_your_api_key")
+    df = client.get_actual("price spot no1 nordpool eur mwh min60 actual", "2024-01-01", "2024-12-31")
+"""
+
+from volt_client.client import (
+    DataFrame,
+    VoltAccessError,
+    VoltClient,
+    VoltClientError,
+    VoltCurveNotFoundError,
+    VoltEmptyDataError,
+)
+
+__version__ = "1.0.0"
+__all__ = [
+    "VoltClient",
+    "VoltClientError",
+    "VoltAccessError",
+    "VoltCurveNotFoundError",
+    "VoltEmptyDataError",
+    "DataFrame",
+]

volt_client/client.py

@@ -0,0 +1,826 @@
+"""
+Volt Client for accessing Volt Power Analytics time series data API.
+
+Usage:
+    from volt_client import VoltClient
+
+    # Recommended: Use API key (generated from dashboard)
+    client = VoltClient(api_key="volt_abc123...")
+    df = client.get_actual("price power no1 nordpool eur min60 actual", "2024-01-01", "2024-12-31")
+
+    # For better performance with large datasets, use polars:
+    client = VoltClient(api_key="volt_abc123...", use_polars=True)
+    df = client.get_actual(...)  # Returns polars DataFrame
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+import orjson
+import polars as pl
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+# Type alias for DataFrame return type
+DataFrame = pl.DataFrame
+
+logger = logging.getLogger(__name__)
+
+# Default API URL
+DEFAULT_API_URL = "https://volt-api-gateway.azure-api.net/volt"
+
+
+class VoltClientError(Exception):
+    """Base exception for VoltClient errors."""
+
+    pass
+
+
+class VoltAccessError(VoltClientError):
+    """Raised when access is denied."""
+
+    pass
+
+
+class VoltCurveNotFoundError(VoltClientError):
+    """Raised when a curve is not found."""
+
+    pass
+
+
+class VoltEmptyDataError(VoltClientError):
+    """Raised when no data is returned."""
+
+    pass
+
+
+class VoltClient:
+    """
+    Client for accessing Volt Power Analytics time series data API.
+
+    Internally uses polars for all data processing (10x faster than pandas).
+    By default returns pandas DataFrames for backwards compatibility.
+
+    Parameters:
+    -----------
+    api_key : str
+        API key for authentication (required, generated from dashboard).
+        Example: "volt_abc123..."
+    base_url : str, optional
+        Base URL for the API (default: https://volt-api-gateway.azure-api.net/volt)
+    use_polars : bool, optional
+        If True, return polars DataFrames instead of pandas.
+        Default: False (returns pandas DataFrames for backwards compatibility)
+
+    Example:
+    --------
+    >>> from volt_client import VoltClient
+    >>> client = VoltClient(api_key="volt_abc123...")
+    >>> df = client.get_actual("price power no1 nordpool eur min60 actual", "2024-01-01", "2024-12-31")
+
+    >>> # For better performance with large datasets:
+    >>> client = VoltClient(api_key="volt_abc123...", use_polars=True)
+    >>> df = client.get_actual(...)  # Returns polars DataFrame
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_API_URL,
+        use_polars: bool = False,
+    ):
+        if not api_key:
+            raise ValueError("API key is required. Get one from the Volt Analytics dashboard.")
+
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.use_polars = use_polars
+        self._session = None
+        self._curves_cache: pl.DataFrame | None = None
+
+    def _get_session(self) -> requests.Session:
+        """Get or create a requests session with retry logic."""
+        if self._session is None:
+            self._session = requests.Session()
+            retry = Retry(
+                total=3,
+                backoff_factor=0.3,
+                status_forcelist=(500, 502, 503, 504),
+            )
+            adapter = HTTPAdapter(max_retries=retry)
+            self._session.mount("http://", adapter)
+            self._session.mount("https://", adapter)
+        return self._session
+
+    def _get_headers(self) -> dict:
+        """Get request headers with authentication credentials."""
+        return {
+            "Content-Type": "application/json",
+            "X-API-Key": self.api_key,
+        }
+
+    def _request(self, method: str, endpoint: str, params: dict = None) -> dict:
+        """Make an API request."""
+        session = self._get_session()
+        url = f"{self.base_url}{endpoint}"
+
+        response = session.request(
+            method=method,
+            url=url,
+            headers=self._get_headers(),
+            params=params,
+        )
+
+        if response.status_code == 401:
+            raise VoltAccessError("Invalid API key or access denied")
+        elif response.status_code == 403:
+            raise VoltAccessError(f"Access denied to {endpoint}")
+        elif response.status_code == 404:
+            # Include params in error for debugging
+            param_info = f" (params: {params})" if params else ""
+            raise VoltCurveNotFoundError(f"Not found: {endpoint}{param_info}")
+        elif response.status_code != 200:
+            raise VoltClientError(f"API error: {response.status_code} - {response.text}")
+
+        # Use orjson for faster JSON parsing (3-10x faster than stdlib json)
+        return orjson.loads(response.content)
+
+    def _to_output(self, df: pl.DataFrame) -> DataFrame | pd.DataFrame:
+        """Convert polars DataFrame to output format based on use_polars setting."""
+        if self.use_polars:
+            return df
+
+        pdf = df.to_pandas()
+        if "ts" in pdf.columns:
+            pdf = pdf.set_index("ts")
+        return pdf
+
+    def search(self, area: str = None, groups: str = None) -> DataFrame:
+        """
+        Search for available curves.
+
+        Parameters:
+        -----------
+        area : str, optional
+            Filter by area (e.g., "NO1", "SE1")
+        groups : str, optional
+            Filter by group (e.g., "historical", "mid-term")
+
+        Returns:
+        --------
+        DataFrame with curve metadata (curve_id, curve_name, area, groups, etc.)
+        Returns polars DataFrame if use_polars=True, otherwise pandas DataFrame.
+        """
+        params = {}
+        if area:
+            params["area"] = area
+        if groups:
+            params["groups"] = groups
+
+        data = self._request("GET", "/curves", params=params)
+        return pl.DataFrame(data) if self.use_polars else pl.DataFrame(data).to_pandas()
+
+    def get_curve_id(self, curve_name: str) -> int:
+        """
+        Get the curve ID for a given curve name.
+
+        Parameters:
+        -----------
+        curve_name : str
+            The unique curve name
+
+        Returns:
+        --------
+        int: The curve ID
+        """
+        # Always use polars internally for cache
+        if self._curves_cache is None:
+            data = self._request("GET", "/curves", params={})
+            self._curves_cache = pl.DataFrame(data)
+
+        curve_name_lower = curve_name.lower()
+        match = self._curves_cache.filter(
+            pl.col("curve_name").str.to_lowercase() == curve_name_lower
+        )
+
+        if match.is_empty():
+            raise VoltCurveNotFoundError(
+                f"Curve '{curve_name}' not found or you do not have access to it"
+            )
+        return int(match["curve_id"][0])
+
+    def name_search(self, search_query: str) -> DataFrame:
+        """
+        Search for curves by keywords in the name.
+
+        Parameters:
+        -----------
+        search_query : str
+            Space-separated keywords to search for (e.g., "price no1 actual")
+
+        Returns:
+        --------
+        DataFrame with matching curves.
+        Returns polars DataFrame if use_polars=True, otherwise pandas DataFrame.
+        """
+        # Always use polars internally for cache
+        if self._curves_cache is None:
+            data = self._request("GET", "/curves", params={})
+            self._curves_cache = pl.DataFrame(data)
+
+        search_terms = search_query.lower().split()
+
+        # Build polars filter expression
+        filter_expr = pl.lit(True)
+        for term in search_terms:
+            filter_expr = filter_expr & pl.col("curve_name").str.to_lowercase().str.contains(term)
+        matches = self._curves_cache.filter(filter_expr)
+
+        if matches.is_empty():
+            logger.warning(f"No curves found matching '{search_query}'")
+
+        return matches if self.use_polars else matches.to_pandas()
+
+    def get_actual(
+        self,
+        curve_name,
+        start_date: str,
+        end_date: str,
+        tz: str = None,
+        agg: str = None,
+        agg_func: str = None,
+    ) -> DataFrame:
+        """
+        Get actual (historical) time series data for a curve or multiple curves.
+
+        Supports both single curve and bulk queries. When a list is provided,
+        automatically uses a single optimized bulk request (much faster than
+        calling get_actual() in a loop).
+
+        Parameters:
+        -----------
+        curve_name : str or list of str
+            Single curve name, or list of curve names for bulk query.
+            Curve names must end with 'actual' or 'synthetic'.
+        start_date : str
+            Start date in format 'YYYY-MM-DD'
+        end_date : str
+            End date in format 'YYYY-MM-DD'
+        tz : str, optional
+            Output timezone (e.g., 'Europe/Oslo', 'CET'). Default: UTC.
+        agg : str, optional
+            Aggregation period: 'hourly', 'daily', 'weekly', 'monthly', 'quarterly', 'yearly'.
+            If specified, data is aggregated server-side.
+        agg_func : str, optional
+            Aggregation function: 'avg', 'sum', 'min', 'max'. Default: 'avg'.
+            Only used when agg is specified.
+
+        Returns:
+        --------
+        DataFrame with DatetimeIndex and value column(s) named after the curve(s).
+        Returns polars DataFrame if use_polars=True, otherwise pandas DataFrame.
+
+        Examples:
+        ---------
+        # Single curve
+        df = client.get_actual(
+            "price power no1 nordpool eur min60 actual",
+            "2024-01-01", "2024-12-31"
+        )
+
+        # Multiple curves (bulk query - much faster)
+        df = client.get_actual(
+            ["price power no1 nordpool eur min60 actual",
+             "price power no2 nordpool eur min60 actual",
+             "price power se1 nordpool eur min60 actual"],
+            "2024-01-01", "2024-12-31",
+            tz="Europe/Oslo",
+            agg="daily"
+        )
+        # Returns DataFrame with one column per curve
+        """
+        # If list provided, use bulk query for efficiency
+        if isinstance(curve_name, list | tuple):
+            return self.get_bulk(
+                curve_names=list(curve_name),
+                start_date=start_date,
+                end_date=end_date,
+                tz=tz,
+                agg=agg,
+                agg_func=agg_func,
+            )
+
+        curve_name_lower = curve_name.lower()
+        curve_type = curve_name_lower.split()[-1]
+
+        if curve_type not in ["actual", "synthetic"]:
+            raise VoltClientError(
+                f"Curve '{curve_name}' is not of type 'actual' or 'synthetic' but '{curve_type}'. "
+                "Use get_actual only for actual/synthetic curves."
+            )
+
+        curve_id = self.get_curve_id(curve_name_lower)
+
+        params = {
+            "curve_id": curve_id,
+            "start_date": start_date,
+            "end_date": end_date,
+        }
+        if tz:
+            params["tz"] = tz
+        if agg:
+            params["agg"] = agg
+        if agg_func:
+            params["agg_func"] = agg_func
+
+        data = self._request("GET", "/data/actual", params=params)
+
+        if not data.get("data"):
+            raise VoltEmptyDataError(
+                f"No data for '{curve_name}' between {start_date} and {end_date}"
+            )
+
+        # Always use polars internally for processing
+        df = pl.DataFrame(data["data"])
+        target_tz = tz or "UTC"
+        df = df.with_columns(
+            pl.col("ts")
+            .str.to_datetime(time_unit="us", time_zone="UTC")
+            .dt.convert_time_zone(target_tz)
+        )
+        df = df.sort("ts")
+        df = df.unique(subset=["ts"], keep="last")
+        df = df.rename({"value": curve_name_lower})
+        df = df.select(["ts", curve_name_lower])
+
+        logger.info(f"Extracted data for: {curve_name} from {df['ts'][0]} to {df['ts'][-1]}")
+
+        return self._to_output(df)
+
+    def get_fcast(
+        self,
+        curve_name,
+        start_date: str,
+        end_date: str,
+        as_of: str = None,
+        tz: str = None,
+        freq: str = None,
+        tags: str = None,
+    ) -> DataFrame:
+        """
+        Get forecast time series data for a curve or multiple curves.
+
+        Supports both single curve and bulk queries. When a list is provided,
+        automatically uses the bulk endpoint (much faster than calling get_fcast()
+        in a loop).
+
+        Parameters:
+        -----------
+        curve_name : str or list of str
+            Single curve name, or list of curve names for bulk query.
+            Curve names must end with 'fcast'.
+        start_date : str
+            Start date in format 'YYYY-MM-DD'
+        end_date : str
+            End date in format 'YYYY-MM-DD'
+        as_of : str, optional
+            As-of date for forecast (YYYY-MM-DD). If not specified, uses latest.
+            Note: For bulk queries, as_of is not supported.
+        tz : str, optional
+            Output timezone (e.g., 'Europe/Oslo', 'CET'). Default: UTC.
+            Note: For mid-term percentile data (when freq is specified), only
+            CET-compatible timezones are allowed.
+        freq : str, optional
+            Frequency for mid-term percentile/average data (e.g., 'weekly', 'monthly').
+            Only applicable for mid-term curves. Not supported in bulk queries.
+        tags : str, optional
+            Comma-separated weather year tags for mid-term hourly data.
+            Not supported in bulk queries.
+
+        Returns:
+        --------
+        DataFrame with timestamp and value column(s).
+        Returns polars DataFrame if use_polars=True, otherwise pandas DataFrame.
+
+        Examples:
+        ---------
+        # Single curve
+        df = client.get_fcast("prod wind no1 mid-term fcast", "2024-01-01", "2024-12-31")
+
+        # Multiple curves (bulk query - much faster)
+        df = client.get_fcast([
+            "prod wind no1 mid-term fcast",
+            "prod wind no2 mid-term fcast",
+            "prod solar de mid-term fcast"
+        ], "2024-01-01", "2024-12-31")
+        """
+        # If list provided, use bulk query for efficiency
+        if isinstance(curve_name, list | tuple):
+            if as_of or freq or tags:
+                logger.warning(
+                    "Bulk forecast queries do not support as_of, freq, or tags parameters. "
+                    "These will be ignored."
+                )
+            return self.get_bulk(
+                curve_names=list(curve_name),
+                start_date=start_date,
+                end_date=end_date,
+                tz=tz,
+            )
+
+        curve_name_lower = curve_name.lower()
+        curve_type = curve_name_lower.split()[-1]
+
+        if curve_type != "fcast":
+            raise VoltClientError(
+                f"Curve '{curve_name}' is not of type 'fcast' but '{curve_type}'. "
+                "Use get_fcast only for forecast curves."
+            )
+
+        curve_id = self.get_curve_id(curve_name_lower)
+
+        params = {
+            "curve_id": curve_id,
+            "start_date": start_date,
+            "end_date": end_date,
+        }
+        if as_of:
+            params["as_of"] = as_of
+        if tz:
+            params["tz"] = tz
+        if freq:
+            params["freq"] = freq
+        if tags:
+            params["tags"] = tags
+
+        data = self._request("GET", "/data/fcast", params=params)
+
+        if not data.get("data"):
+            raise VoltEmptyDataError(
+                f"No data for '{curve_name}' between {start_date} and {end_date}"
+            )
+
+        # Always use polars internally
+        df = pl.DataFrame(data["data"])
+        target_tz = tz or "UTC"
+        df = df.with_columns(
+            pl.col("ts")
+            .str.to_datetime(time_unit="us", time_zone="UTC")
+            .dt.convert_time_zone(target_tz)
+        )
+        df = df.sort("ts")
+        df = df.unique(subset=["ts"], keep="last")
+        if "value" in df.columns:
+            df = df.rename({"value": curve_name_lower})
+
+        logger.info(
+            f"Extracted forecast data for: {curve_name} from {df['ts'][0]} to {df['ts'][-1]}"
+        )
+
+        return self._to_output(df)
+
+    def get_closing(
+        self,
+        curve_name,
+        as_of: str = None,
+        tz: str = None,
+    ) -> DataFrame:
+        """
+        Get latest closing/settlement prices for a forward curve or multiple curves.
+
+        Supports both single curve and bulk queries. When a list is provided,
+        automatically uses a single optimized bulk request (much faster than
+        calling get_closing() in a loop).
+
+        Parameters:
+        -----------
+        curve_name : str or list of str
+            Single curve name, or list of curve names for bulk query.
+            Curve names must end with 'close' or 'settlement'.
+        as_of : str, optional
+            As-of date (YYYY-MM-DD). If not specified, uses latest for each curve.
+        tz : str, optional
+            Output timezone (e.g., 'Europe/Oslo', 'CET'). Default: UTC.
+
+        Returns:
+        --------
+        For single curve: DataFrame with forward contract data (delivery periods and prices).
+        For bulk query: DataFrame with curve_name, ts, value, and as_of columns.
+        Returns polars DataFrame if use_polars=True, otherwise pandas DataFrame.
+
+        Examples:
+        ---------
+        # Single curve
+        df = client.get_closing("price future no1 nasdaq close")
+
+        # Multiple curves (bulk query - much faster)
+        df = client.get_closing([
+            "price future no1 nasdaq close",
+            "price future no2 nasdaq close",
+            "price future se1 nasdaq close"
+        ])
+        """
+        # If list provided, use bulk query for efficiency
+        if isinstance(curve_name, list | tuple):
+            return self.get_bulk_closing(
+                curve_names=list(curve_name),
+                as_of=as_of,
+                tz=tz,
+            )
+
+        curve_name_lower = curve_name.lower()
+        curve_type = curve_name_lower.split()[-1]
+
+        if curve_type not in ["close", "settlement"]:
+            raise VoltClientError(
+                f"Curve '{curve_name}' is not of type 'close' or 'settlement' but '{curve_type}'. "
+                "Use get_closing only for closing/settlement curves."
+            )
+
+        curve_id = self.get_curve_id(curve_name_lower)
+
+        params = {"curve_id": curve_id}
+        if as_of:
+            params["as_of"] = as_of
+        if tz:
+            params["tz"] = tz
+
+        data = self._request("GET", "/data/closing", params=params)
+
+        if not data.get("data"):
+            raise VoltEmptyDataError(f"No closing data for '{curve_name}'")
+
+        # Always use polars internally
+        df = pl.DataFrame(data["data"])
+        target_tz = tz or "UTC"
+        for col in ["ts", "delivery_end"]:
+            if col in df.columns:
+                df = df.with_columns(
+                    pl.col(col)
+                    .str.to_datetime(time_unit="us", time_zone="UTC")
+                    .dt.convert_time_zone(target_tz)
+                )
+
+        logger.info(
+            f"Extracted closing data for: {curve_name}, as_of: {data.get('as_of')}, count: {len(df)}"
+        )
+
+        return df if self.use_polars else df.to_pandas()
+
+    def get_bulk_closing(
+        self,
+        curve_names: list[str],
+        as_of: str = None,
+        as_of_start: str = None,
+        as_of_end: str = None,
+        tz: str = None,
+    ) -> DataFrame:
+        """
+        Get closing/settlement prices for multiple forward curves in a single request.
+
+        This is much more efficient than calling get_closing() multiple times
+        as it makes a single HTTP request and ClickHouse query.
+
+        Parameters:
+        -----------
+        curve_names : list of str
+            List of curve names to fetch (must end with 'close' or 'settlement')
+        as_of : str, optional
+            Single as-of date (YYYY-MM-DD). If not specified, uses latest for each curve.
+        as_of_start : str, optional
+            Start of as-of range (YYYY-MM-DD). Use with as_of_end for development over time.
+        as_of_end : str, optional
+            End of as-of range (YYYY-MM-DD). Use with as_of_start for development over time.
+        tz : str, optional
+            Output timezone (e.g., 'Europe/Oslo', 'CET'). Default: UTC.
+
+        Returns:
+        --------
+        DataFrame with columns: curve_name, ts, value, as_of.
+        Returns polars DataFrame if use_polars=True, otherwise pandas DataFrame.
+
+        Examples:
+        ---------
+        # Snapshot mode - latest for each curve
+        df = client.get_bulk_closing(["curve1 close", "curve2 close"])
+
+        # Snapshot mode - specific date
+        df = client.get_bulk_closing(["curve1 close", "curve2 close"], as_of="2025-01-15")
+
+        # Range mode - development over time
+        df = client.get_bulk_closing(
+            ["curve1 close", "curve2 close"],
+            as_of_start="2025-01-01",
+            as_of_end="2025-01-15"
+        )
+        """
+        if not curve_names:
+            raise VoltClientError("curve_names cannot be empty")
+
+        if as_of and (as_of_start or as_of_end):
+            raise VoltClientError(
+                "Cannot use 'as_of' together with 'as_of_start'/'as_of_end'. "
+                "Use either snapshot mode (as_of) or range mode (as_of_start + as_of_end)."
+            )
+        if (as_of_start and not as_of_end) or (as_of_end and not as_of_start):
+            raise VoltClientError(
+                "Both 'as_of_start' and 'as_of_end' must be specified for range mode."
+            )
+
+        # Get curve IDs for all names
+        curve_ids = []
+        id_to_name = {}
+        for name in curve_names:
+            name_lower = name.lower()
+            curve_id = self.get_curve_id(name_lower)
+            curve_ids.append(curve_id)
+            id_to_name[curve_id] = name_lower
+
+        params = {
+            "curve_ids": ",".join(str(cid) for cid in curve_ids),
+        }
+        if as_of:
+            params["as_of"] = as_of
+        if as_of_start:
+            params["as_of_start"] = as_of_start
+        if as_of_end:
+            params["as_of_end"] = as_of_end
+        if tz:
+            params["tz"] = tz
+
+        data = self._request("GET", "/data/closing/bulk", params=params)
+
+        curves_data = data.get("curves", [])
+        if not curves_data:
+            raise VoltEmptyDataError(
+                f"No closing data found for any of the {len(curve_names)} requested curves. "
+                "Check that curves have data in curves_forwards table."
+            )
+
+        # Log which curves had data vs which didn't
+        curves_with_data = {c["curve_id"] for c in curves_data}
+        curves_without_data = [id_to_name[cid] for cid in curve_ids if cid not in curves_with_data]
+        if curves_without_data:
+            logger.warning(
+                f"No closing data for {len(curves_without_data)} curves: {curves_without_data[:5]}..."
+            )
+
+        # Build combined DataFrame using pl.concat (avoids Python row-by-row loop)
+        dfs = []
+        for curve in curves_data:
+            curve_id = curve["curve_id"]
+            curve_name = id_to_name.get(curve_id, curve.get("curve_name", f"curve_{curve_id}"))
+            curve_as_of = curve.get("as_of")
+
+            if not curve.get("data"):
+                continue
+
+            cdf = pl.DataFrame(curve["data"])
+            cdf = cdf.with_columns(pl.lit(curve_name).alias("curve_name"))
+            # In range mode, as_of is on each point; in snapshot mode, add from curve
+            if "as_of" not in cdf.columns:
+                cdf = cdf.with_columns(pl.lit(curve_as_of).alias("as_of"))
+            dfs.append(cdf)
+
+        if not dfs:
+            raise VoltEmptyDataError("No closing data for curves")
+
+        df = pl.concat(dfs)
+        target_tz = tz or "UTC"
+        df = df.with_columns(
+            pl.col("ts")
+            .str.to_datetime(time_unit="us", time_zone="UTC")
+            .dt.convert_time_zone(target_tz)
+        )
+        df = df.sort(["curve_name", "as_of", "ts"])
+
+        logger.info(
+            f"Extracted bulk closing data for {len(curve_names)} curves: {len(df)} rows total"
+        )
+
+        return df if self.use_polars else df.to_pandas()
+
+    def get_bulk(
+        self,
+        curve_names: list[str],
+        start_date: str,
+        end_date: str,
+        tz: str = None,
+        agg: str = None,
+        agg_func: str = None,
+    ) -> DataFrame:
+        """
+        Get time series data for multiple curves in a single request.
+
+        This is much more efficient than calling get_actual() multiple times
+        as it makes a single HTTP request and ClickHouse query.
+
+        Parameters:
+        -----------
+        curve_names : list of str
+            List of curve names to fetch
+        start_date : str
+            Start date in format 'YYYY-MM-DD'
+        end_date : str
+            End date in format 'YYYY-MM-DD'
+        tz : str, optional
+            Output timezone (e.g., 'Europe/Oslo', 'CET'). Default: UTC.
+        agg : str, optional
+            Aggregation period: 'hourly', 'daily', 'weekly', 'monthly', 'quarterly', 'yearly'.
+        agg_func : str, optional
+            Aggregation function: 'avg', 'sum', 'min', 'max'. Default: 'avg'.
+
+        Returns:
+        --------
+        DataFrame with timestamp column/index and one column per curve.
+        Returns polars DataFrame if use_polars=True, otherwise pandas DataFrame.
+        """
+        if not curve_names:
+            raise VoltClientError("curve_names cannot be empty")
+
+        # Get curve IDs for all names
+        curve_ids = []
+        name_to_id = {}
+        for name in curve_names:
+            name_lower = name.lower()
+            curve_id = self.get_curve_id(name_lower)
+            curve_ids.append(curve_id)
+            name_to_id[curve_id] = name_lower
+
+        params = {
+            "curve_ids": ",".join(str(cid) for cid in curve_ids),
+            "start_date": start_date,
+            "end_date": end_date,
+        }
+        if tz:
+            params["tz"] = tz
+        if agg:
+            params["agg"] = agg
+        if agg_func:
+            params["agg_func"] = agg_func
+
+        data = self._request("GET", "/data", params=params)
+
+        curves_data = data.get("curves", [])
+        if not curves_data:
+            raise VoltEmptyDataError(f"No data for curves between {start_date} and {end_date}")
+
+        # Always use polars internally for processing
+        dfs = []
+        for curve in curves_data:
+            curve_id = curve["curve_id"]
+            curve_name = name_to_id.get(curve_id, f"curve_{curve_id}")
+
+            if curve.get("data"):
+                df = pl.DataFrame(curve["data"])
+                target_tz = tz or "UTC"
+                df = df.with_columns(
+                    pl.col("ts")
+                    .str.to_datetime(time_unit="us", time_zone="UTC")
+                    .dt.convert_time_zone(target_tz)
+                )
+                df = df.rename({"value": curve_name})
+                df = df.select(["ts", curve_name])
+                dfs.append(df)
+
+        if not dfs:
+            raise VoltEmptyDataError(f"No data for curves between {start_date} and {end_date}")
+
+        # Join all DataFrames on timestamp using polars (much faster than pandas)
+        result = dfs[0]
+        for df in dfs[1:]:
+            result = result.join(df, on="ts", how="full", coalesce=True)
+
+        result = result.sort("ts")
+        result = result.unique(subset=["ts"], keep="last")
+
+        logger.info(
+            f"Extracted bulk data for {len(curve_names)} curves: "
+            f"{result['ts'][0]} to {result['ts'][-1]}, {len(result)} rows"
+        )
+
+        return self._to_output(result)
+
+    def get_areas(self) -> list[str]:
+        """Get list of areas the user has access to."""
+        data = self._request("GET", "/areas")
+        return data.get("areas", [])
+
+    def get_groups(self) -> list[str]:
+        """Get list of groups the user has access to."""
+        data = self._request("GET", "/groups")
+        return data.get("groups", [])
+
+    def me(self) -> dict:
+        """Get current user information."""
+        return self._request("GET", "/me")
+
+    def my_rules(self) -> dict:
+        """Get current user's permission rules."""
+        return self._request("GET", "/me/rules")

volt_client-1.0.0.dist-info/METADATA

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: volt-client
+Version: 1.0.0
+Summary: Python client for Volt Power Analytics API - Access energy market time series data
+Author-email: Volt Power Analytics <support@voltanalytics.no>
+License-Expression: MIT
+Project-URL: Homepage, https://voltpoweranalytics.com
+Project-URL: Documentation, https://github.com/Volt-Power-Analytics/volt-api/tree/main/docs
+Project-URL: Repository, https://github.com/Volt-Power-Analytics/volt-api
+Keywords: energy,api,time-series,power,market,data
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: polars>=0.20.0
+Requires-Dist: requests>=2.28.0
+Requires-Dist: orjson>=3.9.0
+Provides-Extra: pandas
+Requires-Dist: pandas>=2.0.0; extra == "pandas"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+
+# Volt Client
+
+Python client for the Volt Power Analytics API - Access energy market time series data.
+
+## Installation
+
+```bash
+pip install volt-client
+```
+
+## Quick Start
+
+```python
+import os
+from volt_client import VoltClient
+
+# Initialize with your API key
+client = VoltClient(api_key=os.environ["VOLT_API_KEY"])
+
+# Get spot prices
+df = client.get_actual(
+    "price spot no1 nordpool eur mwh min60 actual",
+    start_date="2024-01-01",
+    end_date="2024-12-31"
+)
+print(df.head())
+```
+
+## Features
+
+- Simple Python interface for Volt Power Analytics API
+- Support for historical data, forecasts, and forward curves
+- Bulk queries for efficient data retrieval
+- Timezone conversion and server-side aggregation
+- Returns pandas DataFrames (or polars for better performance)
+
+## Usage Examples
+
+### Historical Data
+
+```python
+# Single curve
+df = client.get_actual(
+    "price spot no1 nordpool eur mwh min60 actual",
+    start_date="2024-01-01",
+    end_date="2024-12-31",
+    tz="Europe/Oslo",
+    agg="daily",
+    agg_func="avg"
+)
+
+# Multiple curves (bulk query - much faster)
+df = client.get_actual(
+    ["price spot no1...", "price spot no2...", "price spot no3..."],
+    start_date="2024-01-01",
+    end_date="2024-12-31"
+)
+```
+
+### Forecast Data
+
+```python
+df = client.get_fcast(
+    "price no1 volt emps mid-term fcast",
+    start_date="2025-01-01",
+    end_date="2025-12-31",
+    freq="weekly"  # Returns percentiles: avg, p10, p25, p50, p75, p90
+)
+```
+
+### Forward Curves
+
+```python
+df = client.get_closing("price future no1 nasdaq eur mwh close")
+```
+
+### Performance Tips
+
+For large datasets, use polars mode (10x faster):
+
+```python
+client = VoltClient(api_key="...", use_polars=True)
+df = client.get_actual(...)  # Returns polars DataFrame
+```
+
+## API Reference
+
+| Method | Description |
+|--------|-------------|
+| `get_actual(curve, start, end)` | Get historical/actual data |
+| `get_fcast(curve, start, end)` | Get forecast data |
+| `get_closing(curve)` | Get forward curve prices |
+| `search(area=None)` | Search available curves |
+| `get_areas()` | List accessible areas |
+| `get_groups()` | List accessible groups |
+
+## Documentation
+
+Full documentation: https://github.com/Volt-Power-Analytics/volt-api/tree/main/docs
+
+## Support
+
+Contact: support@voltanalytics.no

volt_client-1.0.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+volt_client/__init__.py,sha256=Q8uuwfiSqVyDsYOELc0nts1A_StcmdZVcp1tv7KsfSY,605
+volt_client/client.py,sha256=4he1uSL1NsCqZjWGJqV1Tme0YVCKRafn9hSJ2f33REs,28408
+volt_client-1.0.0.dist-info/METADATA,sha256=rMwKnKyyYmx1ShO1lc3AxiHis8ZJJPdJB8bKiepXqXM,3470
+volt_client-1.0.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+volt_client-1.0.0.dist-info/top_level.txt,sha256=BWXHOWfVwSZW7GgLwFjWUEgeFmPWCs3XK8B1DjNNtYs,12
+volt_client-1.0.0.dist-info/RECORD,,

volt_client-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

volt_client-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+volt_client