Metadata-Version: 2.4
Name: youtube-scraper-api
Version: 0.0.1
Summary: Python client for the ScrapingBee YouTube API: search, video metadata, and subtitles as structured JSON
Author: wordstotech
License: MIT
Project-URL: Homepage, https://www.scrapingbee.com/features/youtube/
Keywords: youtube scraper,youtube scraping api,youtube video scraper,youtube scraper api,youtube data scraper,scrapingbee
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Dynamic: license-file

# youtube-scraper-api

Pull YouTube search results, video metadata, and subtitles as parsed JSON. A thin Python wrapper over the ScrapingBee **YouTube scraper API** that handles authentication, headless rendering, and proxies behind a single Bearer-token request.

```bash
pip install youtube-scraper-api
```

Covers the queries people reach for: `youtube scraper`, `youtube scraping api`, `youtube video scraper`, `youtube scraper api`, and `youtube data scraper`. Requires Python 3.8+ and `requests`. Built on the [ScrapingBee YouTube API](https://www.scrapingbee.com/features/youtube/).

## 30-second example

```python
from youtube_scraper_api import YouTubeScraper

yt = YouTubeScraper(api_key="YOUR_API_KEY")

# 1. find videos
hits = yt.search("python tutorial", type="video", sort_by="view_count")
video_id = hits["results"][0]["videoId"]

# 2. enrich one of them
details = yt.metadata(video_id)

# 3. grab its captions
captions = yt.subtitles(video_id, language="en")
```

Get a key first: ScrapingBee gives 1,000 credits with no card at [scrapingbee.com](https://www.scrapingbee.com/).

## The client

```python
YouTubeScraper(api_key: str, timeout: int = 60)
```

Authentication is a Bearer token, set for you on every call. The client drops any `None` arguments before sending the request.

## Methods

### `search(search, type=None, upload_date=None, duration=None, sort_by=None, hd=False, fourk=False, subtitles=False, creative_commons=False, live=False, tag=None, extra=None)`

Query YouTube for videos, channels, or playlists. `search` is the only required argument.

| Argument | API parameter | Accepted values |
|---|---|---|
| `search` | `search` | any query string |
| `type` | `type` | `video`, `channel`, `playlist`, `movie` |
| `upload_date` | `upload_date` | `today`, `last_hour`, `this_week`, `this_month`, `this_year` |
| `duration` | `duration` | `<4`, `4-20`, `>20` |
| `sort_by` | `sort_by` | `rating`, `relevance`, `view_count`, `upload_date` |
| `hd`, `fourk`, `subtitles`, `creative_commons`, `live` | `hd`, `4k`, `subtitles`, `creative_commons`, `live` | booleans |
| `tag` | `tag` | custom id echoed back in the response |
| `extra` | (any) | dict for other documented flags: `360`, `3d`, `hdr`, `vr180`, `location`, `purchased` |

### `metadata(video_id)`

Return full details for one video: duration, view count, like count, upload date, description, channel info, thumbnails, and available formats. This is the building block of a **YouTube data scraper** that enriches a list of ids.

### `subtitles(video_id, language=None, subtitle_origin=None)`

Return timestamped caption segments. `subtitle_origin` selects auto-generated or uploader-provided captions when both exist.

## Returned fields

`search()` returns a `results` list. Each item carries the fields YouTube rendered, commonly:

```
videoId, title, longBylineText, thumbnail, lengthText,
shortViewCountText, publishedTimeText
```

Not every field appears on every result, so use `.get()` rather than direct indexing.

## Credits

ScrapingBee bills successful calls. `search()` is 5 credits per call. The cost for `metadata()` and `subtitles()` is shown in the dashboard request builder. Plan tiers: [scrapingbee.com/pricing](https://www.scrapingbee.com/pricing/).

## Notes

- A **YouTube video scraper** built this way needs no headless browser or proxy management on your side; ScrapingBee does both.
- Scrape public content only. ScrapingBee's terms prohibit scraping behind a login.

## Links

- [ScrapingBee YouTube API](https://www.scrapingbee.com/features/youtube/)
- [YouTube API documentation](https://www.scrapingbee.com/documentation/youtube/)
- [ScrapingBee pricing](https://www.scrapingbee.com/pricing/)

## License

MIT

## Disclaimer

Unofficial Python client built on the ScrapingBee YouTube API. Not affiliated with ScrapingBee or YouTube. Comply with YouTube's terms of service and applicable law.
