Metadata-Version: 2.4
Name: tickerinside
Version: 0.1.1
Summary: Python client for the free TickerInside API: the full holdings of US ETFs, which funds hold a stock, fund overlap and portfolio look-through.
Project-URL: Homepage, https://tickerinside.com
Project-URL: Documentation, https://tickerinside.com/api/
Author-email: TickerInside <contact@tickerinside.com>
License-Expression: MIT
License-File: LICENSE
Keywords: api,etf,etf holdings,etf overlap,finance,look-through,n-port,portfolio,sec
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Typing :: Typed
Requires-Python: >=3.9
Provides-Extra: pandas
Requires-Dist: pandas>=1.3; extra == 'pandas'
Description-Content-Type: text/markdown

# tickerinside

A Python client for the free TickerInside API, which serves the full holdings of US ETFs, the funds that hold each stock, and the overlap and look-through computed from them.

## Install

```
pip install tickerinside
```

The package uses only the Python standard library and runs on Python 3.9 or later. There is no API key and no account to create. pandas is optional: install it (or `pip install "tickerinside[pandas]"`) and every result also offers a `.df` DataFrame.

## Examples

```python
import tickerinside as ti
```

The holdings of VOO as a DataFrame, heaviest first:

```python
voo = ti.holdings("VOO", names=True)
voo.holdings_as_of        # '2026-08-31', the date of the issuer's file
voo.df.head(3)
#   ticker        name  weight_pct
# 0   NVDA      Nvidia      8.0927
# 1   AAPL  Apple Inc.      7.0432
# 2   MSFT   Microsoft      5.7033
```

Which ETFs hold NVDA, and at what weight:

```python
nvda = ti.holders("NVDA")
nvda.data["counts"]       # {'issuer': 177, 'sec_nport': None}
nvda.df[["fund", "weight_pct", "holdings_as_of"]].head(3)
#    fund  weight_pct holdings_as_of
# 0  GXPT     19.9100     2026-09-24
# 1   VGT     17.7869     2026-08-31
# 2  VUSG     16.9500     2026-09-25
```

Funds covered from their issuers' own files and funds covered from SEC Form N-PORT filings, which are months older, are kept apart in `nvda.data["issuer"]` and `nvda.data["sec_nport"]` (None while the API lists only the first kind). `.df` lists the issuer rows first and the SEC rows after them, without merging the two by weight.

How much VOO and QQQ overlap:

```python
c = ti.compare("VOO", "QQQ")
c.data["overlap"]["by_weight"]    # 53.9, the smaller weight of each shared company, summed
c.data["overlap"]["share_of_b"]   # 93.7, the part of QQQ held in companies VOO also holds
c.data["correlation_3y"]          # 0.95, from three years of weekly returns
```

What a small portfolio holds underneath, in percent and in money:

```python
lt = ti.look_through({"VOO": 6000, "QQQ": 3000, "SCHD": 1000})
lt.df.head(2)
#   ticker  weight_pct   value  via_VOO  via_QQQ  via_SCHD
# 0   NVDA       7.312  731.24   4.8556   2.4568       0.0
# 1   AAPL       6.449  644.88   4.2259   2.2229       0.0
```

Citing a figure, with the line every result carries:

```python
print(c.cite)
# TickerInside, VOO vs QQQ, holdings files of 2026-08-31 and 2026-09-24, https://tickerinside.com/compare/voo-vs-qqq/, CC BY 4.0
c.page_url                # the page where a reader can check it
```

The figures above are from the files of 25 September 2026 and change as issuers publish new ones.

## What each call returns

The functions are `funds()`, `fund(ticker)`, `holdings(ticker)`, `holders(stock_ticker)`, `security(ticker)`, `compare(a, b)`, `overlap_matrix(tickers)`, `look_through(positions)` and `census()`. Each returns a result with these attributes:

- `.data`: the answer as plain dicts and lists.
- `.df`: the same answer as a pandas DataFrame, when pandas is installed.
- `.as_of`: the date of the price data, and `.holdings_as_of`: the date of the holdings file, or a dict of dates by fund when the answer uses several funds.
- `.source`: where the holdings come from, `issuer` for the issuer's own file or `sec_nport` for a fund covered from its latest SEC Form N-PORT filing, which is months older. Like `.holdings_as_of`, it is a dict by fund when the answer uses several funds.
- `.cite`: a citation line naming the source, its date, a link and the licence.
- `.url`: the API file the answer was read from, and `.page_url`: the page on tickerinside.com where it can be checked.

Overlap, correlation and look-through are computed on your machine from the fund files, with the same arithmetic as the TickerInside website and MCP server, so the figures agree with theirs. A ticker that is not covered raises `tickerinside.NotCovered` with the API's own message, and a fund given to `holders()` or a stock given to `fund()` gets a message naming the call that fits it. A network failure raises `tickerinside.APIError` with the URL that failed, and so does a 404 that is not the API's own answer, which usually means a wrong base URL. Each file is kept in memory for an hour, so asking twice costs one request. `ti.Client(base_url=..., timeout=..., cache_ttl=...)` gives a session with other settings, and the `TICKERINSIDE_API` environment variable, when it is set, replaces the default base URL `https://tickerinside.com/api/v1` (the TickerInside MCP server reads the same variable). Requests identify themselves with the User-Agent `tickerinside-python/<version>`, and nothing else is sent anywhere.

## Licence and attribution

The code of this package is released under the MIT licence. The data it reads is published by TickerInside under the Creative Commons Attribution 4.0 licence (CC BY 4.0): you may use it, commercially as well, provided you credit TickerInside and link to https://tickerinside.com. The `.cite` line on every result does both. The figures are measurements of what funds hold and how they have behaved, not investment advice.

The API reference, with every field and endpoint, is at https://tickerinside.com/api/.
