# dropthe

Python SDK for [DropThe.org](https://dropthe.org) — access 1.9 million entities across movies, people, companies, crypto, games, universities, and more, connected by 2.18 million knowledge graph links.

## Install

```bash
pip install dropthe
```

For pandas DataFrame support:

```bash
pip install dropthe[pandas]
```

## Quick Start

```python
import dropthe

# Search any entity
results = dropthe.search("Inception")
print(results[0]["name"])  # Inception

# Get a specific entity by slug
btc = dropthe.entity("bitcoin")
print(btc["type"])  # cryptocurrencies

# Top movies by popularity
top_movies = dropthe.movies(limit=10)

# Top crypto by market cap
top_crypto = dropthe.crypto(limit=10)

# Companies, games, universities
top_companies = dropthe.companies(limit=10)
top_games = dropthe.games(limit=10)
unis = dropthe.universities(limit=10)
```

## Using the Client

For more control, use `DropTheClient` directly:

```python
from dropthe import DropTheClient

with DropTheClient() as client:
    # Search with type filter
    movies = client.search("dark knight", type="movies")

    # Get entity count
    total = client.count()
    print(f"Total entities: {total:,}")  # Total entities: 1,933,637

    # Get knowledge graph links
    entity = client.search("Christopher Nolan", type="people")[0]
    links = client.links(entity["id"])

    # Geographic data (countries, cities)
    countries = client.geo("country")
```

## Pandas DataFrames

```python
import dropthe

# Get top movies as DataFrame
df = dropthe.movies(limit=100, as_dataframe=True)
print(df[["name", "slug"]].head())
```

## Entity Types

| Type | Count | Examples |
|------|-------|---------|
| people | 1,550,000+ | Actors, directors, musicians, athletes |
| movies | 208,000+ | Films from 1888 to 2026 |
| series | 44,000+ | TV shows, anime, K-drama |
| games | 44,000+ | Video games across all platforms |
| universities | 27,000+ | Global institutions |
| companies | 19,000+ | Public and private companies |
| cryptocurrencies | 16,000+ | Active and dead tokens |
| apps | 7,000+ | Software applications |
| books | 5,700+ | Literature and non-fiction |

## Data Sources

All data comes from authoritative APIs (TMDb, CoinGecko, Wikidata, IGDB) and is enriched by DropThe's entity resolution pipeline. See the [methodology](https://dropthe.org/good/methodology/) for details.

## Links

- [DropThe.org](https://dropthe.org) -- Main site
- [Data Hub](https://dropthe.org/data/) -- Statistics and insights
- [Knowledge Graph](https://dropthe.org/data/statistics/) -- Entity connections
- [Open Datasets](https://github.com/arnaudleroy-studio/dropthe-datasets-public) -- CSV datasets on GitHub

## License

MIT
