# Sorsa Twitter (X) API Tools & Playground

A comprehensive suite of tools for Twitter (X) data analysis, extraction, and conversion, powered by the Sorsa API v3.

## Primary Tools

- **ID Converter** (`/id-converter`): Seamlessly convert permanent numeric Twitter User IDs to current screen names (handles) and vice-versa.
- **Shadowban Check** (`/shadowban-check`): Dual-verification tool to check for Search Ban (hidden tweets) and Search Suggestion Ban (hidden profile).
- **Media Downloader** (`/media-downloader`): Extract direct, high-quality MP4/JPG links from any Twitter post containing videos, GIFs, or images.
- **User Comparison** (`/compare-users`): Side-by-side analytical comparison of two profiles, including Engagement Rate (ER), posting frequency, and account metrics.
- **API Playground** (`/`): Interactive visual builder for testing Sorsa API v3 endpoints including user info, tweet search, scoring, and analytics.

## API Specification (Internal Proxy)

The following internal endpoints are available for programmatic access (requires `x-sorsa-client: sorsa-web-client-v1` header and subject to rate limits):

- `GET /api/id-to-username?id={id}`: Returns `{ "handle": "string" }`
- `GET /api/username-to-id?username={username}`: Returns `{ "id": "string" }`
- `GET /api/shadowban-check?username={username}`: Returns status of search visibility.
- `POST /api/media-downloader`: Requires `{ "tweet_link": "string" }`. Returns direct media URLs.
- `POST /api/compare-users`: Requires `{ "user1": "string", "user2": "string" }`. Returns comparative stats.

## Technical Details

- **Base URL**: `https://playground.sorsa.io`
- **Rate Limit**: 10 requests per minute per IP for tool-specific endpoints.
- **Data Source**: Sorsa API v3 (`https://api.sorsa.io/v3`)