Metadata-Version: 2.4
Name: omniscrape
Version: 0.4.0
Summary: Python SDK for the Omniscrape social media data API
Project-URL: Homepage, https://omniscrape.dev
Project-URL: Repository, https://github.com/leepokai/omniscrape
Project-URL: Documentation, https://omniscrape.dev
Author-email: Signalsurf <support@omniscrape.dev>
License-Expression: MIT
License-File: LICENSE
Keywords: api,omniscrape,scraping,social-media,threads,tiktok
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27
Requires-Dist: loguru<1,>=0.7
Requires-Dist: pydantic<3,>=2.0
Provides-Extra: dev
Requires-Dist: mypy>=1.13; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.22; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Description-Content-Type: text/markdown

# Omniscrape Python SDK

The official Python SDK for the [Omniscrape](https://omniscrape.dev) social media data API.

Supports **Threads, Facebook, X (Twitter), Instagram, Reddit, LinkedIn, TikTok, YouTube, Dcard, Google Maps, and 104**.

## Installation

```bash
pip install omniscrape
```

## Quick Start

```python
from omniscrape import Omniscrape

client = Omniscrape(api_key="sk_oms_...")

# Get a Threads post
post = client.threads.get_post("DQt-ox3kdE4")
print(post.data.text)
print(post.data.stats.likes)
```

## Platform Examples

### Threads

```python
# User profile
user = client.threads.get_user("zuck")
print(f"{user.data.username} — {user.data.follower_count} followers")

# Search posts
results = client.threads.search_posts("AI")
```

### X (Twitter)

```python
user = client.x.get_user("elonmusk")
tweet = client.x.get_post("1234567890")

# Auto-paginate all posts
for post in client.x.iter_user_posts("elonmusk"):
    print(post.text)
```

### Instagram

```python
user = client.instagram.get_user("instagram")
print(user.data.follower_count)
```

### TikTok

```python
video = client.tiktok.get_video("7123456789")
user = client.tiktok.get_user("khaby.lame")

# Browse trending
trending = client.tiktok.get_categories()
```

### Reddit

```python
sub = client.reddit.get_subreddit("python")
posts = client.reddit.get_subreddit_posts("python", sort="hot")
```

### LinkedIn

```python
company = client.linkedin.get_company("google")
jobs = client.linkedin.search_jobs(query="software engineer", location="Taiwan")

# Auto-paginate jobs
for job in client.linkedin.iter_search_jobs(query="data scientist"):
    print(job.title, job.location)
```

### YouTube

```python
video = client.youtube.get_video("dQw4w9WgXcQ")
channel = client.youtube.get_channel("@mkbhd")
results = client.youtube.search("machine learning", count=5)
transcript = client.youtube.get_video_transcription("dQw4w9WgXcQ", language="en")
```

### Dcard

```python
forum = client.dcard.get_forum("trending")
posts = client.dcard.get_forum_posts("trending", limit=10, popular=True)
results = client.dcard.search_posts("台大", limit=10)
```

### Google Maps

```python
results = client.gmaps.search("coffee shops in Tokyo", language="en")
place = client.gmaps.get_place("Blue Bottle Coffee Tokyo")
```

### Facebook

```python
page = client.facebook.get_user("NASA")
posts = client.facebook.get_user_posts("NASA")
```

### 104 Jobs

```python
jobs = client.job104.search_jobs(q="Python工程師")
company = client.job104.get_company("company_id")
```

## Async Support

```python
import asyncio
from omniscrape import AsyncOmniscrape

async def main():
    async with AsyncOmniscrape(api_key="sk_oms_...") as client:
        post = await client.threads.get_post("DQt-ox3kdE4")
        print(post.data.text)

asyncio.run(main())
```

## Rate Limit & Credit Info

Every response includes rate limit and credit usage:

```python
resp = client.threads.get_post("DQt-ox3kdE4")
print(resp.rate_limit.remaining)  # requests left
print(resp.credit.remaining)      # credits left
```

## Error Handling

```python
from omniscrape import Omniscrape, NotFoundError, RateLimitError

try:
    client.threads.get_post("invalid")
except NotFoundError:
    print("Post not found")
except RateLimitError as e:
    print(f"Rate limited, retry after {e.retry_after}s")
```

## Environment Variable

You can set your API key as an environment variable instead of passing it directly:

```bash
export OMNISCRAPE_API_KEY="sk_oms_..."
```

```python
client = Omniscrape()  # picks up from env
```

## Links

- [Website](https://omniscrape.dev)
- [GitHub](https://github.com/Signalsurf-ai/omniscrape-python)
