# YouTube Scraper API - Videos, Channels, Playlists, Shorts > Source: https://scrape.do/products/ready-api/youtube-scraper/ Scrape YouTube search results with videos, channels, playlists, Shorts shelves, and ads as structured JSON. Filter by sort, duration, features, and upload date. Full localization, no JavaScript rendering, no render fee. > Each successful request costs **10 credits**. **YouTube Search Results as Structured JSON** Pull videos, channels, playlists, and Shorts straight from YouTube as clean, ready-to-use JSON. View counts and subscriber numbers come back as actual integers, with no parsing, no headless browsers, and no cookie walls to deal with. ![YouTube Search Results as Structured JSON](/uploads/youtube-api.png) ## Highlights ### Every Result Type in a Single Call - Search YouTube once and get back **videos, channels, playlists, and Shorts**, each as its own clean array. Build a channel directory, a playlist library, or a Shorts feed without juggling separate scrapers. - Every video arrives with the fields you'd otherwise extract by hand: views as a real integer, channel handle and verified badge, duration, upload date, thumbnails, and visual tags like 4K, HD, LIVE, and CC. ### Precision Filters, Built In - Pull **the top-rated 4K nature documentaries from Germany this week**, or just channels above a subscriber threshold, or only long-form videos sorted by views. Every filter YouTube exposes is a single parameter away. - Sort by relevance, rating, upload date, or view count. Restrict by duration, upload window, video quality, or live status. Pagination uses the same parameter, so one helper handles filtering and continuation. ## How It Works ### Basic Search Search YouTube by keyword. Returns up to 20 videos plus channels, playlists, and Shorts shelves that YouTube interleaves on the page. Discovery rails (people_also_watched, channels_new_to_you, related_searches) come back when YouTube renders them. ![Basic Search](/uploads/youtube-search-results.png) **cURL (API mode)** ```bash curl --location --request GET 'https://api.scrape.do/plugin/google/youtube?token=&search_query=best+laptop+2025' ``` **Python (API mode)** ```python import requests import json token = "" url = f"https://api.scrape.do/plugin/google/youtube?token={token}&search_query=best+laptop+2025" response = requests.request("GET", url) print(json.dumps(response.json(), indent=2)) ``` **Node.js (API mode)** ```javascript const axios = require('axios'); const token = ""; const url = `https://api.scrape.do/plugin/google/youtube?token=${token}&search_query=best+laptop+2025`; axios.get(url) .then(response => { console.log(JSON.stringify(response.data, null, 2)); }) .catch(error => { console.error(error); }); ``` *(Go, Ruby, Java, C#, PHP examples are also available on the HTML version.)* **Example response** ```json { "search_parameters": { "engine": "google_youtube", "search_query": "best laptop 2025", "gl": "us", "hl": "en" }, "search_information": { "total_results": 16406969 }, "video_results": [ { "position_on_page": 2, "title": "The Best Laptops of 2025", "link": "https://www.youtube.com/watch?v=PKshhTHyoZU", "video_id": "PKshhTHyoZU", "channel": { "name": "Just Josh", "link": "https://www.youtube.com/@JustJoshTech", "verified": true, "thumbnail": "https://yt3.ggpht.com/..." }, "published_date": "4 months ago", "views": 313829, "length": "12:38", "description": "Save BIG on Your Laptop: ...", "extensions": ["4K"], "thumbnail": { "static": "https://i.ytimg.com/vi/PKshhTHyoZU/hqdefault.jpg" }, "live": false } ], "shorts_results": [ { "position_on_page": 5, "shorts": [ { "title": "Top 3 Laptops", "link": "https://www.youtube.com/shorts/abc123", "views": 2100000, "video_id": "abc123" } ] } ], "related_searches": [ { "query": "best laptop 2025 under 1000" }, { "query": "best gaming laptop 2025" } ], "pagination": { "next_page_token": "EqwDEhBiZXN0..." } } ``` ### Channels Filter Pass sp=EgIQAg%3D%3D to switch the result page to channel cards. Returns channel name, link, handle, subscriber count (parsed to integer), description, and avatar, populated in channel_results instead of video_results. ![Channels Filter](/uploads/youtube-channels.png) **cURL (API mode)** ```bash curl --location --request GET 'https://api.scrape.do/plugin/google/youtube?token=&search_query=best+laptop+2025' ``` **Python (API mode)** ```python import requests import json token = "" url = f"https://api.scrape.do/plugin/google/youtube?token={token}&search_query=best+laptop+2025" response = requests.request("GET", url) print(json.dumps(response.json(), indent=2)) ``` **Node.js (API mode)** ```javascript const axios = require('axios'); const token = ""; const url = `https://api.scrape.do/plugin/google/youtube?token=${token}&search_query=best+laptop+2025`; axios.get(url) .then(response => { console.log(JSON.stringify(response.data, null, 2)); }) .catch(error => { console.error(error); }); ``` *(Go, Ruby, Java, C#, PHP examples are also available on the HTML version.)* **Example response** ```json { "search_parameters": { "engine": "google_youtube", "search_query": "tech reviewer", "gl": "us", "hl": "en", "sp": "EgIQAg==" }, "channel_results": [ { "position_on_page": 1, "title": "Marques Brownlee", "link": "https://www.youtube.com/@mkbhd", "verified": true, "handle": "@mkbhd", "subscribers": 20700000, "description": "MKBHD - Quality Tech Videos.", "thumbnail": "https://yt3.ggpht.com/..." }, { "position_on_page": 2, "title": "Just Josh", "link": "https://www.youtube.com/@JustJoshTech", "verified": true, "handle": "@JustJoshTech", "subscribers": 379000, "description": "Finding You The Best Laptop!", "thumbnail": "https://yt3.ggpht.com/..." } ] } ``` ### Filtered Search (Duration, 4K, Localized) Combine sp tokens with hl/gl for tightly scoped queries. Here is a German 4K nature-documentary search. The response carries localized published_date and length strings, and only 4K-flagged videos. ![Filtered Search (Duration, 4K, Localized)](/uploads/youtube-filtered.png) **cURL (API mode)** ```bash curl --location --request GET 'https://api.scrape.do/plugin/google/youtube?token=&search_query=best+laptop+2025' ``` **Python (API mode)** ```python import requests import json token = "" url = f"https://api.scrape.do/plugin/google/youtube?token={token}&search_query=best+laptop+2025" response = requests.request("GET", url) print(json.dumps(response.json(), indent=2)) ``` **Node.js (API mode)** ```javascript const axios = require('axios'); const token = ""; const url = `https://api.scrape.do/plugin/google/youtube?token=${token}&search_query=best+laptop+2025`; axios.get(url) .then(response => { console.log(JSON.stringify(response.data, null, 2)); }) .catch(error => { console.error(error); }); ``` *(Go, Ruby, Java, C#, PHP examples are also available on the HTML version.)* **Example response** ```json { "search_parameters": { "engine": "google_youtube", "search_query": "naturdokumentation", "gl": "de", "hl": "de", "sp": "EgJwAQ==" }, "video_results": [ { "position_on_page": 1, "title": "Wildes Skandinavien | Eine Reise in 4K", "link": "https://www.youtube.com/watch?v=xxxxx", "video_id": "xxxxx", "channel": { "name": "Terra Mater Studios", "verified": true }, "published_date": "vor 2 Monaten", "views": 1200000, "length": "1:48:30", "extensions": ["4K"], "live": false } ] } ``` ## FAQ ### How does this differ from using the official YouTube Data API? The YouTube Data API has a strict daily quota (10,000 units default), and a search call costs 100 units, which works out to 100 searches per project per day. It also doesn't return Shorts shelves, ads, or discovery rails the way the search page does. This plugin scrapes the public results page: no quota, returns the full page layout (videos, channels, playlists, Shorts, related rails), and you pay per successful request. ### What can I do with the `sp` parameter? `sp` is YouTube's opaque filter token. Short values control **sort** (rating, upload date, view count), **result type** (videos-only, channels-only, playlists-only), **duration** (under 4min, 4–20min, over 20min), **features** (4K, HD, LIVE, CC), and **upload date** (hour, today, week, month, year). The same parameter accepts continuation cursors for pagination; the plugin routes filter tokens and pagination tokens automatically based on length. ### Do I get Shorts in the response? Yes, when YouTube renders them. Shorts come back as `shorts_results[]`, an array of shelves. Each shelf has a `position_on_page` (so you know where it sat in the result list) and a `shorts[]` array of individual Short videos with title, link, thumbnail, views (parsed to integer + original display string), and video id. Shorts shelves are unpredictable; expect 0, 1, or multiple per query depending on the topic and locale. ### How do I paginate? Every response that has more pages includes `pagination.next_page_token`. Pass that value back as the `sp` parameter on a new request to fetch the next page. The same `sp` parameter handles both filter tokens and pagination cursors: short values filter, long values paginate, and the plugin routes them automatically. Continuation is stable for tens of pages; very deep pagination (>50 pages) may start returning empty `video_results` as YouTube exhausts the feed. ### Can I get channel info or playlist contents? You can list channels and playlists via `sp=EgIQAg==` (channels filter) and `sp=EgIQAw==` (playlists filter). Each response gives handle, subscriber count (parsed integer), avatar, description for channels; lead video, total video count, and cover thumbnail for playlists. Deep channel-page or playlist-contents scraping isn't covered by this plugin today; it's the **search results** API. ### Are the metadata strings localized? Yes. `hl` controls the language of `published_date` (`"4 months ago"` → `"vor 4 Monaten"`), `length` (`"12:38"` stays numeric, but units like `Std.` / `Std.` localize), and view-count suffixes (`"1.2M views"` → `"1,2 Mio. Aufrufe"`). `gl` influences ranking and which shelves render. Match `hl` to `gl` for the cleanest locale experience (`hl=de&gl=de`). ### What about ads in the response? Promoted entries come back in `ads_results[]` when YouTube renders them, with title, link, advertiser channel info, description, and thumbnail. YouTube runs many ad layouts in parallel, and unknown layouts are skipped rather than returned as partial objects, so `ads_results` may be empty even when ads were shown in the page HTML. ### Does it cost extra credits to use the `sp` filters? No. Every request to the plugin is **10 credits** flat, regardless of which `sp` token (or none) is passed. Filtering, sorting, and pagination don't add cost. There's no render fee, because the plugin doesn't run JavaScript. ### Why do consecutive searches return slightly different results? YouTube reorders search results continuously. Even with identical parameters, consecutive calls can return a 60–95% overlap depending on the query. This is inherent to the surface, not the plugin. Sort modes (`sp=CAM==` for view count, `sp=CAI==` for upload date) give more stable orderings than default relevance. ### Where can I find the full API reference? The [YouTube API documentation](/documentation/youtube-api/) covers the full parameter list, response schema for every result type (videos, channels, playlists, Shorts, ads, discovery rails), the complete `sp` token table for sort/type/duration/features/upload-date, and pagination patterns.