Metadata-Version: 2.4
Name: yt-search-python
Version: 2.1.1
Summary: Search YouTube contents without YouTube Data v3 API_KEY with Modern Sync & Async Python support.
Home-page: https://github.com/BillaSpace/yt-search-python
Author: Prakhar-Shukla
Author-email: srvopus@gmail.com
License: MIT
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.28.1
Provides-Extra: transcript
Requires-Dist: yt-dlp; python_version >= "3.10" and extra == "transcript"
Dynamic: author
Dynamic: author-email
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# yt-search-python v2.1.1 🚩



[![GitHub Stars](https://img.shields.io/github/stars/BillaSpace/youtube-search-python?style=for-the-badge&logo=github)](https://github.com/BillaSpace/youtube-search-python/stargazers)
[![GitHub Forks](https://img.shields.io/github/forks/BillaSpace/youtube-search-python?style=for-the-badge&logo=github)](https://github.com/BillaSpace/youtube-search-python/network)
[![Python Version](https://img.shields.io/badge/python-3.7+-blue.svg?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/downloads/)
[![License](https://img.shields.io/github/license/BillaSpace/youtube-search-python?style=for-the-badge)](https://github.com/BillaSpace/youtube-search-python/blob/main/LICENSE)

**Search and read YouTube data (videos, playlists, channels, comments, transcripts) without the YouTube Data API v3 — no API key, no quota limits.**

[Installation](#installation) • [Quick Start](#quick-start) • [Key Classes](#key-classes) • [Examples](#examples) • [Known Limitations](#known-limitations) • [Testing](#testing)

---

## What this library does

It talks to YouTube's own internal (`innertube`) endpoints — the same ones the youtube.com website itself calls — and parses the JSON back into clean Python structures. Both a synchronous API (`youtubesearchpython`) and an async API (`youtubesearchpython.future`) are provided, sharing the same underlying parsing logic so their results match.

Previous users of `youtube-search-python`: replace `youtubesearchpython.__future__` imports with `youtubesearchpython.future` — nothing else changes.

---

## Installation

```bash
pip3 install yt-search-python
```

Or from source:
```bash
pip install git+https://github.com/BillaSpace/yt-search-python.git
```

---

## Quick Start

**Search for videos**
```python
from youtubesearchpython import VideosSearch

search = VideosSearch('Hindutva', limit=10)
print(search.result())
```

**Get video info + streaming formats**
```python
from youtubesearchpython import Video

video = Video.get('https://www.youtube.com/watch?v=aqz-KE-bpKQ')
print(video['title'], video['viewCount'])
```

**Async**
```python
import asyncio
from youtubesearchpython.future import VideosSearch, Video

async def main():
    search = VideosSearch('Learn Python', limit=5)
    print(search.result())
    await search.next()          # next page
    print(search.result())

    video = await Video.get('aqz-KE-bpKQ')
    print(video['title'])

asyncio.run(main())
```

---

## Key Classes

**Search**
- `VideosSearch`, `ChannelsSearch`, `PlaylistsSearch`, `CustomSearch`, `ChannelSearch`

**Content**
- `Video` — info + streaming formats (`Video.get`, `Video.getInfo`, `Video.getFormats`)
- `Playlist` — one-shot `Playlist.get(...)`, or instantiate `Playlist(link)` for `.getNextVideos()` pagination
- `Channel` — `Channel.get(...)`, or instantiate + `.init()` / `.next()` for pagination
- `Comments` — `Comments.get(...)`, or instantiate + `.init()` / `.getNextComments()`
- `Transcript` — `Transcript.get(link, params=<languageCode>)` to select a specific caption track
- `Hashtag` — instantiate `Hashtag(tag, limit=...)` (fetches immediately) or `Hashtag.get(...)`
- `Suggestions` — autocomplete text suggestions. `Suggestions.get(...)` for one-shot use, `Suggestions.session(...)` (async: same) to reuse a client across many calls
- `Recommendations` — related/up-next videos for a video ID

**Utility**
- `StreamURLFetcher` — direct stream URLs (needs `yt-dlp` & `deno`installed in your system)
- `ResultMode` — `.dict` or `.json` output

Note: `Suggestions` (autocomplete text) and `Recommendations` (related videos) are deliberately separate classes — different endpoints, different data — not merged into one.

---

## Examples

**Advanced search with filters**
```python
from youtubesearchpython import CustomSearch, VideoSortOrder

search = CustomSearch('Python', VideoSortOrder.viewCount, limit=10)
print(search.result())
```

**Playlist videos (works with a URL or a bare ID)**
```python
from youtubesearchpython import Playlist

playlist = Playlist.get('PLRBp0Fe2GpgmsW46rJyudVFlY6IYjFBIK')
print(playlist['info']['title'], len(playlist['videos']))
```

**Comments**
```python
from youtubesearchpython import Comments

comments = Comments.get('https://www.youtube.com/watch?v=aqz-KE-bpKQ')
for c in comments['result'][:5]:
    print(c['author']['name'], ':', c['content'])
```

**Search suggestions**
```python
from youtubesearchpython import Suggestions

print(Suggestions.get('Arijit Singh', language='en', region='US'))
```

**Pagination**
```python
search = VideosSearch('Python', limit=10)
print(search.result())
search.next()
print(search.result())
```

**Language & region**
```python
search = VideosSearch('Music', limit=10, language='es', region='ES')
```

**Filters available**
- Upload date: `VideoUploadDateFilter.lastHour`, `.today`, `.thisWeek`, `.thisMonth`, `.thisYear`
- Duration: `VideoDurationFilter.short`, `.long`
- Sort order: `VideoSortOrder.relevance`, `.uploadDate`, `.viewCount`, `.rating`

---

## Known Limitations

Being upfront about what this library can't do, rather than silently under-delivering:

- **Mix / Radio playlists** (IDs starting with `RD…`) are auto-generated by YouTube through a different, session-based mechanism than regular playlists, and aren't returned by the standard browse endpoint this library uses. `Playlist.get()` will raise a clear `YouTubeParseError` identifying this case rather than crashing with an unrelated `TypeError` — but it won't fetch the mix's videos.
- **Recommendations** reflect what YouTube's own backend returns for an anonymous, session-less request to the `/next` endpoint — without real watch history or a signed-in session, YouTube itself mixes in generic suggestions alongside genuinely related videos. This is backend behavior, not something a scraper can fully correct.
- This library depends entirely on YouTube's internal response shapes, which change without notice. If something breaks, it's almost always a shape change on YouTube's end.

---

Covers all search classes, content retrieval, comments/recommendations/suggestions, `StreamURLFetcher`, transcripts — both sync and async. 

---

## Contributing

1. Fork the repository
2. Create a feature branch
3. Commit and push
4. Open a Pull Request

---

## License

MIT — see [LICENSE](LICENSE).

## Disclaimer

Not affiliated with YouTube or Google. Uses YouTube's publically available internal endpoints, which may change without notice. Use responsibly and in accordance with YouTube's Terms of Service.

## Credits

» Current maintainer: [Prakhar Shukla](https://github.com/BillaSpace) 

» Original author: [Hitesh Kumar Saini](https://github.com/alexmercerind)

<details>
<summary>Full acknowledgements</summary>

- Thanks to [CertifiedCoder](https://github.com/CertifiedCoder) for his work on the request layer[ v2.0.0.]
- 
- Built on top of the original `youtube-search-python` project and its contributors.

</details>

---

<div align="center">

• [Report a bug](https://github.com/BillaSpace/yt-search-python/issues) 
• [Request a feature](https://github.com/BillaSpace/yt-search-python/issues)

</div>
