marketstack-python-client 1.0.0__py3-none-any.whl

marketstack/namespaces/exchanges/exchanges.py

@@ -0,0 +1,109 @@
+from marketstack.client.http import HTTPClient
+from typing import Unpack
+from marketstack.models.exchange import (
+    Exchange,
+    ExchangesResponse,
+    ExchangeMicTickersResponse,
+    ExchangesMicEod,
+    ExchangesMicIntraday,
+    ExchangesMicIntradayLatest,
+    ExchangesRequest,
+    ExchangeTickersRequest,
+)
+from marketstack.models.eod import EODRequest, EODLatestRequest
+from marketstack.models.intraday import IntradayResponse, IntradayRequest
+
+
+class Exchanges:
+    def __init__(self, http_client: HTTPClient):
+        self.http_client = http_client
+
+    def list(self, **params: Unpack[ExchangesRequest]) -> ExchangesResponse:
+        """List stock exchanges."""
+        return ExchangesResponse.model_validate(self.http_client.get("/v2/exchanges", params=params))
+
+    def __call__(self, mic: str) -> "ExchangeInstance":
+        return ExchangeInstance(http_client=self.http_client, mic=mic)
+
+
+class ExchangeInstance:
+    def __init__(self, http_client: HTTPClient, mic: str):
+        self.http_client = http_client
+        self.mic = mic
+
+    def get(self) -> Exchange:
+        """Obtain stock exchange by MIC."""
+        res = self.http_client.get(f"/v2/exchanges/{self.mic}")
+        return Exchange.model_validate(res["data"])
+
+    @property
+    def eod(self) -> "ExchangeEOD":
+        return ExchangeEOD(http_client=self.http_client, mic=self.mic)
+
+    @property
+    def intraday(self) -> "ExchangeIntraday":
+        return ExchangeIntraday(http_client=self.http_client, mic=self.mic)
+
+    @property
+    def tickers(self) -> "ExchangeTickers":
+        return ExchangeTickers(http_client=self.http_client, mic=self.mic)
+
+
+class ExchangeEOD:
+    def __init__(self, http_client: HTTPClient, mic: str):
+        self.http_client = http_client
+        self.mic = mic
+
+    def list(self, **params: Unpack[EODRequest]) -> ExchangesMicEod:
+        """Obtain exchange end-of-day data."""
+        return ExchangesMicEod.model_validate(
+            self.http_client.get(f"/v2/exchanges/{self.mic}/eod", params=params)
+        )
+
+    def latest(self, **params: Unpack[EODLatestRequest]) -> ExchangesMicEod:
+        """Obtain exchange latest end-of-day data."""
+        return ExchangesMicEod.model_validate(
+            self.http_client.get(f"/v2/exchanges/{self.mic}/eod/latest", params=params)
+        )
+
+    def for_a_date(self, date: str, **params: Unpack[EODLatestRequest]) -> ExchangesMicEod:
+        """Obtain exchange end-of-day data for a date."""
+        return ExchangesMicEod.model_validate(
+            self.http_client.get(f"/v2/exchanges/{self.mic}/eod/{date}", params=params)
+        )
+
+
+class ExchangeIntraday:
+    def __init__(self, http_client: HTTPClient, mic: str):
+        self.http_client = http_client
+        self.mic = mic
+
+    def list(self, **params: Unpack[IntradayRequest]) -> ExchangesMicIntraday:
+        """Obtain exchange intraday data."""
+        return ExchangesMicIntraday.model_validate(
+            self.http_client.get(f"/v2/exchanges/{self.mic}/intraday", params=params)
+        )
+
+    def latest(self, **params: Unpack[IntradayRequest]) -> ExchangesMicIntradayLatest:
+        """Obtain exchange latest intraday data."""
+        return ExchangesMicIntradayLatest.model_validate(
+            self.http_client.get(f"/v2/exchanges/{self.mic}/intraday/latest", params=params)
+        )
+
+    def for_a_date(self, date: str, **params: Unpack[IntradayRequest]) -> ExchangesMicIntradayLatest:
+        """Obtain exchange intraday data for a date."""
+        return ExchangesMicIntradayLatest.model_validate(
+            self.http_client.get(f"/v2/exchanges/{self.mic}/intraday/{date}", params=params)
+        )
+
+
+class ExchangeTickers:
+    def __init__(self, http_client: HTTPClient, mic: str):
+        self.http_client = http_client
+        self.mic = mic
+
+    def list(self, **params: Unpack[ExchangeTickersRequest]) -> ExchangeMicTickersResponse:
+        """List tickers for an exchange."""
+        return ExchangeMicTickersResponse.model_validate(
+            self.http_client.get(f"/v2/exchanges/{self.mic}/tickers", params=params)
+        )

marketstack/namespaces/frames/__init__.py

@@ -0,0 +1 @@
+from .frames import Frames

marketstack/namespaces/frames/frames.py

@@ -0,0 +1,12 @@
+from marketstack.client.http import HTTPClient
+from typing import Unpack
+from marketstack.models.concept import FrameResponse, FramesRequest
+
+
+class Frames:
+    def __init__(self, http_client: HTTPClient):
+        self.http_client = http_client
+
+    def get_accounts_payable(self, unit: str, **params: Unpack[FramesRequest]) -> FrameResponse:
+        """Obtain Accounts Payable Frames."""
+        return FrameResponse.model_validate(self.http_client.get(f"/v2/frames/accounts_payable/{unit}", params=params))

marketstack/namespaces/indexinfo/__init__.py

@@ -0,0 +1 @@
+from .indexinfo import IndexInfo

marketstack/namespaces/indexinfo/indexinfo.py

@@ -0,0 +1,12 @@
+from marketstack.client.http import HTTPClient
+from typing import Unpack
+from marketstack.models.index import IndexInfoResponse, IndexInfoRequest
+
+
+class IndexInfo:
+    def __init__(self, http_client: HTTPClient):
+        self.http_client = http_client
+
+    def get(self, **params: Unpack[IndexInfoRequest]) -> IndexInfoResponse:
+        """Obtain market index information."""
+        return IndexInfoResponse.model_validate(self.http_client.get("/v2/indexinfo", params=params))

marketstack/namespaces/indexlist/__init__.py

@@ -0,0 +1 @@
+from .indexlist import IndexList

marketstack/namespaces/indexlist/indexlist.py

@@ -0,0 +1,12 @@
+from marketstack.client.http import HTTPClient
+from typing import Unpack
+from marketstack.models.index import IndexListResponse, IndexListRequest
+
+
+class IndexList:
+    def __init__(self, http_client: HTTPClient):
+        self.http_client = http_client
+
+    def list(self, **params: Unpack[IndexListRequest]) -> IndexListResponse:
+        """List market indices."""
+        return IndexListResponse.model_validate(self.http_client.get("/v2/indexlist", params=params))

marketstack/namespaces/intraday/__init__.py

@@ -0,0 +1 @@
+from .intraday import Intraday

marketstack/namespaces/intraday/intraday.py

@@ -0,0 +1,20 @@
+from marketstack.client.http import HTTPClient
+from typing import Unpack
+from marketstack.models.intraday import IntradayResponse, IntradayRequest
+
+
+class Intraday:
+    def __init__(self, http_client: HTTPClient):
+        self.http_client = http_client
+
+    def list(self, **params: Unpack[IntradayRequest]) -> IntradayResponse:
+        """Obtain intraday data."""
+        return IntradayResponse.model_validate(self.http_client.get("/v2/intraday", params=params))
+
+    def latest(self, **params: Unpack[IntradayRequest]) -> IntradayResponse:
+        """Obtain latest intraday data."""
+        return IntradayResponse.model_validate(self.http_client.get("/v2/intraday/latest", params=params))
+
+    def for_a_date(self, date: str, **params: Unpack[IntradayRequest]) -> IntradayResponse:
+        """Obtain intraday data for a specific date."""
+        return IntradayResponse.model_validate(self.http_client.get(f"/v2/intraday/{date}", params=params))

marketstack/namespaces/splits/__init__.py

@@ -0,0 +1 @@
+from .splits import Splits

marketstack/namespaces/splits/splits.py

@@ -0,0 +1,12 @@
+from marketstack.client.http import HTTPClient
+from typing import Unpack
+from marketstack.models.split import SplitsResponse, SplitsRequest
+
+
+class Splits:
+    def __init__(self, http_client: HTTPClient):
+        self.http_client = http_client
+
+    def list(self, **params: Unpack[SplitsRequest]) -> SplitsResponse:
+        """List stock splits."""
+        return SplitsResponse.model_validate(self.http_client.get("/v2/splits", params=params))

marketstack/namespaces/stockprice/__init__.py

@@ -0,0 +1 @@
+from .stockprice import StockPrice

marketstack/namespaces/stockprice/stockprice.py

@@ -0,0 +1,12 @@
+from marketstack.client.http import HTTPClient
+from typing import Unpack
+from marketstack.models.stockprice import StockPriceResponse, StockPriceRequest
+
+
+class StockPrice:
+    def __init__(self, http_client: HTTPClient):
+        self.http_client = http_client
+
+    def get(self, **params: Unpack[StockPriceRequest]) -> StockPriceResponse:
+        """Obtain real-time stock price."""
+        return StockPriceResponse.model_validate(self.http_client.get("/v2/stockprice", params=params))

marketstack/namespaces/submissions/__init__.py

@@ -0,0 +1 @@
+from .submissions import Submissions

marketstack/namespaces/submissions/submissions.py

@@ -0,0 +1,12 @@
+from marketstack.client.http import HTTPClient
+from typing import Unpack
+from marketstack.models.company import SubmissionsByCIKResponse, SubmissionsRequest
+
+
+class Submissions:
+    def __init__(self, http_client: HTTPClient):
+        self.http_client = http_client
+
+    def get(self, **params: Unpack[SubmissionsRequest]) -> SubmissionsByCIKResponse:
+        """Obtain SEC Submissions."""
+        return SubmissionsByCIKResponse.model_validate(self.http_client.get("/v2/submissions", params=params))

marketstack/namespaces/tickerinfo/__init__.py

@@ -0,0 +1 @@
+from .tickerinfo import TickerInfo

marketstack/namespaces/tickerinfo/tickerinfo.py

@@ -0,0 +1,12 @@
+from marketstack.client.http import HTTPClient
+from typing import Unpack
+from marketstack.models.ticker_info import TickerInfoResponse, TickerInfoRequest
+
+
+class TickerInfo:
+    def __init__(self, http_client: HTTPClient):
+        self.http_client = http_client
+
+    def get(self, **params: Unpack[TickerInfoRequest]) -> TickerInfoResponse:
+        """Obtain ticker information."""
+        return TickerInfoResponse.model_validate(self.http_client.get("/v2/tickerinfo", params=params))

marketstack/namespaces/tickers/__init__.py

@@ -0,0 +1 @@
+from .tickers import Tickers

marketstack/namespaces/tickers/tickers.py

@@ -0,0 +1,150 @@
+from marketstack.client.http import HTTPClient
+from marketstack.models.ticker import (
+    TickerResponse,
+    TickerSplitsRequest,
+    TickerSplitsResponse,
+    TickerEODRequest,
+    TickerEODResponse,
+    TickerEODLatestRequest,
+    TickerIntradayRequest,
+    TickerDividendsRequest,
+)
+from marketstack.models.ticker_info import (
+    TickerIntradayResponse,
+    TickerDividendsResponse,
+)
+from marketstack.models.intraday import IntradayBar, IntradayResponse
+from typing import Unpack
+from marketstack.models.eod import EODBar
+
+
+class Tickers:
+    def __init__(self, http_client: HTTPClient):
+        self.http_client = http_client
+
+    def __call__(self, symbol: str) -> "Ticker":
+        return Ticker(http_client=self.http_client, symbol=symbol)
+
+
+class Ticker:
+    def __init__(self, http_client: HTTPClient, symbol: str):
+        self.http_client = http_client
+        self.symbol = symbol
+
+    def get(self) -> TickerResponse:
+        """Using the API's Tickers endpoint you will be able to look up information about one or multiple stock ticker symbols as well as obtain end-of-day, real-time and intraday market data for single tickers."""
+        return TickerResponse.model_validate(self.http_client.get(f"/v2/tickers/{self.symbol}"))
+
+    @property
+    def eod(self) -> "TickerEOD":
+        return TickerEOD(http_client=self.http_client, symbol=self.symbol)
+
+    @property
+    def splits(self) -> "TickerSplits":
+        return TickerSplits(http_client=self.http_client, symbol=self.symbol)
+
+    @property
+    def intraday(self) -> "TickerIntraday":
+        return TickerIntraday(http_client=self.http_client, symbol=self.symbol)
+
+    @property
+    def dividends(self) -> "TickerDividends":
+        return TickerDividends(http_client=self.http_client, symbol=self.symbol)
+
+
+class TickerEOD:
+    def __init__(self, http_client: HTTPClient, symbol: str):
+        self.http_client = http_client
+        self.symbol = symbol
+
+    def list(
+        self,
+        **params: Unpack[TickerEODRequest],
+    ) -> TickerEODResponse:
+        """Obtain end-of-day data for a specific stock ticker by attaching /eod to your URL."""
+        return TickerEODResponse.model_validate(
+            self.http_client.get(f"/v2/tickers/{self.symbol}/eod", params=params)
+        )
+
+    def latest(
+        self,
+        **params: Unpack[TickerEODLatestRequest],
+    ) -> EODBar:
+        """Obtain eod data for the latest date by specifying stock ticker by attaching /eod/latest to your URL."""
+        return EODBar.model_validate(
+            self.http_client.get(f"/v2/tickers/{self.symbol}/eod/latest", params=params)
+        )
+
+    def for_a_date(
+        self,
+        date: str,
+        **params: Unpack[TickerEODRequest],
+    ) -> EODBar:
+        """Specify a date in YYYY-MM-DD format. You can also specify an exact time in ISO-8601 date format. For example, 2020-05-21T00:00:00+0000. Example, /eod/2020-01-01."""
+        return EODBar.model_validate(
+            self.http_client.get(f"/v2/tickers/{self.symbol}/eod/{date}", params=params)
+        )
+
+
+class TickerSplits:
+    def __init__(self, http_client: HTTPClient, symbol: str):
+        self.http_client = http_client
+        self.symbol = symbol
+
+    def list(
+        self,
+        **params: Unpack[TickerSplitsRequest],
+    ) -> TickerSplitsResponse:
+        """Obtain ticker splits factor for a specific stock ticker by attaching /splits to your URL."""
+        return TickerSplitsResponse.model_validate(
+            self.http_client.get(f"/v2/tickers/{self.symbol}/splits", params=params)
+        )
+
+
+class TickerIntraday:
+    def __init__(self, http_client: HTTPClient, symbol: str):
+        self.http_client = http_client
+        self.symbol = symbol
+
+    def list(
+        self,
+        **params: Unpack[TickerIntradayRequest],
+    ) -> TickerIntradayResponse:
+        """Obtain intraday data for a specific stock ticker by attaching /intraday to your URL."""
+        return TickerIntradayResponse.model_validate(
+            self.http_client.get(f"/v2/tickers/{self.symbol}/intraday", params=params)
+        )
+
+    def latest(
+        self,
+        **params: Unpack[TickerIntradayRequest],
+    ) -> IntradayBar:
+        """Obtain intraday data for the latest date by specifying stock ticker by attaching /intraday/latest to your URL."""
+        return IntradayBar.model_validate(
+            self.http_client.get(f"/v2/tickers/{self.symbol}/intraday/latest", params=params)
+        )
+
+    def for_a_date(
+        self,
+        date: str,
+        **params: Unpack[TickerIntradayRequest],
+    ) -> IntradayResponse:
+        """Specify a date in YYYY-MM-DD format or ISO-8601 date format."""
+        return IntradayResponse.model_validate(
+            self.http_client.get(f"/v2/tickers/{self.symbol}/intraday/{date}", params=params)
+        )
+
+
+class TickerDividends:
+    def __init__(self, http_client: HTTPClient, symbol: str):
+        self.http_client = http_client
+        self.symbol = symbol
+
+    def list(
+        self,
+        **params: Unpack[TickerDividendsRequest],
+    ) -> TickerDividendsResponse:
+        """Obtain dividends for a specific stock ticker."""
+        return TickerDividendsResponse.model_validate(
+            self.http_client.get(f"/v2/tickers/{self.symbol}/dividends", params=params)
+        )

marketstack/namespaces/tickerslist/__init__.py

@@ -0,0 +1 @@
+from .tickerslist import TickersList

marketstack/namespaces/tickerslist/tickerslist.py

@@ -0,0 +1,12 @@
+from marketstack.client.http import HTTPClient
+from typing import Unpack
+from marketstack.models.ticker_info import TickersListResponse, TickersListRequest
+
+
+class TickersList:
+    def __init__(self, http_client: HTTPClient):
+        self.http_client = http_client
+
+    def list(self, **params: Unpack[TickersListRequest]) -> TickersListResponse:
+        """List tickers."""
+        return TickersListResponse.model_validate(self.http_client.get("/v2/tickerslist", params=params))

marketstack/namespaces/timezones/__init__.py

@@ -0,0 +1 @@
+from .timezones import Timezones

marketstack/namespaces/timezones/timezones.py

@@ -0,0 +1,12 @@
+from marketstack.client.http import HTTPClient
+from typing import Unpack
+from marketstack.models.timezone import TimezonesResponse, TimezonesRequest
+
+
+class Timezones:
+    def __init__(self, http_client: HTTPClient):
+        self.http_client = http_client
+
+    def list(self, **params: Unpack[TimezonesRequest]) -> TimezonesResponse:
+        """List supported timezones."""
+        return TimezonesResponse.model_validate(self.http_client.get("/v2/timezones", params=params))

marketstack_python_client-1.0.0.dist-info/METADATA

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: marketstack-python-client
+Version: 1.0.0
+Summary: A Python client for the Marketstack API.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.13.4
+Dynamic: license-file
+
+# Marketstack Python Client
+
+A modern, fully-typed Python client for the [Marketstack API (v2)](https://marketstack.com/). Built on top of `httpx` and `pydantic`, this client offers high performance, strict type validation, and an elegant fluent API interface.
+
+---
+
+## Features
+
+- **Modern Python Support:** Optimized for Python `>= 3.10`.
+- **Fully Typed Requests & Responses:** Leverages Pydantic v2 and PEP 692 `Unpack` for complete autocomplete, editor hints, and runtime validation.
+- **Fluent & Hierarchical API:** Easily access nested endpoints (e.g., `client.tickers("AAPL").eod.list()`).
+- **Comprehensive Coverage:** Supports 25+ namespaces covering end-of-day (EOD) data, intraday, tickers, stock exchanges, stock splits, dividends, ETFs, indices, currencies, bonds, commodities, company fundamentals, and more.
+
+---
+
+## Installation
+
+Install the package via `pip`:
+
+```bash
+pip install marketstack-python-client
+```
+
+Or using `uv`:
+
+```bash
+uv add marketstack-python-client
+```
+
+---
+
+## Quick Start
+
+To use the client, you will need a Marketstack API key. Get one by registering at [marketstack.com](https://marketstack.com/).
+
+```python
+import os
+from marketstack import Marketstack
+
+# Initialize the client with your access key
+client = Marketstack(api_key=os.environ["MARKETSTACK_API_KEY"])
+
+# 1. Fetch generic End-of-Day (EOD) stock data
+eod_data = client.eod.list(symbols="AAPL,MSFT")
+for bar in eod_data.data:
+    print(f"{bar.symbol} closed at {bar.close} on {bar.date}")
+
+# 2. Access Ticker-specific data using the fluent API
+aapl_ticker = client.tickers("AAPL").get()
+print(f"Name: {aapl_ticker.name}, Stock Exchange: {aapl_ticker.stock_exchange.name}")
+
+# Fetch EOD prices specifically for AAPL
+aapl_eod = client.tickers("AAPL").eod.list(limit=10)
+for bar in aapl_eod.data:
+    print(f"AAPL Close: {bar.close}")
+
+# 3. Access Stock Exchange specific tickers and EOD data
+nasdaq_eod = client.exchanges("XNAS").eod.list(symbols="AAPL", limit=5)
+print(f"Fetched {len(nasdaq_eod.data)} records from NASDAQ")
+```
+
+---
+
+## Client Namespaces & API Coverage
+
+The `Marketstack` client provides dedicated namespaces mapping to the various endpoints of the Marketstack API.
+
+### 1. Tickers (Fluent API)
+Interact with a specific ticker symbol.
+```python
+ticker = client.tickers("AAPL")
+
+ticker.get()                      # Basic ticker information
+ticker.eod.list()                 # End-of-Day historical data
+ticker.eod.latest()               # Latest End-of-Day bar
+ticker.eod.for_a_date("2023-10-27") # End-of-Day bar for a specific date
+ticker.intraday.list()            # Intraday / Real-time data
+ticker.intraday.latest()          # Latest intraday data
+ticker.intraday.for_a_date("2023-10-27")
+ticker.splits.list()              # Split history
+ticker.dividends.list()           # Dividend history
+```
+
+### 2. Stock Exchanges (Fluent API)
+Interact with stock exchanges.
+```python
+exchange = client.exchanges("XNAS")
+
+exchange.get()                    # Basic exchange info
+exchange.tickers.list()           # All tickers listed on this exchange
+exchange.eod.list(symbols="AAPL") # EOD data for a ticker on this exchange
+exchange.intraday.list(symbols="AAPL") # Intraday data for a ticker on this exchange
+```
+
+### 3. End-of-Day (EOD) & Intraday Market Data
+Retrieve general EOD and Intraday datasets.
+```python
+# General EOD endpoints
+client.eod.list(symbols="AAPL", date_from="2023-01-01")
+client.eod.latest(symbols="AAPL")
+client.eod.for_a_date(date="2023-10-27", symbols="AAPL")
+
+# General Intraday endpoints
+client.intraday.list(symbols="AAPL")
+client.intraday.latest(symbols="AAPL")
+client.intraday.for_a_date(date="2023-10-27", symbols="AAPL")
+```
+
+### 4. Other Specialized Namespaces
+The client supports many other endpoints depending on your Marketstack subscription tier:
+
+- **Dividends & Splits:**
+  - `client.dividends.list(symbols="AAPL")`
+  - `client.splits.list(symbols="AAPL")`
+- **Currencies & Timezones:**
+  - `client.currencies.list()`
+  - `client.timezones.list()`
+- **Bonds & Index Info:**
+  - `client.bondlist.list(country="US")`
+  - `client.bond.get(country="US")`
+  - `client.indexlist.list()`
+  - `client.indexinfo.get(index="SPX")`
+- **ETFs:**
+  - `client.etflist.list(ticker="SPY")`
+  - `client.etfholdings.get(ticker="PRSVX")`
+- **Company Fundamentals (Requires Enterprise/Tier Plan):**
+  - `client.company_facts.get(cik_code="0000320193")`
+  - `client.companyname.get(cik_code="0000320193")`
+  - `client.companyratings.get(ticker="AAPL")`
+  - `client.concept.get_accounts_payable(cik_code="0000320193")`
+
+---
+
+## Development
+
+We use `uv` for dependency management and workspace workflows.
+
+### Prerequisites
+
+- Python 3.10 or higher
+- `uv` package manager
+
+### Setup
+
+Clone the repository and install the dependencies:
+
+```bash
+uv sync
+```
+
+### Running Tests
+
+This project uses `pytest` for unit and integration testing.
+
+```bash
+# Run all unit tests
+uv run pytest -v
+```
+
+To run the integration tests against the live Marketstack API, make sure to set the `MARKETSTACK_API_KEY` environment variable in your `.env` or current session. Note that some tests require higher-tier plans and are marked to be skipped if your API key lacks access.
+
+```bash
+export MARKETSTACK_API_KEY="your_api_key_here"
+uv run pytest tests/test_integration.py
+```
+
+---
+
+## License
+
+This project is licensed under the MIT License. See individual files or package settings for more details.