Metadata-Version: 2.4
Name: simple-yt-api
Version: 3.0.1
Summary: A simple and easy-to-use unofficial YouTube API Wrapper.
Author-email: Ahmet Burhan Kayalı <ahmetburhan1703@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/SoAp9035/simple-yt-api
Project-URL: Bug Tracker, https://github.com/SoAp9035/simple-yt-api/issues
Keywords: simple,unofficial,youtube,api,wrapper
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Text Processing :: Markup :: HTML
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests==2.32.5
Requires-Dist: beautifulsoup4==4.13.5
Requires-Dist: youtube-transcript-api==1.2.2
Dynamic: license-file

# Simple YouTube API

An unofficial lightweight Python wrapper for extracting video metadata and transcripts from YouTube videos.

## Features

- 🎥 Extract video metadata (title, thumbnail, short description)
- 📝 Get video transcripts in various languages
- ⚡ Simple and easy to use interface
- 🔒 No API key required

## Installation

[uv](https://docs.astral.sh/uv/) is recommended for managing and installing packages in isolated environments.

```bash
uv add simple-yt-api
```

You can also install it using pip:

```bash
pip install simple-yt-api
```

## Quick Start

```python
from simple_yt_api import YouTubeAPI

# Initialize
yt = YouTubeAPI()

url = "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

# Get video metadata
metadata = yt.data(url=url)
print(metadata["title"])

# Get video transcript
transcript = yt.get_transcript(
    url=url,
    language_code="tr",
    as_dict=True
) # Get Turkish transcript. Defaults to "en".
print(transcript)

# Or get both metadata and transcript at once
data, transcript = yt.get_video_data_and_transcript(
    url=url,
    language_code="es",
    as_dict=False  # Return transcript as plain text
)
```

## API Reference

### YouTubeAPI Class

#### `YouTubeAPI()`
Initializes the API client.

#### `data(url: str) -> dict`
Returns video metadata dictionary containing:
- `video_id`: YouTube video ID
- `title`: Video title
- `img_url`: Thumbnail URL
- `short_description`: Video description

#### `get_transcript(url: str, language_code: str = "en", as_dict: bool = True) -> list[dict] | str`
Get video transcript in the specified languages.
- `url (str)`: The URL of the YouTube video.
- `language_code (str, optional)`: The language code for the desired transcript. Defaults to "en".
- `as_dict (bool, optional)`: If `True`, returns the transcript as a list of dictionaries; otherwise, returns the transcript as a string. Defaults to `True`.

#### `get_video_data_and_transcript(url: str, language_code: str = "en", as_dict: bool = True) -> tuple`
Returns both video metadata and transcript. If there is an error, that spot in the tuple will have `None` instead of a value.
- `url (str)`: The URL of the YouTube video.
- `language_code (str, optional)`: The language code for the desired transcript. Defaults to "en".
- `as_dict (bool, optional)`: If `True`, returns the transcript as a list of dictionaries; otherwise, returns the transcript as a string. Defaults to `True`.

## Error Handling

The library includes custom exceptions:
- `NoVideoFound`: When a video is not accessible or doesn't exist.
- `NoMetadataFound`: When no metadata is found for the video.
- `TranscriptsDisabled`: When transcripts are not available for the video.
- `NoTranscriptFound`: When no transcript is available for the video.

## Warning

Sending too many requests in a short period might lead to your IP address being temporarily blocked by YouTube. Use responsibly.

## License

This project is licensed under the [MIT](https://choosealicense.com/licenses/mit/) License.

## Links

- [GitHub Repository](https://github.com/SoAp9035/simple-yt-api)
- [PyPI Package](https://pypi.org/project/simple-yt-api/)
- [Buy Me a Coffee](https://buymeacoffee.com/soap9035/)
- [Visit My Website](https://ahmetburhan.com/)
