tickerapi 0.1.0__py3-none-any.whl

tickerapi/__init__.py

@@ -0,0 +1,40 @@
+"""TickerAPI Python SDK - Financial data at your fingertips.
+
+Usage::
+
+    from tickerapi import TickerAPI
+
+    client = TickerAPI("your_api_key")
+    result = client.summary("AAPL")
+
+For async usage::
+
+    from tickerapi import AsyncTickerAPI
+
+    async with AsyncTickerAPI("your_api_key") as client:
+        result = await client.summary("AAPL")
+"""
+
+from .async_client import AsyncTickerAPI
+from .client import TickerAPI
+from .exceptions import (
+    AuthenticationError,
+    DataUnavailableError,
+    ForbiddenError,
+    NotFoundError,
+    RateLimitError,
+    TickerAPIError,
+)
+
+__all__ = [
+    "TickerAPI",
+    "AsyncTickerAPI",
+    "TickerAPIError",
+    "AuthenticationError",
+    "ForbiddenError",
+    "NotFoundError",
+    "RateLimitError",
+    "DataUnavailableError",
+]
+
+__version__ = "0.1.0"

tickerapi/async_client.py

@@ -0,0 +1,436 @@
+"""Asynchronous TickerAPI client."""
+
+from typing import Any, Dict, List, Optional, Union
+
+import httpx
+
+from .exceptions import (
+    AuthenticationError,
+    DataUnavailableError,
+    ForbiddenError,
+    NotFoundError,
+    RateLimitError,
+    TickerAPIError,
+)
+from .types import RateLimits
+
+_DEFAULT_BASE_URL = "https://api.tickerapi.ai/v1"
+_DEFAULT_TIMEOUT = 30.0
+
+
+def _parse_rate_limits(headers: httpx.Headers) -> RateLimits:
+    """Extract rate-limit information from response headers."""
+
+    def _int_or_none(key: str) -> Optional[int]:
+        val = headers.get(key)
+        if val is None:
+            return None
+        try:
+            return int(val)
+        except (ValueError, TypeError):
+            return None
+
+    return RateLimits(
+        request_limit=_int_or_none("X-Request-Limit"),
+        requests_used=_int_or_none("X-Requests-Used"),
+        requests_remaining=_int_or_none("X-Requests-Remaining"),
+        request_reset=headers.get("X-Request-Reset"),
+        hourly_request_limit=_int_or_none("X-Hourly-Request-Limit"),
+        hourly_requests_used=_int_or_none("X-Hourly-Requests-Used"),
+        hourly_requests_remaining=_int_or_none("X-Hourly-Requests-Remaining"),
+        hourly_request_reset=headers.get("X-Hourly-Request-Reset"),
+    )
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    """Raise a typed TickerAPIError if the response indicates an error."""
+    if response.status_code < 400:
+        return
+
+    try:
+        body = response.json()
+    except Exception:
+        raise TickerAPIError(
+            status_code=response.status_code,
+            error_type="unknown_error",
+            message=response.text or "Unknown error",
+        )
+
+    error = body.get("error", {})
+    error_type = error.get("type", "unknown_error")
+    message = error.get("message", "Unknown error")
+    upgrade_url = error.get("upgrade_url")
+    reset = error.get("reset")
+
+    kwargs: Dict[str, Any] = dict(
+        status_code=response.status_code,
+        error_type=error_type,
+        message=message,
+        upgrade_url=upgrade_url,
+        reset=reset,
+        raw=body,
+    )
+
+    error_cls = {
+        401: AuthenticationError,
+        403: ForbiddenError,
+        404: NotFoundError,
+        429: RateLimitError,
+        503: DataUnavailableError,
+    }.get(response.status_code, TickerAPIError)
+
+    raise error_cls(**kwargs)
+
+
+class AsyncTickerAPI:
+    """Asynchronous client for the TickerAPI financial data API.
+
+    Args:
+        api_key: Your TickerAPI bearer token.
+        base_url: Override the default API base URL.
+        timeout: Request timeout in seconds (default 30).
+        **httpx_kwargs: Additional keyword arguments forwarded to ``httpx.AsyncClient``.
+
+    Usage::
+
+        import asyncio
+        from tickerapi import AsyncTickerAPI
+
+        async def main():
+            async with AsyncTickerAPI("your_api_key") as client:
+                result = await client.summary("AAPL")
+                print(result["data"])
+
+        asyncio.run(main())
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: float = _DEFAULT_TIMEOUT,
+        **httpx_kwargs: Any,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._client = httpx.AsyncClient(
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Accept": "application/json",
+                "User-Agent": "tickerapi-python/0.1.0",
+            },
+            timeout=timeout,
+            **httpx_kwargs,
+        )
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Dict[str, Any]] = None,
+        json: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Send a request and return parsed data + rate limits."""
+        url = f"{self._base_url}{path}"
+
+        if params:
+            params = {k: v for k, v in params.items() if v is not None}
+
+        response = await self._client.request(method, url, params=params, json=json)
+        _raise_for_status(response)
+
+        data = response.json()
+        rate_limits = _parse_rate_limits(response.headers)
+
+        return {"data": data, "rate_limits": rate_limits}
+
+    # ------------------------------------------------------------------
+    # Public API methods
+    # ------------------------------------------------------------------
+
+    async def summary(
+        self,
+        ticker: str,
+        *,
+        timeframe: Optional[str] = None,
+        date: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Get a summary for a single ticker.
+
+        Args:
+            ticker: Asset ticker symbol (e.g. ``"AAPL"``).
+            timeframe: ``"daily"`` or ``"weekly"`` (default ``"daily"``).
+            date: ISO 8601 date string (``YYYY-MM-DD``).
+
+        Returns:
+            Dict with ``data`` and ``rate_limits`` keys.
+        """
+        return await self._request(
+            "GET",
+            f"/summary/{ticker}",
+            params={"timeframe": timeframe, "date": date},
+        )
+
+    async def compare(
+        self,
+        tickers: Union[List[str], str],
+        *,
+        timeframe: Optional[str] = None,
+        date: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Compare multiple tickers side-by-side.
+
+        Args:
+            tickers: List of ticker symbols or a comma-separated string.
+            timeframe: ``"daily"`` or ``"weekly"``.
+            date: ISO 8601 date string.
+
+        Returns:
+            Dict with ``data`` and ``rate_limits`` keys.
+        """
+        if isinstance(tickers, list):
+            tickers = ",".join(tickers)
+        return await self._request(
+            "GET",
+            "/compare",
+            params={"tickers": tickers, "timeframe": timeframe, "date": date},
+        )
+
+    async def watchlist(
+        self,
+        tickers: List[str],
+        *,
+        timeframe: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Get watchlist data for multiple tickers.
+
+        Args:
+            tickers: List of ticker symbols.
+            timeframe: ``"daily"`` or ``"weekly"``.
+
+        Returns:
+            Dict with ``data`` and ``rate_limits`` keys.
+        """
+        body: Dict[str, Any] = {"tickers": tickers}
+        if timeframe is not None:
+            body["timeframe"] = timeframe
+        return await self._request("POST", "/watchlist", json=body)
+
+    async def assets(self) -> Dict[str, Any]:
+        """List all available assets.
+
+        Returns:
+            Dict with ``data`` and ``rate_limits`` keys.
+        """
+        return await self._request("GET", "/assets")
+
+    async def scan_oversold(
+        self,
+        *,
+        timeframe: Optional[str] = None,
+        asset_class: Optional[str] = None,
+        sector: Optional[str] = None,
+        min_severity: Optional[str] = None,
+        sort_by: Optional[str] = None,
+        limit: Optional[int] = None,
+        date: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Scan for oversold assets.
+
+        Args:
+            timeframe: ``"daily"`` or ``"weekly"``.
+            asset_class: ``"stock"``, ``"crypto"``, ``"etf"``, or ``"all"``.
+            sector: Filter by sector.
+            min_severity: ``"oversold"`` or ``"deep_oversold"``.
+            sort_by: ``"severity"``, ``"days_oversold"``, or ``"condition_percentile"``.
+            limit: Max results (1-50).
+            date: ISO 8601 date string.
+
+        Returns:
+            Dict with ``data`` and ``rate_limits`` keys.
+        """
+        return await self._request(
+            "GET",
+            "/scan/oversold",
+            params={
+                "timeframe": timeframe,
+                "asset_class": asset_class,
+                "sector": sector,
+                "min_severity": min_severity,
+                "sort_by": sort_by,
+                "limit": limit,
+                "date": date,
+            },
+        )
+
+    async def scan_breakouts(
+        self,
+        *,
+        timeframe: Optional[str] = None,
+        asset_class: Optional[str] = None,
+        sector: Optional[str] = None,
+        direction: Optional[str] = None,
+        sort_by: Optional[str] = None,
+        limit: Optional[int] = None,
+        date: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Scan for breakout patterns.
+
+        Args:
+            timeframe: ``"daily"`` or ``"weekly"``.
+            asset_class: ``"stock"``, ``"crypto"``, ``"etf"``, or ``"all"``.
+            sector: Filter by sector.
+            direction: ``"bullish"``, ``"bearish"``, or ``"all"``.
+            sort_by: ``"volume_ratio"``, ``"level_strength"``, or ``"condition_percentile"``.
+            limit: Max results (1-50).
+            date: ISO 8601 date string.
+
+        Returns:
+            Dict with ``data`` and ``rate_limits`` keys.
+        """
+        return await self._request(
+            "GET",
+            "/scan/breakouts",
+            params={
+                "timeframe": timeframe,
+                "asset_class": asset_class,
+                "sector": sector,
+                "direction": direction,
+                "sort_by": sort_by,
+                "limit": limit,
+                "date": date,
+            },
+        )
+
+    async def scan_unusual_volume(
+        self,
+        *,
+        timeframe: Optional[str] = None,
+        asset_class: Optional[str] = None,
+        sector: Optional[str] = None,
+        min_ratio_band: Optional[str] = None,
+        sort_by: Optional[str] = None,
+        limit: Optional[int] = None,
+        date: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Scan for unusual volume activity.
+
+        Args:
+            timeframe: ``"daily"`` or ``"weekly"``.
+            asset_class: ``"stock"``, ``"crypto"``, ``"etf"``, or ``"all"``.
+            sector: Filter by sector.
+            min_ratio_band: ``"extremely_low"``, ``"low"``, ``"normal"``,
+                ``"elevated"``, ``"high"``, or ``"extremely_high"``.
+            sort_by: ``"volume_percentile"``.
+            limit: Max results (1-50).
+            date: ISO 8601 date string.
+
+        Returns:
+            Dict with ``data`` and ``rate_limits`` keys.
+        """
+        return await self._request(
+            "GET",
+            "/scan/unusual-volume",
+            params={
+                "timeframe": timeframe,
+                "asset_class": asset_class,
+                "sector": sector,
+                "min_ratio_band": min_ratio_band,
+                "sort_by": sort_by,
+                "limit": limit,
+                "date": date,
+            },
+        )
+
+    async def scan_valuation(
+        self,
+        *,
+        timeframe: Optional[str] = None,
+        sector: Optional[str] = None,
+        direction: Optional[str] = None,
+        min_severity: Optional[str] = None,
+        sort_by: Optional[str] = None,
+        limit: Optional[int] = None,
+        date: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Scan for valuation outliers.
+
+        Args:
+            timeframe: ``"daily"`` or ``"weekly"``.
+            sector: Filter by sector.
+            direction: ``"undervalued"``, ``"overvalued"``, or ``"all"``.
+            min_severity: ``"deep_value"`` or ``"extreme_premium"``.
+            sort_by: ``"valuation_percentile"`` or ``"pe_vs_history"``.
+            limit: Max results (1-50).
+            date: ISO 8601 date string.
+
+        Returns:
+            Dict with ``data`` and ``rate_limits`` keys.
+        """
+        return await self._request(
+            "GET",
+            "/scan/valuation",
+            params={
+                "timeframe": timeframe,
+                "sector": sector,
+                "direction": direction,
+                "min_severity": min_severity,
+                "sort_by": sort_by,
+                "limit": limit,
+                "date": date,
+            },
+        )
+
+    async def scan_insider_activity(
+        self,
+        *,
+        timeframe: Optional[str] = None,
+        sector: Optional[str] = None,
+        direction: Optional[str] = None,
+        sort_by: Optional[str] = None,
+        limit: Optional[int] = None,
+        date: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Scan for notable insider trading activity.
+
+        Args:
+            timeframe: ``"daily"`` or ``"weekly"``.
+            sector: Filter by sector.
+            direction: ``"buying"``, ``"selling"``, or ``"all"``.
+            sort_by: ``"zone_severity"``, ``"shares_volume"``, or ``"net_ratio"``.
+            limit: Max results (1-50).
+            date: ISO 8601 date string.
+
+        Returns:
+            Dict with ``data`` and ``rate_limits`` keys.
+        """
+        return await self._request(
+            "GET",
+            "/scan/insider-activity",
+            params={
+                "timeframe": timeframe,
+                "sector": sector,
+                "direction": direction,
+                "sort_by": sort_by,
+                "limit": limit,
+                "date": date,
+            },
+        )
+
+    # ------------------------------------------------------------------
+    # Context manager support
+    # ------------------------------------------------------------------
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client."""
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncTickerAPI":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()

tickerapi/client.py

@@ -0,0 +1,434 @@
+"""Synchronous TickerAPI client."""
+
+from typing import Any, Dict, List, Optional, Union
+
+import httpx
+
+from .exceptions import (
+    AuthenticationError,
+    DataUnavailableError,
+    ForbiddenError,
+    NotFoundError,
+    RateLimitError,
+    TickerAPIError,
+)
+from .types import RateLimits
+
+_DEFAULT_BASE_URL = "https://api.tickerapi.ai/v1"
+_DEFAULT_TIMEOUT = 30.0
+
+
+def _parse_rate_limits(headers: httpx.Headers) -> RateLimits:
+    """Extract rate-limit information from response headers."""
+
+    def _int_or_none(key: str) -> Optional[int]:
+        val = headers.get(key)
+        if val is None:
+            return None
+        try:
+            return int(val)
+        except (ValueError, TypeError):
+            return None
+
+    return RateLimits(
+        request_limit=_int_or_none("X-Request-Limit"),
+        requests_used=_int_or_none("X-Requests-Used"),
+        requests_remaining=_int_or_none("X-Requests-Remaining"),
+        request_reset=headers.get("X-Request-Reset"),
+        hourly_request_limit=_int_or_none("X-Hourly-Request-Limit"),
+        hourly_requests_used=_int_or_none("X-Hourly-Requests-Used"),
+        hourly_requests_remaining=_int_or_none("X-Hourly-Requests-Remaining"),
+        hourly_request_reset=headers.get("X-Hourly-Request-Reset"),
+    )
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    """Raise a typed TickerAPIError if the response indicates an error."""
+    if response.status_code < 400:
+        return
+
+    try:
+        body = response.json()
+    except Exception:
+        raise TickerAPIError(
+            status_code=response.status_code,
+            error_type="unknown_error",
+            message=response.text or "Unknown error",
+        )
+
+    error = body.get("error", {})
+    error_type = error.get("type", "unknown_error")
+    message = error.get("message", "Unknown error")
+    upgrade_url = error.get("upgrade_url")
+    reset = error.get("reset")
+
+    kwargs: Dict[str, Any] = dict(
+        status_code=response.status_code,
+        error_type=error_type,
+        message=message,
+        upgrade_url=upgrade_url,
+        reset=reset,
+        raw=body,
+    )
+
+    error_cls = {
+        401: AuthenticationError,
+        403: ForbiddenError,
+        404: NotFoundError,
+        429: RateLimitError,
+        503: DataUnavailableError,
+    }.get(response.status_code, TickerAPIError)
+
+    raise error_cls(**kwargs)
+
+
+class TickerAPI:
+    """Synchronous client for the TickerAPI financial data API.
+
+    Args:
+        api_key: Your TickerAPI bearer token.
+        base_url: Override the default API base URL.
+        timeout: Request timeout in seconds (default 30).
+        **httpx_kwargs: Additional keyword arguments forwarded to ``httpx.Client``.
+
+    Usage::
+
+        from tickerapi import TickerAPI
+
+        client = TickerAPI("your_api_key")
+        result = client.summary("AAPL")
+        print(result["data"])
+        print(result["rate_limits"])
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: float = _DEFAULT_TIMEOUT,
+        **httpx_kwargs: Any,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._client = httpx.Client(
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Accept": "application/json",
+                "User-Agent": "tickerapi-python/0.1.0",
+            },
+            timeout=timeout,
+            **httpx_kwargs,
+        )
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Dict[str, Any]] = None,
+        json: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Send a request and return parsed data + rate limits."""
+        url = f"{self._base_url}{path}"
+
+        # Strip None values from params
+        if params:
+            params = {k: v for k, v in params.items() if v is not None}
+
+        response = self._client.request(method, url, params=params, json=json)
+        _raise_for_status(response)
+
+        data = response.json()
+        rate_limits = _parse_rate_limits(response.headers)
+
+        return {"data": data, "rate_limits": rate_limits}
+
+    # ------------------------------------------------------------------
+    # Public API methods
+    # ------------------------------------------------------------------
+
+    def summary(
+        self,
+        ticker: str,
+        *,
+        timeframe: Optional[str] = None,
+        date: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Get a summary for a single ticker.
+
+        Args:
+            ticker: Asset ticker symbol (e.g. ``"AAPL"``).
+            timeframe: ``"daily"`` or ``"weekly"`` (default ``"daily"``).
+            date: ISO 8601 date string (``YYYY-MM-DD``).
+
+        Returns:
+            Dict with ``data`` and ``rate_limits`` keys.
+        """
+        return self._request(
+            "GET",
+            f"/summary/{ticker}",
+            params={"timeframe": timeframe, "date": date},
+        )
+
+    def compare(
+        self,
+        tickers: Union[List[str], str],
+        *,
+        timeframe: Optional[str] = None,
+        date: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Compare multiple tickers side-by-side.
+
+        Args:
+            tickers: List of ticker symbols or a comma-separated string.
+            timeframe: ``"daily"`` or ``"weekly"``.
+            date: ISO 8601 date string.
+
+        Returns:
+            Dict with ``data`` and ``rate_limits`` keys.
+        """
+        if isinstance(tickers, list):
+            tickers = ",".join(tickers)
+        return self._request(
+            "GET",
+            "/compare",
+            params={"tickers": tickers, "timeframe": timeframe, "date": date},
+        )
+
+    def watchlist(
+        self,
+        tickers: List[str],
+        *,
+        timeframe: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Get watchlist data for multiple tickers.
+
+        Args:
+            tickers: List of ticker symbols.
+            timeframe: ``"daily"`` or ``"weekly"``.
+
+        Returns:
+            Dict with ``data`` and ``rate_limits`` keys.
+        """
+        body: Dict[str, Any] = {"tickers": tickers}
+        if timeframe is not None:
+            body["timeframe"] = timeframe
+        return self._request("POST", "/watchlist", json=body)
+
+    def assets(self) -> Dict[str, Any]:
+        """List all available assets.
+
+        Returns:
+            Dict with ``data`` and ``rate_limits`` keys.
+        """
+        return self._request("GET", "/assets")
+
+    def scan_oversold(
+        self,
+        *,
+        timeframe: Optional[str] = None,
+        asset_class: Optional[str] = None,
+        sector: Optional[str] = None,
+        min_severity: Optional[str] = None,
+        sort_by: Optional[str] = None,
+        limit: Optional[int] = None,
+        date: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Scan for oversold assets.
+
+        Args:
+            timeframe: ``"daily"`` or ``"weekly"``.
+            asset_class: ``"stock"``, ``"crypto"``, ``"etf"``, or ``"all"``.
+            sector: Filter by sector.
+            min_severity: ``"oversold"`` or ``"deep_oversold"``.
+            sort_by: ``"severity"``, ``"days_oversold"``, or ``"condition_percentile"``.
+            limit: Max results (1-50).
+            date: ISO 8601 date string.
+
+        Returns:
+            Dict with ``data`` and ``rate_limits`` keys.
+        """
+        return self._request(
+            "GET",
+            "/scan/oversold",
+            params={
+                "timeframe": timeframe,
+                "asset_class": asset_class,
+                "sector": sector,
+                "min_severity": min_severity,
+                "sort_by": sort_by,
+                "limit": limit,
+                "date": date,
+            },
+        )
+
+    def scan_breakouts(
+        self,
+        *,
+        timeframe: Optional[str] = None,
+        asset_class: Optional[str] = None,
+        sector: Optional[str] = None,
+        direction: Optional[str] = None,
+        sort_by: Optional[str] = None,
+        limit: Optional[int] = None,
+        date: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Scan for breakout patterns.
+
+        Args:
+            timeframe: ``"daily"`` or ``"weekly"``.
+            asset_class: ``"stock"``, ``"crypto"``, ``"etf"``, or ``"all"``.
+            sector: Filter by sector.
+            direction: ``"bullish"``, ``"bearish"``, or ``"all"``.
+            sort_by: ``"volume_ratio"``, ``"level_strength"``, or ``"condition_percentile"``.
+            limit: Max results (1-50).
+            date: ISO 8601 date string.
+
+        Returns:
+            Dict with ``data`` and ``rate_limits`` keys.
+        """
+        return self._request(
+            "GET",
+            "/scan/breakouts",
+            params={
+                "timeframe": timeframe,
+                "asset_class": asset_class,
+                "sector": sector,
+                "direction": direction,
+                "sort_by": sort_by,
+                "limit": limit,
+                "date": date,
+            },
+        )
+
+    def scan_unusual_volume(
+        self,
+        *,
+        timeframe: Optional[str] = None,
+        asset_class: Optional[str] = None,
+        sector: Optional[str] = None,
+        min_ratio_band: Optional[str] = None,
+        sort_by: Optional[str] = None,
+        limit: Optional[int] = None,
+        date: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Scan for unusual volume activity.
+
+        Args:
+            timeframe: ``"daily"`` or ``"weekly"``.
+            asset_class: ``"stock"``, ``"crypto"``, ``"etf"``, or ``"all"``.
+            sector: Filter by sector.
+            min_ratio_band: ``"extremely_low"``, ``"low"``, ``"normal"``,
+                ``"elevated"``, ``"high"``, or ``"extremely_high"``.
+            sort_by: ``"volume_percentile"``.
+            limit: Max results (1-50).
+            date: ISO 8601 date string.
+
+        Returns:
+            Dict with ``data`` and ``rate_limits`` keys.
+        """
+        return self._request(
+            "GET",
+            "/scan/unusual-volume",
+            params={
+                "timeframe": timeframe,
+                "asset_class": asset_class,
+                "sector": sector,
+                "min_ratio_band": min_ratio_band,
+                "sort_by": sort_by,
+                "limit": limit,
+                "date": date,
+            },
+        )
+
+    def scan_valuation(
+        self,
+        *,
+        timeframe: Optional[str] = None,
+        sector: Optional[str] = None,
+        direction: Optional[str] = None,
+        min_severity: Optional[str] = None,
+        sort_by: Optional[str] = None,
+        limit: Optional[int] = None,
+        date: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Scan for valuation outliers.
+
+        Args:
+            timeframe: ``"daily"`` or ``"weekly"``.
+            sector: Filter by sector.
+            direction: ``"undervalued"``, ``"overvalued"``, or ``"all"``.
+            min_severity: ``"deep_value"`` or ``"extreme_premium"``.
+            sort_by: ``"valuation_percentile"`` or ``"pe_vs_history"``.
+            limit: Max results (1-50).
+            date: ISO 8601 date string.
+
+        Returns:
+            Dict with ``data`` and ``rate_limits`` keys.
+        """
+        return self._request(
+            "GET",
+            "/scan/valuation",
+            params={
+                "timeframe": timeframe,
+                "sector": sector,
+                "direction": direction,
+                "min_severity": min_severity,
+                "sort_by": sort_by,
+                "limit": limit,
+                "date": date,
+            },
+        )
+
+    def scan_insider_activity(
+        self,
+        *,
+        timeframe: Optional[str] = None,
+        sector: Optional[str] = None,
+        direction: Optional[str] = None,
+        sort_by: Optional[str] = None,
+        limit: Optional[int] = None,
+        date: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Scan for notable insider trading activity.
+
+        Args:
+            timeframe: ``"daily"`` or ``"weekly"``.
+            sector: Filter by sector.
+            direction: ``"buying"``, ``"selling"``, or ``"all"``.
+            sort_by: ``"zone_severity"``, ``"shares_volume"``, or ``"net_ratio"``.
+            limit: Max results (1-50).
+            date: ISO 8601 date string.
+
+        Returns:
+            Dict with ``data`` and ``rate_limits`` keys.
+        """
+        return self._request(
+            "GET",
+            "/scan/insider-activity",
+            params={
+                "timeframe": timeframe,
+                "sector": sector,
+                "direction": direction,
+                "sort_by": sort_by,
+                "limit": limit,
+                "date": date,
+            },
+        )
+
+    # ------------------------------------------------------------------
+    # Context manager support
+    # ------------------------------------------------------------------
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._client.close()
+
+    def __enter__(self) -> "TickerAPI":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()

tickerapi/exceptions.py

@@ -0,0 +1,53 @@
+"""Exceptions for the TickerAPI SDK."""
+
+from typing import Any, Dict, Optional
+
+
+class TickerAPIError(Exception):
+    """Raised when the TickerAPI returns an error response.
+
+    Attributes:
+        status_code: HTTP status code of the response.
+        error_type: Error type string from the API (e.g. "authentication_error").
+        message: Human-readable error message.
+        upgrade_url: URL to upgrade the API plan (present on 403/429 errors).
+        reset: Rate limit reset timestamp (present on 429 errors).
+        raw: The full parsed error body from the API.
+    """
+
+    def __init__(
+        self,
+        status_code: int,
+        error_type: str,
+        message: str,
+        upgrade_url: Optional[str] = None,
+        reset: Optional[str] = None,
+        raw: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        self.status_code = status_code
+        self.error_type = error_type
+        self.message = message
+        self.upgrade_url = upgrade_url
+        self.reset = reset
+        self.raw = raw or {}
+        super().__init__(f"[{status_code}] {error_type}: {message}")
+
+
+class AuthenticationError(TickerAPIError):
+    """Raised on 401 responses (invalid or missing API key)."""
+
+
+class ForbiddenError(TickerAPIError):
+    """Raised on 403 responses (tier-restricted endpoint)."""
+
+
+class NotFoundError(TickerAPIError):
+    """Raised on 404 responses (asset not found)."""
+
+
+class RateLimitError(TickerAPIError):
+    """Raised on 429 responses (rate limit exceeded)."""
+
+
+class DataUnavailableError(TickerAPIError):
+    """Raised on 503 responses (data temporarily unavailable)."""

tickerapi/types.py

@@ -0,0 +1,112 @@
+"""TypedDict definitions for TickerAPI SDK parameters and responses."""
+
+import sys
+from typing import Any, Dict, List, Optional
+
+if sys.version_info >= (3, 8):
+    from typing import Literal, TypedDict
+else:
+    from typing_extensions import Literal, TypedDict
+
+
+# ---------------------------------------------------------------------------
+# Common types
+# ---------------------------------------------------------------------------
+
+Timeframe = Literal["daily", "weekly"]
+AssetClass = Literal["stock", "crypto", "etf", "all"]
+
+# ---------------------------------------------------------------------------
+# Rate limit information returned with every response
+# ---------------------------------------------------------------------------
+
+
+class RateLimits(TypedDict, total=False):
+    """Rate limit information parsed from response headers."""
+
+    request_limit: Optional[int]
+    requests_used: Optional[int]
+    requests_remaining: Optional[int]
+    request_reset: Optional[str]
+    hourly_request_limit: Optional[int]
+    hourly_requests_used: Optional[int]
+    hourly_requests_remaining: Optional[int]
+    hourly_request_reset: Optional[str]
+
+
+# ---------------------------------------------------------------------------
+# Scan parameter TypedDicts (for IDE autocompletion)
+# ---------------------------------------------------------------------------
+
+
+class OversoldParams(TypedDict, total=False):
+    """Parameters for the oversold scan endpoint."""
+
+    timeframe: Timeframe
+    asset_class: AssetClass
+    sector: str
+    min_severity: Literal["oversold", "deep_oversold"]
+    sort_by: Literal["severity", "days_oversold", "condition_percentile"]
+    limit: int
+    date: str
+
+
+class BreakoutsParams(TypedDict, total=False):
+    """Parameters for the breakouts scan endpoint."""
+
+    timeframe: Timeframe
+    asset_class: AssetClass
+    sector: str
+    direction: Literal["bullish", "bearish", "all"]
+    sort_by: Literal["volume_ratio", "level_strength", "condition_percentile"]
+    limit: int
+    date: str
+
+
+class UnusualVolumeParams(TypedDict, total=False):
+    """Parameters for the unusual volume scan endpoint."""
+
+    timeframe: Timeframe
+    asset_class: AssetClass
+    sector: str
+    min_ratio_band: Literal[
+        "extremely_low", "low", "normal", "elevated", "high", "extremely_high"
+    ]
+    sort_by: Literal["volume_percentile"]
+    limit: int
+    date: str
+
+
+class ValuationParams(TypedDict, total=False):
+    """Parameters for the valuation scan endpoint."""
+
+    timeframe: Timeframe
+    sector: str
+    direction: Literal["undervalued", "overvalued", "all"]
+    min_severity: Literal["deep_value", "extreme_premium"]
+    sort_by: Literal["valuation_percentile", "pe_vs_history"]
+    limit: int
+    date: str
+
+
+class InsiderActivityParams(TypedDict, total=False):
+    """Parameters for the insider activity scan endpoint."""
+
+    timeframe: Timeframe
+    sector: str
+    direction: Literal["buying", "selling", "all"]
+    sort_by: Literal["zone_severity", "shares_volume", "net_ratio"]
+    limit: int
+    date: str
+
+
+# ---------------------------------------------------------------------------
+# API response wrapper
+# ---------------------------------------------------------------------------
+
+
+class APIResponse(TypedDict):
+    """Every SDK method returns a dict with parsed JSON data and rate limits."""
+
+    data: Any
+    rate_limits: RateLimits

tickerapi-0.1.0.dist-info/METADATA

@@ -0,0 +1,216 @@
+Metadata-Version: 2.4
+Name: tickerapi
+Version: 0.1.0
+Summary: Python SDK for the TickerAPI financial data API
+Project-URL: Homepage, https://tickerapi.ai
+Project-URL: Documentation, https://tickerapi.ai/docs
+Project-URL: Repository, https://github.com/tickerapi/tickerapi-python
+Project-URL: Issues, https://github.com/tickerapi/tickerapi-python/issues
+Author-email: TickerAPI <support@tickerapi.ai>
+License-Expression: MIT
+Keywords: api,crypto,etf,finance,market-data,stocks,ticker
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Requires-Dist: httpx>=0.24.0
+Description-Content-Type: text/markdown
+
+# TickerAPI Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/tickerapi.svg)](https://pypi.org/project/tickerapi/)
+[![Python versions](https://img.shields.io/pypi/pyversions/tickerapi.svg)](https://pypi.org/project/tickerapi/)
+
+The official Python SDK for [TickerAPI](https://tickerapi.ai) -- financial data and market intelligence API.
+
+- Sync and async clients
+- Full type hints for IDE autocompletion
+- Typed exceptions for every error class
+- Rate limit information on every response
+
+**Full API documentation:** [https://tickerapi.ai/docs](https://tickerapi.ai/docs)
+
+## Installation
+
+```bash
+pip install tickerapi
+```
+
+## Quick Start
+
+### Synchronous
+
+```python
+from tickerapi import TickerAPI
+
+client = TickerAPI("your_api_key")
+
+# Get a ticker summary
+result = client.summary("AAPL")
+print(result["data"])
+
+# Rate limit info is included on every response
+print(result["rate_limits"]["requests_remaining"])
+```
+
+### Asynchronous
+
+```python
+import asyncio
+from tickerapi import AsyncTickerAPI
+
+async def main():
+    async with AsyncTickerAPI("your_api_key") as client:
+        result = await client.summary("AAPL")
+        print(result["data"])
+
+asyncio.run(main())
+```
+
+## Endpoints
+
+### Summary
+
+Get a detailed summary for a single ticker.
+
+```python
+result = client.summary("AAPL")
+result = client.summary("AAPL", timeframe="weekly")
+result = client.summary("AAPL", date="2025-01-15")
+```
+
+### Compare
+
+Compare multiple tickers side-by-side.
+
+```python
+result = client.compare(["AAPL", "MSFT", "GOOGL"])
+result = client.compare("AAPL,MSFT,GOOGL", timeframe="weekly")
+```
+
+### Watchlist
+
+Post a list of tickers to get watchlist data.
+
+```python
+result = client.watchlist(["AAPL", "MSFT", "TSLA"])
+result = client.watchlist(["AAPL", "MSFT"], timeframe="weekly")
+```
+
+### Assets
+
+List all available assets.
+
+```python
+result = client.assets()
+```
+
+### Scan: Oversold
+
+Find oversold assets across markets.
+
+```python
+result = client.scan_oversold()
+result = client.scan_oversold(
+    asset_class="stock",
+    min_severity="deep_oversold",
+    sort_by="severity",
+    limit=10,
+)
+```
+
+### Scan: Breakouts
+
+Detect breakout patterns.
+
+```python
+result = client.scan_breakouts(direction="bullish", asset_class="stock", limit=20)
+```
+
+### Scan: Unusual Volume
+
+Spot unusual volume activity.
+
+```python
+result = client.scan_unusual_volume(min_ratio_band="high", limit=10)
+```
+
+### Scan: Valuation
+
+Find valuation outliers.
+
+```python
+result = client.scan_valuation(direction="undervalued", sort_by="pe_vs_history")
+```
+
+### Scan: Insider Activity
+
+Track notable insider trading activity.
+
+```python
+result = client.scan_insider_activity(direction="buying", sort_by="net_ratio", limit=15)
+```
+
+## Error Handling
+
+The SDK raises typed exceptions for all API errors:
+
+```python
+from tickerapi import TickerAPI, TickerAPIError, RateLimitError, NotFoundError
+
+client = TickerAPI("your_api_key")
+
+try:
+    result = client.summary("INVALID_TICKER")
+except NotFoundError as e:
+    print(f"Ticker not found: {e.message}")
+except RateLimitError as e:
+    print(f"Rate limited! Resets at: {e.reset}")
+    print(f"Upgrade: {e.upgrade_url}")
+except TickerAPIError as e:
+    print(f"API error [{e.status_code}]: {e.message}")
+```
+
+### Exception Hierarchy
+
+| Exception | Status Code | Description |
+|---|---|---|
+| `TickerAPIError` | any | Base exception for all API errors |
+| `AuthenticationError` | 401 | Invalid or missing API key |
+| `ForbiddenError` | 403 | Endpoint restricted to higher tier |
+| `NotFoundError` | 404 | Asset not found |
+| `RateLimitError` | 429 | Rate limit exceeded |
+| `DataUnavailableError` | 503 | Data temporarily unavailable |
+
+All exceptions include `status_code`, `error_type`, `message`, and optionally `upgrade_url` and `reset` attributes.
+
+## Rate Limits
+
+Every response includes a `rate_limits` dict parsed from the API headers:
+
+```python
+result = client.summary("AAPL")
+limits = result["rate_limits"]
+
+print(limits["request_limit"])           # Total request limit
+print(limits["requests_remaining"])      # Requests remaining
+print(limits["request_reset"])           # Reset timestamp
+print(limits["hourly_request_limit"])    # Hourly limit
+print(limits["hourly_requests_remaining"])  # Hourly remaining
+```
+
+## Links
+
+- [TickerAPI Website](https://tickerapi.ai)
+- [API Documentation](https://tickerapi.ai/docs)
+- [PyPI Package](https://pypi.org/project/tickerapi/)

tickerapi-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+tickerapi/__init__.py,sha256=xOj6HVMqeSCo22I9GSEcMgV31YMF_UizdnQD5899SfE,801
+tickerapi/async_client.py,sha256=CvTD9oR_2mhdOp-WbzRFGi87kM3t4xOwdolyNM4f_AM,13624
+tickerapi/client.py,sha256=hhw-NmKih8S9W0KM8AmAu8HNkStR8-GdhhSkvYyjj-0,13399
+tickerapi/exceptions.py,sha256=EM7Jdzx9TKO_l3D41unDaRZec0tBXRj60o5e_NR2I6M,1613
+tickerapi/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tickerapi/types.py,sha256=6w5vPc_BGmZrQeaYknNUQtZ0z-UnXtxxyI-oTshuXpo,3387
+tickerapi-0.1.0.dist-info/METADATA,sha256=4S9xdlbF5rmttX-icT0flN-9hKpEEI6phhdK9p9aewg,5623
+tickerapi-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+tickerapi-0.1.0.dist-info/RECORD,,

tickerapi-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any