Youtube Scraper Api

An Apify Actor that searches YouTube and extracts structured JSON for search result pages: videos, channels, playlists, Shorts shelves, ads, discovery rails, and search refinement keywords.

---

What does this Actor do?

This Actor executes YouTube searches and extracts comprehensive, flat data directly into the default Apify Dataset and Key-Value store. Usefull for cvs & excell extraction. Always column are always present to facilitate cvs & excell extraction.

• Videos: Video title, canonical watch URL, video ID, channel details (name, link, verified status, avatar thumbnail), published date, view counts (parsed integer and original string), duration length, description snippet, feature badges (4K, LIVE, CC, etc.), and thumbnails.
• Channels: Channel display name, link, handle (@handle), verified badge, subscriber count, description snippet, and avatar thumbnail.
• Playlists: Playlist title, link, channel information, video count, preview video links, and cover thumbnail.
• Sponsored Ads: Sponsored ad title, click-through URL, advertiser landing website, advertiser channel info (name and thumbnail), ad description text, static thumbnail, and position on page.
• Shorts: YouTube Short title, canonical link (https://www.youtube.com/shorts/...), video ID, view counts (parsed integer and localized text string), and shelf position on page.

---

Key Features

• Up to 30 Videos in One Request: Set num (1–30) and the Actor pages internally until it collects the requested number of videos.
• Result Type Filters: Filter exclusively for videos, channels, or playlists via the sp parameter.
• Flexible Sorting: Sort results by relevance (default), rating, upload date (newest first), or view count.
• Duration & Feature Filters: Narrow results by duration (<4 min, 4–20 min, >20 min) or features (4K, HD, LIVE, closed captions).
• Upload Date Filters: Target videos uploaded in the last hour, today, this week, this month, or this year.
• Localization: Configure UI language (hl) to localize age and view-count strings, and country code (gl) to influence ranking and local shelves.
• Device Emulation: Switch between desktop and mobile search layouts.
• Exact JSON Output: Delivers clean, structured JSON directly into your Apify Dataset and Key-Value Store.

---

Input Parameters

The Actor accepts the following input parameters:

Required

Parameter	Type	Description
search_query	string	Search terms to look up on YouTube (e.g. best laptop 2025, macbook pro m3). (Alias: q)

Optional

Parameter	Type	Default	Description
hl	string	"en"	Interface language code (en, de, fr, ja, tr, es, it, …). Controls localized text such as published_date, length, and views. Choose from the dropdown list.
gl	string	"us"	Two-letter country code (us, gb, de, fr, it, jp, …). Influences search ranking and shelf availability. Choose from the dropdown list.
device	string	"desktop"	Device layout emulation: desktop or mobile.
sp	string	""	YouTube filter / sort option (e.g. sort_by_view_count, type_channels, feature_4k). Choose a predefined filter from the dropdown. Cannot be combined with num.
num	integer	—	Number of video results to return from a single request (1–30). When set, internal pagination retrieves up to num videos. Cannot be combined with sp.

---

Filter & Sort Options (sp)

The sp parameter controls sorting, filtering by result type, duration, features, and upload date using clean, human-readable option keys that are automatically mapped internally:

1. Sort Order

sp Option	Description
(empty / omitted)	Relevance (Default)
sort_by_rating	Sort by rating
sort_by_upload_date	Sort by upload date (newest first)
sort_by_view_count	Sort by view count

2. Result Type

sp Option	Description	Output Populated
type_videos	Videos only	video_results
type_channels	Channels only	channel_results
type_playlists	Playlists only	playlist_results

3. Duration

sp Option	Description
duration_under_4_min	Under 4 minutes (Short)
duration_4_to_20_min	4–20 minutes (Medium)
duration_over_20_min	Over 20 minutes (Long)

4. Features

sp Option	Description
feature_4k	4K resolution
feature_hd	HD resolution
feature_live	Live streams currently active
feature_subtitles	Subtitles / Closed Captions (CC)

5. Upload Date

sp Option	Description
upload_last_hour	Uploaded in the last hour
upload_today	Uploaded today
upload_this_week	Uploaded this week
upload_this_month	Uploaded this month
upload_this_year	Uploaded this year

[!TIP] Raw YouTube continuation tokens or filter tokens passed directly to sp are also accepted and preserved.

---

Result Count (num)

Setting num allows you to retrieve up to 30 videos in a single execution. The service pages internally until it collects num videos, deduplicates by video_id, and numbers position_on_page starting from 1.

[!NOTE]

• num and sp are mutually exclusive. Provide either num or sp, not both.
• When num is used, the response contains only video_results and discovery rails (shorts_results, channel_results, and playlist_results are omitted).
• Recommendation shelves do not count toward num.

---

Example Inputs

1. Basic Search

{
  "search_query": "best laptop 2025"
}

2. Retrieve 25 Videos in a Single Run

{
  "search_query": "best laptop 2025",
  "num": 25
}

3. German Locale

{
  "search_query": "beste laptop 2025",
  "hl": "de",
  "gl": "de"
}

4. Channels Only

{
  "search_query": "tech reviewer",
  "sp": "type_channels"
}

5. Playlists Only

{
  "search_query": "python tutorial for beginners",
  "sp": "type_playlists"
}

6. 4K Videos Only

{
  "search_query": "nature documentary 4k",
  "sp": "feature_4k"
}

7. Long-Form Videos (> 20 Minutes)

{
  "search_query": "podcast interview",
  "sp": "duration_over_20_min"
}

8. Sort by View Count

{
  "search_query": "best laptop 2025",
  "sp": "sort_by_view_count"
}

9. Mobile Layout

{
  "search_query": "workout routines",
  "device": "mobile"
}

---

Output Structure

The Actor returns a flattened list of JSON objects directly pushed to the default Apify Dataset and Key-Value Store (OUTPUT). Each object represents an individual result item (video_results, channel_results, playlist_results, ads_results, or shorts_results).

Metadata wrappers (search_parameters, search_information, pagination) are excluded.

[!IMPORTANT] Schema Consistency: All 43 output parameters listed below will always be present in every single item of the returned dataset. If a parameter is not applicable to an item or not available, it will be empty (""). This ensures 100% predictable columns for tabular exports (CSV, Excel, databases).

All 43 Standardized Output Fields

Every returned object always contains these exact 43 keys:

Field	Type	Description
video_results.position_on_page	integer / string	1-based position of the video on the search results page
video_results.title	string	Video title
video_results.link	string	Canonical watch URL
video_results.video_id	string	YouTube video ID
video_results.channel.name	string	Channel display name
video_results.channel.link	string	Channel URL
video_results.channel.thumbnail	string	Channel avatar thumbnail URL
video_results.published_date	string	Relative published age localized to hl (e.g. "6 mesi fa", "4 months ago")
video_results.views	integer / string	View count parsed to integer
video_results.length	string	Video duration (e.g. "21:02", "12:38")
video_results.description	string	Video description snippet
video_results.extensions.0	string	Primary feature badge (e.g. "4K", "LIVE", "Sottotitoli")
video_results.thumbnail.static	string	Static cover thumbnail URL
video_results.thumbnail.rich	string	Animated preview thumbnail URL
channel_results.position_on_page	integer / string	1-based position of the channel on the search page
channel_results.title	string	Channel display name
channel_results.link	string	Channel URL
channel_results.handle	string	Channel @handle slug
channel_results.subscribers	integer / string	Subscriber count parsed to integer
channel_results.description	string	Channel description snippet
channel_results.thumbnail	string	Channel avatar thumbnail URL
playlist_results.position_on_page	integer / string	1-based position of the playlist on the search page
playlist_results.title	string	Playlist title
playlist_results.link	string	Playlist URL
playlist_results.channel.name	string	Uploader channel display name
playlist_results.channel.link	string	Uploader channel URL
playlist_results.videos.0.link	string	Link to the first preview video in the playlist
playlist_results.video_count	integer / string	Total video count on the playlist badge
playlist_results.thumbnail	string	Playlist cover thumbnail URL
ads_results.position_on_page	integer / string	1-based position of the sponsored ad on the search page
ads_results.title	string	Sponsored ad title
ads_results.link	string	Sponsored ad click-through URL
ads_results.website	string	Advertiser landing website URL
ads_results.channel.name	string	Advertiser name or domain
ads_results.channel.thumbnail	string	Advertiser icon / thumbnail URL
ads_results.description	string	Sponsored ad description text
ads_results.thumbnail.static	string	Static ad thumbnail image URL
shorts_results.position_on_page	integer / string	1-based position of the Shorts shelf on the search page
shorts_results.shorts.title	string	Short video title
shorts_results.shorts.link	string	Short watch URL (https://www.youtube.com/shorts/...)
shorts_results.shorts.views_original	string	Localized view count text (e.g. "1.2M views")
shorts_results.shorts.views	integer / string	Short view count parsed to integer
shorts_results.shorts.video_id	string	Short video ID

---

Example Output Records

1. Channel Result Example

When a channel is retrieved, channel fields are populated and other fields remain empty strings (""):

{
  "video_results.position_on_page": "",
  "video_results.title": "",
  "video_results.link": "",
  "video_results.video_id": "",
  "video_results.channel.name": "",
  "video_results.channel.link": "",
  "video_results.channel.thumbnail": "",
  "video_results.published_date": "",
  "video_results.views": "",
  "video_results.length": "",
  "video_results.description": "",
  "video_results.extensions.0": "",
  "video_results.thumbnail.static": "",
  "video_results.thumbnail.rich": "",
  "channel_results.position_on_page": 25,
  "channel_results.title": "Top 5 Tech   ",
  "channel_results.link": "https://www.youtube.com/@Top5Tech_",
  "channel_results.handle": "@Top5Tech_",
  "channel_results.subscribers": 523,
  "channel_results.description": "Benvenuti nel nostro canale YouTube dedicato alle recensioni di prodotti! Esplora il mondo delle ultime novità, dai gadget ...",
  "channel_results.thumbnail": "https://yt3.ggpht.com/QMgqMPtfAEYmD4sSDHtw82CFK-HZ-U82q-CXVa7nPajohhJF0TAbeTn2uwm6UQnCtueXBZT-5iI=s88-c-k-c0x00ffffff-no-rj-mo",
  "playlist_results.position_on_page": "",
  "playlist_results.title": "",
  "playlist_results.link": "",
  "playlist_results.channel.name": "",
  "playlist_results.channel.link": "",
  "playlist_results.videos.0.link": "",
  "playlist_results.video_count": "",
  "playlist_results.thumbnail": "",
  "ads_results.position_on_page": "",
  "ads_results.title": "",
  "ads_results.link": "",
  "ads_results.website": "",
  "ads_results.channel.name": "",
  "ads_results.channel.thumbnail": "",
  "ads_results.description": "",
  "ads_results.thumbnail.static": "",
  "shorts_results.position_on_page": "",
  "shorts_results.shorts.title": "",
  "shorts_results.shorts.link": "",
  "shorts_results.shorts.views_original": "",
  "shorts_results.shorts.views": "",
  "shorts_results.shorts.video_id": ""
}

2. Video Result Example

When a video is retrieved, video fields are populated and other fields remain empty strings (""):

{
  "video_results.position_on_page": 2,
  "video_results.title": "MIGLIORI NOTEBOOK di SETTEMBRE 2026 #TopBook",
  "video_results.link": "https://www.youtube.com/watch?v=eANiioMW39M",
  "video_results.video_id": "eANiioMW39M",
  "video_results.channel.name": "TuttoTech",
  "video_results.channel.link": "https://www.youtube.com/@TuttoTech",
  "video_results.channel.thumbnail": "https://yt3.ggpht.com/6IvsXMFmButt6XXcZUOu_3Uehk7AzEoze3oc984Re6nIGmFrS1CQqW_UiRGUyv4Tvf5tSnAYGw=s68-c-k-c0x00ffffff-no-rj",
  "video_results.published_date": "1 mese fa",
  "video_results.views": 28026,
  "video_results.length": "16:02",
  "video_results.description": "Questa non è una lista di tutti i portatili del 2026 ma una selezione accurata dei migliori notebook per rapporto qualità-prezzo.",
  "video_results.extensions.0": "4K",
  "video_results.thumbnail.static": "https://i.ytimg.com/vi/eANiioMW39M/hq720.jpg",
  "video_results.thumbnail.rich": "https://i.ytimg.com/an_webp/eANiioMW39M/mqdefault_6s.webp",
  "channel_results.position_on_page": "",
  "channel_results.title": "",
  "channel_results.link": "",
  "channel_results.handle": "",
  "channel_results.subscribers": "",
  "channel_results.description": "",
  "channel_results.thumbnail": "",
  "playlist_results.position_on_page": "",
  "playlist_results.title": "",
  "playlist_results.link": "",
  "playlist_results.channel.name": "",
  "playlist_results.channel.link": "",
  "playlist_results.videos.0.link": "",
  "playlist_results.video_count": "",
  "playlist_results.thumbnail": "",
  "ads_results.position_on_page": "",
  "ads_results.title": "",
  "ads_results.link": "",
  "ads_results.website": "",
  "ads_results.channel.name": "",
  "ads_results.channel.thumbnail": "",
  "ads_results.description": "",
  "ads_results.thumbnail.static": "",
  "shorts_results.position_on_page": "",
  "shorts_results.shorts.title": "",
  "shorts_results.shorts.link": "",
  "shorts_results.shorts.views_original": "",
  "shorts_results.shorts.views": "",
  "shorts_results.shorts.video_id": ""
}

3. Playlist Result Example

When a playlist is retrieved, playlist fields are populated and other fields remain empty strings (""):

{
  "video_results.position_on_page": "",
  "video_results.title": "",
  "video_results.link": "",
  "video_results.video_id": "",
  "video_results.channel.name": "",
  "video_results.channel.link": "",
  "video_results.channel.thumbnail": "",
  "video_results.published_date": "",
  "video_results.views": "",
  "video_results.length": "",
  "video_results.description": "",
  "video_results.extensions.0": "",
  "video_results.thumbnail.static": "",
  "video_results.thumbnail.rich": "",
  "channel_results.position_on_page": "",
  "channel_results.title": "",
  "channel_results.link": "",
  "channel_results.handle": "",
  "channel_results.subscribers": "",
  "channel_results.description": "",
  "channel_results.thumbnail": "",
  "playlist_results.position_on_page": 2,
  "playlist_results.title": "#TopBook",
  "playlist_results.link": "https://www.youtube.com/playlist?list=PLpBWoHEpd0ayObBsMGMh_yjfnvQ0ncx-x",
  "playlist_results.channel.name": "TuttoTech",
  "playlist_results.channel.link": "https://www.youtube.com/@TuttoTech",
  "playlist_results.videos.0.link": "https://www.youtube.com/watch?v=eANiioMW39M&list=PLpBWoHEpd0ayObBsMGMh_yjfnvQ0ncx-x",
  "playlist_results.video_count": 68,
  "playlist_results.thumbnail": "https://i.ytimg.com/vi/eANiioMW39M/hq720.jpg",
  "ads_results.position_on_page": "",
  "ads_results.title": "",
  "ads_results.link": "",
  "ads_results.website": "",
  "ads_results.channel.name": "",
  "ads_results.channel.thumbnail": "",
  "ads_results.description": "",
  "ads_results.thumbnail.static": "",
  "shorts_results.position_on_page": "",
  "shorts_results.shorts.title": "",
  "shorts_results.shorts.link": "",
  "shorts_results.shorts.views_original": "",
  "shorts_results.shorts.views": "",
  "shorts_results.shorts.video_id": ""
}

4. Sponsored Ad Result Example

When an ad is retrieved, ads_results fields are populated and other fields remain empty strings (""):

{
  "video_results.position_on_page": "",
  "video_results.title": "",
  "video_results.link": "",
  "video_results.video_id": "",
  "video_results.channel.name": "",
  "video_results.channel.link": "",
  "video_results.channel.thumbnail": "",
  "video_results.published_date": "",
  "video_results.views": "",
  "video_results.length": "",
  "video_results.description": "",
  "video_results.extensions.0": "",
  "video_results.thumbnail.static": "",
  "video_results.thumbnail.rich": "",
  "channel_results.position_on_page": "",
  "channel_results.title": "",
  "channel_results.link": "",
  "channel_results.handle": "",
  "channel_results.subscribers": "",
  "channel_results.description": "",
  "channel_results.thumbnail": "",
  "playlist_results.position_on_page": "",
  "playlist_results.title": "",
  "playlist_results.link": "",
  "playlist_results.channel.name": "",
  "playlist_results.channel.link": "",
  "playlist_results.videos.0.link": "",
  "playlist_results.video_count": "",
  "playlist_results.thumbnail": "",
  "ads_results.position_on_page": 4,
  "ads_results.title": "See Top Picks of October 2026 - Best Laptops - Official Laptop Buying Guide",
  "ads_results.link": "https://www.google.com/aclk?sa=L&ai=DChs...",
  "ads_results.website": "https://www.google.com/aclk?sa=L&ai=DChs...",
  "ads_results.channel.name": "https://www.pcmag.com/top-10-picks/laptops",
  "ads_results.channel.thumbnail": "https://tpc.googlesyndication.com/simgad/12940295094016054608",
  "ads_results.description": "PCMag.Com Delivers Labs-Based, Independent Reviews Of The Latest Products. See Our #1 Pick. Lab Tested Reviews by...",
  "ads_results.thumbnail.static": "https://tpc.googlesyndication.com/simgad/12940295094016054608",
  "shorts_results.position_on_page": "",
  "shorts_results.shorts.title": "",
  "shorts_results.shorts.link": "",
  "shorts_results.shorts.views_original": "",
  "shorts_results.shorts.views": "",
  "shorts_results.shorts.video_id": ""
}

5. YouTube Short Result Example

When a short is retrieved, shorts_results fields are populated and other fields remain empty strings (""):

{
  "video_results.position_on_page": "",
  "video_results.title": "",
  "video_results.link": "",
  "video_results.video_id": "",
  "video_results.channel.name": "",
  "video_results.channel.link": "",
  "video_results.channel.thumbnail": "",
  "video_results.published_date": "",
  "video_results.views": "",
  "video_results.length": "",
  "video_results.description": "",
  "video_results.extensions.0": "",
  "video_results.thumbnail.static": "",
  "video_results.thumbnail.rich": "",
  "channel_results.position_on_page": "",
  "channel_results.title": "",
  "channel_results.link": "",
  "channel_results.handle": "",
  "channel_results.subscribers": "",
  "channel_results.description": "",
  "channel_results.thumbnail": "",
  "playlist_results.position_on_page": "",
  "playlist_results.title": "",
  "playlist_results.link": "",
  "playlist_results.channel.name": "",
  "playlist_results.channel.link": "",
  "playlist_results.videos.0.link": "",
  "playlist_results.video_count": "",
  "playlist_results.thumbnail": "",
  "ads_results.position_on_page": "",
  "ads_results.title": "",
  "ads_results.link": "",
  "ads_results.website": "",
  "ads_results.channel.name": "",
  "ads_results.channel.thumbnail": "",
  "ads_results.description": "",
  "ads_results.thumbnail.static": "",
  "shorts_results.position_on_page": 14,
  "shorts_results.shorts.title": "Top 10 BEST LAPTOP Brands 2025!",
  "shorts_results.shorts.link": "https://www.youtube.com/shorts/Wq6_eILGrpU",
  "shorts_results.shorts.views_original": "1.2M views",
  "shorts_results.shorts.views": 1200000,
  "shorts_results.shorts.video_id": "Wq6_eILGrpU"
}

---

Error Handling

If an error occurs or invalid input parameters are provided, the Actor reports a descriptive status message and halts cleanly:

Cause	Error Message / Status
Missing search terms	Missing required input parameter 'search_query'.
Invalid device	Parameter 'device' must be one of: 'desktop', 'mobile'.
Invalid num	Parameter 'num' must be an integer between 1 and 30.
Combined sp and num	Parameters 'num' and 'sp' cannot be combined. Please provide either 'num' or 'sp', not both.
Upstream service error	Descriptive error message with HTTP status code and details.

---

Related Actors & Recommended Workflow

Looking to extract full transcripts, subtitles, or AI summaries from the videos you found?

Check out Youtube Text, AI & Metadata Scraper:

• Full Transcripts & Subtitles: Extract complete, timestamped transcripts and subtitles in any available language.
• AI Summarization: Automatically generate AI-powered summaries, key topics, and takeaways from long videos.
• Deep Metadata: Retrieve detailed view counts, likes, hashtags, complete descriptions, and publication details.
• Perfect Pipeline: Combine this Actor (for search discovery and URL gathering) with Youtube Text, AI & Metadata Scraper for full video analysis and text extraction.