Metadata-Version: 2.4
Name: lse-data
Version: 3.0
Summary: Python client for London Strategic Edge market data: live streaming, LSE Data 3.0 history as CSV and Parquet with resumable checked downloads, macro and reference data, options chains and flow
Project-URL: Homepage, https://londonstrategicedge.com
Project-URL: Documentation, https://github.com/londonstrategicedge/lse-data/blob/main/docs/api.md
Project-URL: Repository, https://github.com/londonstrategicedge/lse-data
Project-URL: Issues, https://github.com/londonstrategicedge/lse-data/issues
Author-email: London Strategic Edge <support@londonstrategicedge.com>
License-Expression: MIT
License-File: LICENSE
Keywords: crypto,csv,forex,futures,level 2,level 3,market data,options,parquet,realtime,stocks,trading,websocket
Classifier: Development Status :: 5 - Production/Stable
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: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Requires-Dist: websockets>=11.0
Provides-Extra: frames
Requires-Dist: pandas>=1.5; extra == 'frames'
Requires-Dist: pyarrow>=14; extra == 'frames'
Description-Content-Type: text/markdown

# lse-data

The Python client for LSE Data 3.0. One key streams live prices and downloads history.

[![PyPI](https://img.shields.io/pypi/v/lse-data)](https://pypi.org/project/lse-data/)
[![Python](https://img.shields.io/pypi/pyversions/lse-data)](https://pypi.org/project/lse-data/)
[![Licence](https://img.shields.io/pypi/l/lse-data)](https://github.com/londonstrategicedge/lse-data/blob/main/LICENSE)
[![Downloads](https://img.shields.io/pypi/dm/lse-data)](https://pypi.org/project/lse-data/)

## LSE Data 3.0

LSE Data 3.0 is the new version of our market data archive and API, with data integrity as its first priority.

- Level 3 order data: Nasdaq TotalView, CME Globex
- Level 2 book: Nasdaq TotalView
- 24,000 additional pairs
- Over 76,000 instruments across 11 markets
- 67 million US options contracts
- CSV and Parquet exports
- Free plan: 50 GB a month
- Coming soon: London Stock Exchange, Toronto Stock Exchange, Eurex

```bash
pip install lse-data
```

```python
from lse import LSE

client = LSE(api_key="your_key")
for tick in client.stream(["BTC/USD", "AAPL"]):
    print(tick.symbol, tick.price)

path = client.export("us_stocks", "AAPL", "5m", "2026-10-08", "2026-10-14", format="csv")
```

Markets: US, UK and Canadian stocks, forex, crypto, futures, indices, commodities, US options, CME Globex and Nasdaq TotalView, plus macro series, bond yields and 18 reference collections. [docs/api.md](https://github.com/londonstrategicedge/lse-data/blob/main/docs/api.md) lists every call.

One key for streaming and downloads. `client.usage()` shows the plan and its limits.

## Download history

Rows for a quick look, files for everything else.

```python
from lse import LSE

client = LSE(api_key="your_key")

# OHLCV candles as rows. timeframe: 1s, 5s, 15s, 30s, 1m, 3m, 5m, 15m, 30m, 1h, 4h, 1d, 1w, 1mo
candles  = client.candles("AAPL", "1h", start="2026-10-01", end="2026-10-14")
latest   = client.candles("BTCUSDT", "1d", limit=30, order="desc")

# The last ten rows of anything, and what an export would weigh, before you ask for it
peek     = client.preview("us_stocks", "AAPL", "5m")
size     = client.estimate("us_stocks", "AAPL", "1m", "2016-01-04", "2026-10-21", format="parquet")

# Macro series and yields: (date, value) rows, any series in one call
cpi      = client.series("US.core_inflation_rate", start="2020-01-01")
us10y    = client.series("US10Y")

# Reference collections, as rows
events   = client.economic_calendar(region="US", start="2026-10-01")
insiders = client.insider_trades("WRB", type="P-Purchase")
divs     = client.dividends("AAPL")
splits   = client.splits("NVDA")
cot      = client.cot("GC")
reports  = client.financial_reports("AAPL", report_type="income", period="FY")
profile  = client.company_profiles("NVDA")
```

Each call returns a list of dicts. Errors raise `LSEError`:

```python
from lse import LSEError

try:
    client.export("cme", "ESZ6", "tick", "2026-10-13", "2026-10-13", data="trades")
except LSEError as e:
    print(e.status, e.code, e.message)       # 403 plan-required This feed requires a subscription
    print(e.required_plan)                   # {"market": "cme", "tier": "lite", "name": "CME Group Lite", ...}
```

Rows are held in memory, so keep them to days or weeks. Years of candles, ticks and order books are files.

## Files: CSV and Parquet

`export()` saves a selection as a file and returns its path. Large exports are prepared on the server; downloads resume if the connection drops and are verified when they finish. The free plan includes 50 GB a month.

```python
path = client.export("us_stocks", "AAPL", "1m", "2016-01-04", "2026-10-21", format="parquet")
path = client.export("us_stocks", "AAPL", "tick", "2026-10-21", "2026-10-21", format="csv")        # the trade slice
path = client.export("nasdaq", "NVDA", "tick", "2026-10-14", "2026-10-14", data="book")             # the Level 2 book
path = client.export("cme", "ESZ6", "tick", "2026-10-13", "2026-10-13", data="orders")              # Level 3 orders
path = client.macro_export("observation", "US.core_inflation_rate", "1957-02-01", "2026-07-01", format="csv")
path = client.reference_export("company_profiles", "AAPL", format="csv")

df = client.history("AAPL", timeframe="1d", start="2020-01-01", end="2026-10-01")   # a DataFrame with the frames extra
```

`pip install 'lse-data[frames]'` adds DataFrames to `history()`, `dataset()` and `load(path)`.

CME Globex and Nasdaq TotalView are paid feeds. Their rows need the feed's plan, and a free key gets an error naming the plan. Tick counts, dates, table sizes and estimates are open to every key.

## Options

The whole US options tape, every contract, with implied volatility and the Greeks computed twice a day.

```python
chain  = client.options("apple", type="call", max_dte=30)
prints = client.options_flow("NVDA", min_premium=100_000)
sweep  = client.options_flow(min_premium=250_000, limit=200)
bars   = client.option_candles("AAPL", strike=100, expiry="2026-11-20", type="call")
names  = client.options_underlyings()
```

`options()` returns the chain, one row per contract with the last trade, volume, premium, implied volatility and Greeks. `options_flow()` returns prints with their premium and venue; leave out the underlying to scan every name. Its window is today by default, up to seven days with `start` and `end`. `option_candles()` returns candles for one contract. `subscribe_options(["AAPL"])` streams every AAPL contract live as `OptionTick` objects, which add `underlying`, `right`, `strike`, `expiry`, `dte`, `premium` and `notional` to a tick. With `from lse import tape`, `client.on("tick", tape())` prints them as a readable table.

## Find instruments

```python
client.markets()                         # every market, with what your key may open
client.catalog("stocks")                 # one dict per symbol: {"symbol": "AAPL", "name": "Apple Inc. - Common Stock", "ticks": 1627759459, ...}
client.pairs("us_stocks", q="apple")     # a market's instruments, searched
client.pairs("cme", underlying="SP500", expiry="2026-12-18")   # the contracts of one underlying
client.factors("uk_stocks", "ULVR")      # an instrument's splits and, for a stock, its dividends
client.macro_catalogue("observation", country="US", q="inflation")
client.reference_catalogue()             # the eighteen reference collections
```

Symbols are spelt as the catalogue lists them, in any case: `AAPL`, `EUR_USD`, `BTCUSDT`, `ESZ6`, `AAPL  261120C00100000`. An option contract works with or without the spaces, so `AAPL261120C00100000` is the same contract. Pair names work too, so `EUR/USD` and `BTC/USD` resolve. A symbol in several markets, such as AAPL, resolves to US stocks unless you pass `market=`.

## Stream live data

```python
from lse import LSE

client = LSE(api_key="your_key")
for tick in client.stream(["BTC/USD", "ETH/USD", "AAPL"]):
    print(tick.symbol, tick.price)
```

Use callbacks instead of a loop:

```python
client = LSE(api_key="your_key")
client.on("tick", lambda t: print(t.symbol, t.price))
client.connect(["BTC/USD"])
```

Events are `tick`, `connected`, `authenticated`, `disconnected`, `error`, `replay_started` and `replay_complete`.

Change subscriptions while connected:

```python
client.subscribe(["SOL/USD"])
client.unsubscribe(["BTC/USD"])
client.subscribe_options(["AAPL"])   # every AAPL contract at once
```

### Replay then live

Pass `start` to replay up to 24 hours of history before the live ticks, on the same connection.

```python
from datetime import datetime, timedelta, timezone

start = (datetime.now(timezone.utc) - timedelta(hours=1)).strftime("%Y-%m-%dT%H:%M:%S")   # UTC
for tick in client.stream(["BTC/USD"], start=start):
    print("replay" if tick.replay else "live", tick.symbol, tick.price)
```

### Async

```python
import asyncio
from lse import LSE

async def main():
    client = LSE(api_key="your_key")
    async for tick in client.stream_async(["BTC/USD"]):
        print(tick)

asyncio.run(main())
```

## The key

Pass it directly, or set it in the environment:

```python
client = LSE(api_key="your_key")

import os
os.environ["LSE_API_KEY"] = "your_key"
client = LSE()
```

The key never goes in a URL: downloads send it in the `X-API-Key` header, the stream in its first message. `LSE` also works as a context manager:

```python
with LSE() as client:
    for tick in client.stream(["BTC/USD"]):
        ...
```

A tick has `symbol`, `price`, `bid`, `ask`, `volume`, `timestamp` (ISO 8601), `name` and `replay`; `tick.datetime` is the parsed timestamp.

## Settings

Every setting of `LSE()` is optional:

| Setting | Default | What it does |
|---|---|---|
| `timeout` | `60` | seconds to wait for each HTTP call |
| `retries` | `3` | retries of a call that got no answer, or a 429, 500, 502, 503 or 504 |
| `poll_seconds` | `0.5` | how often a prepared export is polled |
| `wait_for_limit` | `True` | past your plan's calls a minute, wait the server's `Retry-After` once (at most two minutes) and try again; `False` raises at once |
| `data_url` | `https://download.londonstrategicedge.com` | the LSE Data 3.0 server |
| `url` | `wss://data-ws.londonstrategicedge.com` | the live WebSocket |

```python
client = LSE(api_key="your_key", timeout=120, wait_for_limit=False)
```

## Command line

```bash
lse auth lse_live_xxxxxxxxxxxx
lse stream BTC/USD AAPL
lse datasets
lse browse
```

## Upgrading from 0.x

Scripts written for 0.14 keep working: the method names and row shapes are the same, except `get()`. What changed:

- `candles()` holds rows in memory and takes a date window. It still returns at most `limit` bars (5,000 by default), from `start` onwards or the most recent. To page, pass the last bar's `timestamp` as the next `start`; that bar comes back as the first row. For years of bars, use `history()` or `export()`.
- Symbols follow the catalogue. The 0.x spellings still resolve: `EUR/USD` to `EUR_USD`, `BTC/USD` to `BTCUSDT` (crypto is quoted in Tether).
- `series()` takes catalogue codes (`US10Y`, `US.core_inflation_rate`). `cpi_yoy` and `fdtr` still work, as `US.inflation_rate` and `US.interest_rate`. A name matching several series raises `LSEError` with code `series-ambiguous` and lists them.
- `get()` read the retired tables. It now raises `LSEError` (410, `removed`) naming the methods to use.

[CHANGELOG.md](https://github.com/londonstrategicedge/lse-data/blob/main/CHANGELOG.md) lists every change and [docs/api.md](https://github.com/londonstrategicedge/lse-data/blob/main/docs/api.md) every call.

## Licence

This client is MIT licensed. See [LICENSE](https://github.com/londonstrategicedge/lse-data/blob/main/LICENSE).

That licence extends to the library alone and confers no rights in the data
obtained through it. Data retrieved with an LSE key may be used for your own
research, trading and model training, including for commercial purposes. It may
not be redistributed, resold, or otherwise made available to third parties,
whether in bulk or by way of any competing feed, download service or interface
sourced from LSE. Full terms: https://londonstrategicedge.com/terms
