py-ftmarkets

Financial Times (markets.ft.com) data source for Python. Provides a high-level API and CLI to search for securities, fetch historical data, and validate prices.

Installation

uv add py-ftmarkets
# or
pip install py-ftmarkets

CLI Usage

The ftmarkets CLI is built on treaty and needs Python 3.14 and the cli extra. The library itself still supports Python 3.10 and later; on an older Python, or without the extra, ftmarkets exits 1 and says how to install it.

uv tool install --python 3.14 "py-ftmarkets[cli]"
# or, in a Python 3.14 environment
pip install "py-ftmarkets[cli]"

--format takes plain (the default on a terminal), json (the full response envelope with ok, data, error, warnings, and meta; the default when piped), jsonl, ndjson, and tsv. -v and -vv show info and debug logs on stderr. ftmarkets <command> --help lists the flags and --schema the input and output schemas.

Exit codes: 0 success, 2 invalid arguments (nothing ran), 5 security or history not found, 79 the price check failed (history --price).

Lookup a Security

Resolve an ISIN or Symbol to the Financial Times symbol format (e.g., AAPL:NSQ). Results keep FT's relevance order; --limit defaults to 1 and --limit 0 returns every match.

# Basic lookup by ISIN
ftmarkets lookup --isin DE000A0S9GB0

# Keep only matches that traded near a price on a date (--price needs --date)
ftmarkets lookup --isin DE000A0S9GB0 --price 117.81 --date 2025-12-12

# Lookup with filters (currency, country, asset class or FT security type, exchange)
ftmarkets lookup --isin DE000A0S9GB0 --currency EUR --country DE --asset-class ETF

# Every match as a JSON envelope; the securities are in .data
ftmarkets lookup --isin DE000A0S9GB0 --limit 0 --format json

# Every match as a table
ftmarkets lookup --isin DE000A0S9GB0 --limit 0 --format tsv

Fetch History and Validate

Fetch historical data for a resolved security and optionally validate a trade price on a specific date. The result holds the resolved security, its history (candles in ascending date order), and validated (true when the price matched, null without --price).

# Fetch 1 month of history for an ISIN
ftmarkets history --isin DE000A0S9GB0

# Fetch 1 year of history and validate a price; exits 79 (PRICE_MISMATCH) when it does not match
ftmarkets history --isin DE000A0S9GB0 --period 1y --price 120.50 --date 2025-01-15 --format json

Library Usage

py-ftmarkets implements the DataSource interface from pydantic-market-data.

from ftmarkets.api import FTDataSource
from pydantic_market_data.models import SecurityCriteria

source = FTDataSource()

# Resolve a security
criteria = SecurityCriteria(isin="DE000A0S9GB0")
security = source.resolve(criteria)
print(f"Symbol: {security.symbol}")

# Fetch history
history = source.history(security.symbol, period="1mo")
df = history.to_pandas()
print(df.tail())

# Validate price
is_valid = source.validate(security.symbol, target_date="2025-01-15", target_price=120.50)
print(f"Price valid: {is_valid}")

Features

• Robust Resolution: Searches by ISIN, Symbol, or Description.
• Smart Mapping: Prioritizes results based on preferred exchanges and currency.
• Price Validation: Verifies if a security traded within a range or near a specific price on a given date.
• Pandas Integration: Historical data is easily convertible to Pandas DataFrames.
• Modern Python: Built with Pydantic v2 and async-ready architecture (though currently synchronous).