Marketstack Python Client

A modern, fully-typed Python client for the Marketstack API (v2). 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:

pip install marketstack-python-client

Or using uv:

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.

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.

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.

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.

# 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:

uv sync

Running Tests

This project uses pytest for unit and integration testing.

# 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.

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.