TikTok Video Details Scraper (Apify-ready)

Instantly scrape TikTok videos: views, likes, comments, plays, and author info—all in one JSON.

---

Highlights

• Scrapes TikTok video details from public URLs.
• Normalizes engagement metrics and video metadata.
• Apify-ready: works with Actor.get_input(), push_data(), and key-value store (ALL_RESULTS).
• Local mode supported using input.json.
• Handles hidden JSON in TikTok pages for reliable extraction.
• Outputs consolidated JSON for downstream analytics or automation.

---

Quick Start

Requirements

• Python 3.8+
• requests and beautifulsoup4
• apify SDK if running as an Apify Actor (optional for local runs)

requests
beautifulsoup4
apify          # optional: required only if running inside Apify Actor

Local Usage

1. Create input.json:

{
  "startUrls": [
    "https://www.tiktok.com/@username/video/1234567890123456789"
  ]
}

2. Run the script:

$python main.py

3. Scraped results are printed to stdout and saved to ./output/all_tiktok_videos.json.

---

Running on Apify

1. Upload main.py and requirements.txt to a new Python Actor.
2. Provide actor input:

{
  "startUrls": [{"url": "https://www.tiktok.com/@username/video/1234567890123456789"}]
}

3. Start the Actor. Results are pushed to the dataset and stored under ALL_RESULTS.

---

Output Schema (per video)

{
  "id": "1234567890123456789",
  "url": "https://www.tiktok.com/@username/video/1234567890123456789",
  "title": "Video title",
  "description": "Video description",
  "duration_seconds": 34,
  "duration": "34s",
  "videoUrl": "https://...mp4",
  "cover": "https://...jpg",
  "playCount": "12.3k",
  "shareCount": "1.2k",
  "likeCount": "34.5k",
  "commentCount": "456",
  "author": {
    "uniqueId": "username",
    "nickname": "User Name",
    "avatarThumb": "https://...jpg",
    "verified": true
  },
  "fetched_at": "2025-09-14T00:00:00Z"
}

---

Configuration Options

Option	Type	Description
startUrls	string | list	TikTok video URLs (string, list of strings, or list of { "url": "..." } objects)
OUTPUT_DIR	string	Local folder for JSON output (defaults to ./output)

---

Why Use This Scraper?

• Consolidated data: all video metadata and engagement metrics in one JSON.
• Apify-ready: minimal setup for Actor deployment and automation.
• Local mode: run directly without Apify if needed.
• Robust parsing: captures hidden JSON for reliable extraction of stats, video URLs, and author info.

---

Troubleshooting & Tips

• No data found? Ensure URL is a TikTok video page.
• Private/unavailable videos cannot be scraped.
• Rate limits: use Apify proxy or rotate IPs.
• Counts may vary due to TikTok caching.

---

Deployment Checklist

• Add LICENSE (MIT recommended).
• Include example output JSON in ./examples.
• Tag repo with tiktok, video, apify, scraper.
• Include input.json example.

---

Contributing & Support

PRs and issues welcome. Need additional fields or CSV output? Open an issue or submit a PR.

---

License

MIT — include attribution and keep the LICENSE file.

---

Contact

For integrations, pipelines, or custom scraping support, open an issue or contact the maintainer via the repo profile.