Metadata-Version: 2.4
Name: ugcscraper-helper
Version: 0.1.0
Summary: A tiny Python client for the UGC Scraper Reddit API — scrape posts and comments into clean JSON without Reddit API keys or proxies.
License: MIT
Project-URL: Homepage, https://ugcscraper.com
Project-URL: Documentation, https://ugcscraper.com/reddit-scraper-api
Project-URL: Repository, https://github.com/builtbyish/ugc-scraper-python-helper
Keywords: reddit,reddit-scraper,reddit-comment-scraper,web-scraping,praw-alternative
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25
Dynamic: license-file

# ugc-scraper-python-helper

A lightweight **Reddit scraper Python** client for the [UGC Scraper](https://ugcscraper.com) API.
Scrape any Reddit post and its full comment thread into clean, consistent JSON, with **no Reddit API
keys**, no OAuth app, and no proxies to manage.

It is a ~90-line wrapper over the [UGC Scraper Platform](https://ugcscraper.com) REST API. One key,
one endpoint, the same JSON schema every time, so you can build your parser once.

## Why

Most ways to scrape Reddit break on the same things: the official API needs OAuth and caps listings
at ~1,000 items, and DIY scrapers get IP-banned without a rotating proxy pool. UGC Scraper routes
every request through a resilient fallback chain with automatic failover and bills only for
successful posts. This helper is the smallest possible way to call it from Python.

## Install

```bash
pip install requests   # the only dependency
# then drop ugcscraper.py into your project, or:
pip install .
```

## Usage

```python
from ugcscraper import UGCScraper

client = UGCScraper("rps_live_your_key")          # get a free key at ugcscraper.com/dashboard

# Scrape a post + its full comment thread into one JSON schema
post = client.scrape("https://www.reddit.com/r/python/comments/abc123/")
print(post["title"], post["score"], len(post["comments"]))

# Read your durable scrape history (free, no quota)
print(client.history(limit=20))
print(client.latest("abc123"))          # re-fetch a stored post without spending quota
print(client.usage())                   # tier, quota, remaining

# Export the same data as CSV
open("comments.csv", "w").write(client.latest_csv("abc123", rows="comments"))
open("history.csv", "w").write(client.history_csv())
```

Errors surface as `UGCScraperError` with the API's `status_code` and `detail` (401 invalid key,
429 rate limit, 502 all methods failed).

## What you get back

A flattened, LLM-friendly schema: `title`, `author`, `score`, `num_comments`, `permalink`,
`image_url`, `thumbnail_url`, `body`, and `comments[]` (each with `author`, `body`, `score`, `id`,
`parent_id`, `link_id`, `permalink`, `created_at`). Same shape no matter which engine fetched it.

## Links

- Platform: <https://ugcscraper.com>
- API reference (endpoints, auth, examples): <https://ugcscraper.com/reddit-scraper-api>
- Get an API key (free tier: 1,000 successful posts/mo): <https://ugcscraper.com/dashboard>
- MCP server for Claude Desktop: `ugc-scraper-reddit-mcp`

## License

MIT
