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.
