# SocialCrawl

> Unified social media data API. One API key, one response envelope, many platforms. Credits never expire; cache hits and failed calls cost nothing.

Auth: send your key in the `x-api-key` header. Get one free (100 credits, no card) at http://datatrend.nl/dash/signup
Every endpoint is a GET. Every response uses the same envelope:
{ success, platform, endpoint, data, credits_used, credits_remaining, request_id, cached }

## Machine-readable

- [OpenAPI spec](http://datatrend.nl/v1/openapi.json): every endpoint, params and credit cost
- [Discovery](http://datatrend.nl/v1/discover): live platform catalog
- [Agent skill](http://datatrend.nl/agent-onboarding/SKILL.md): drop-in instructions for coding agents

## Endpoints

### hackernews — Front page, search, items and user profiles from Hacker News.

- `GET /v1/hackernews/top` — no params (1 credit)
- `GET /v1/hackernews/search` — params: query (1 credit)
- `GET /v1/hackernews/item` — params: id (1 credit)
- `GET /v1/hackernews/user` — params: handle (1 credit)
- `GET /v1/hackernews/story` — params: id (1 credit)
- `GET /v1/hackernews/story/comments` — params: id (1 credit)
- `GET /v1/hackernews/profile` — params: handle (1 credit)

### github — Users, repositories and repo listings — stars, forks and issues as engagement.

- `GET /v1/github/user` — params: handle (1 credit)
- `GET /v1/github/repo` — params: repo (1 credit)
- `GET /v1/github/repos` — params: handle (1 credit)
- `GET /v1/github/profile` — params: handle (1 credit)
- `GET /v1/github/profile/repos` — params: handle, sort, per_page, page (1 credit)
- `GET /v1/github/repo/readme` — params: url (1 credit)
- `GET /v1/github/repo/releases` — params: url, per_page, page (1 credit)
- `GET /v1/github/repo/issues` — params: url, state, labels, sort, per_page, page (1 credit)
- `GET /v1/github/issue` — params: url (1 credit)
- `GET /v1/github/issue/comments` — params: url, per_page, page (1 credit)
- `GET /v1/github/search` — params: query, sort, order, per_page, page (1 credit)

### appstore — App Store listings and search, with ratings and review counts.

- `GET /v1/appstore/app` — params: id (1 credit)
- `GET /v1/appstore/search` — params: query (1 credit)
- `GET /v1/appstore/app-search` — params: query, country, depth (1 credit)
- `GET /v1/appstore/app-info` — params: app_id, country (1 credit)
- `GET /v1/appstore/app-reviews` — params: app_id, country, sort_by (1 credit)
- `GET /v1/appstore/app-list` — params: app_collection, country, depth (1 credit)

### reddit — Subreddit listings, search, individual posts and user profiles.

- `GET /v1/reddit/subreddit` — params: name, sort (1 credit)
- `GET /v1/reddit/search` — params: query (1 credit)
- `GET /v1/reddit/post` — params: url (1 credit)
- `GET /v1/reddit/user` — params: handle (1 credit)
- `GET /v1/reddit/subreddit/details` — params: subreddit, url (1 credit)
- `GET /v1/reddit/post/comments` — params: url, cursor (1 credit)
- `GET /v1/reddit/subreddit/search` — params: subreddit, query, sort, timeframe, cursor (1 credit)

### bluesky — Profiles, author feeds and post search across the AT Protocol network.

- `GET /v1/bluesky/profile` — params: handle (1 credit)
- `GET /v1/bluesky/feed` — params: handle (1 credit)
- `GET /v1/bluesky/search` — params: query (1 credit)
- `GET /v1/bluesky/user/posts` — params: handle, user_id (1 credit)
- `GET /v1/bluesky/post` — params: url (1 credit)

### polymarket — Live prediction markets: prices per outcome, volume and liquidity.

- `GET /v1/polymarket/markets` — no params (1 credit)
- `GET /v1/polymarket/market` — params: slug (1 credit)
- `GET /v1/polymarket/search` — params: query (1 credit)

### googleplay — Google Play listings with ratings and install signals.

- `GET /v1/googleplay/app` — params: id, lang (1 credit)
- `GET /v1/googleplay/app-search` — params: query, country, language (1 credit)
- `GET /v1/googleplay/app-info` — params: app_id, language (1 credit)

### youtube — Video metadata and full transcripts with timestamps — no API key, no quota.

- `GET /v1/youtube/video` — params: url (1 credit)
- `GET /v1/youtube/transcript` — params: url, lang (5 credits)
- `GET /v1/youtube/search` — params: query, region (1 credit)
- `GET /v1/youtube/channel` — params: handle, channelId, url (1 credit)
- `GET /v1/youtube/channel/videos` — params: handle, channelId (1 credit)
- `GET /v1/youtube/video/transcript` — params: url, language (1 credit)

### tiktok — Unified access to tiktok data.

- `GET /v1/tiktok/user` — no params (1 credit)
- `GET /v1/tiktok/videos` — no params (1 credit)
- `GET /v1/tiktok/video` — params: video_id (1 credit)

### instagram — Unified access to instagram data.

- `GET /v1/instagram/account` — no params (1 credit)
- `GET /v1/instagram/media` — no params (1 credit)
- `GET /v1/instagram/discover` — params: username (1 credit)

### twitter — Unified access to twitter data.

- `GET /v1/twitter/profile` — params: handle (1 credit)
- `GET /v1/twitter/user/tweets` — params: handle (2 credits)
- `GET /v1/twitter/tweet` — params: url (1 credit)
- `GET /v1/twitter/search/recent` — params: query (2 credits)

### linkedin — Unified access to linkedin data.

- `GET /v1/linkedin/company` — params: url (1 credit)
- `GET /v1/linkedin/company/posts` — params: url (2 credits)
- `GET /v1/linkedin/post/comments` — params: url (1 credit)

### facebook — Unified access to facebook data.

- `GET /v1/facebook/profile` — params: url (1 credit)
- `GET /v1/facebook/profile/posts` — params: url (2 credits)
- `GET /v1/facebook/post` — params: url (1 credit)
- `GET /v1/facebook/post/comments` — params: url (1 credit)

### pinterest — Unified access to pinterest data.

- `GET /v1/pinterest/account` — no params (1 credit)
- `GET /v1/pinterest/boards` — no params (1 credit)
- `GET /v1/pinterest/pin` — params: url (1 credit)

### amazon — Unified access to amazon data.

- `GET /v1/amazon/shop` — params: url (5 credits)
- `GET /v1/amazon/product-search` — params: query, country, depth (5 credits)
- `GET /v1/amazon/product` — params: asin, country (5 credits)
- `GET /v1/amazon/reviews` — params: asin, country (5 credits)
- `GET /v1/amazon/sellers` — params: asin, country (5 credits)

### google — Unified access to google data.

- `GET /v1/google/search` — params: query, region, date_posted, page (5 credits)
- `GET /v1/google/ad` — params: url (5 credits)
- `GET /v1/google/adlibrary/advertisers/search` — params: query, region (5 credits)
- `GET /v1/google/company/ads` — params: domain, advertiser_id, topic, region, start_date, end_date, platform, format, get_ad_details, cursor (5 credits)
- `GET /v1/google/business/info` — params: keyword, cid, place_id, location_name, language_name (5 credits)
- `GET /v1/google/business/extended-reviews` — params: keyword, cid, place_id, location_name, language_name, depth (5 credits)
- `GET /v1/google/business/updates` — params: keyword, cid, location_name, language_name (5 credits)
- `GET /v1/google/business/questions` — params: keyword, cid, place_id, location_name, language_name, depth (5 credits)
- `GET /v1/google/hotels/search` — params: keyword, location_name, language_name, check_in, check_out (5 credits)
- `GET /v1/google/hotels/info` — params: hotel_identifier, location_name, language_name (5 credits)

### google_shopping — Unified access to google_shopping data.

- `GET /v1/google_shopping/product-search` — params: query, country, language, depth, price_min, price_max, sort_by (5 credits)
- `GET /v1/google_shopping/product` — params: product_id, gid, data_docid, country, language (5 credits)
- `GET /v1/google_shopping/reviews` — params: gid, product_id, data_docid, depth, country, language (5 credits)
- `GET /v1/google_shopping/sellers` — params: product_id, gid, data_docid, country, language (5 credits)

### perplexity — Unified access to perplexity data.

- `GET /v1/perplexity/research` — params: query (5 credits)

### tiktokshop — Unified access to tiktokshop data.

- `GET /v1/tiktokshop/product` — params: url, region (5 credits)
- `GET /v1/tiktokshop/product/reviews` — params: url, product_id, region (5 credits)
- `GET /v1/tiktokshop/products` — params: url, sort_by, region (5 credits)
- `GET /v1/tiktokshop/search` — params: query, page, region (5 credits)
- `GET /v1/tiktokshop/user/showcase` — params: handle, region, cursor (5 credits)

### prism — Composites: ask once, get a finished verdict. Fans out across platforms in parallel, reports its own coverage, and refunds the slice it could not gather.

- `GET /v1/prism/share-of-voice` — params: brand, competitors (10 credits)
- `GET /v1/prism/brand-mentions` — params: brand (10 credits)
- `GET /v1/prism/review-integrity` — params: appstore_id, googleplay_id (10 credits)
- `GET /v1/prism/viral-analysis` — params: topic (10 credits)
- `GET /v1/prism/sentiment-report` — params: brand (10 credits)
- `GET /v1/prism/crisis-radar` — params: brand (10 credits)

### marketprice — Unified access to marketprice data.

- `GET /v1/marketprice/lookup` — params: ean, country (6 credits)

## Notes

- `GET /v1/lookup?url=...` auto-detects the platform from any supported URL.
- Slow endpoints return 202 with a job_id; poll `GET /v1/jobs/{id}`.
- Send `Idempotency-Key` to make retries safe: a replay within 24h costs 0 credits.
- `GET /v1/credits/balance` reports your balance and costs nothing.