Skip to content

About

YouTube API without quotas: scrape YouTube search rankings, video details, transcripts (with translation) and comments as structured JSON from one endpoint, in any country. Python, Node.js, Go, PHP and cURL examples.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

Repository files navigation

YouTube API

Semust YouTube API: YouTube search, videos, transcripts and comments as JSON

Get API key Documentation MCP server License: MIT

The Semust YouTube API returns YouTube data as clean, structured JSON from one endpoint: search rankings for a keyword (videos, Shorts, playlists, channels and ads), full video details, transcripts with optional translation, and the comments of any public video. Pick the report with type, send a keyword or a video URL, and get the answer as a viewer in that country would see it. No daily quotas, OAuth setup or HTML parsing on your side.

It is built for SEO teams, content marketers and developers who need YouTube rank tracking, video competitor research, transcript extraction and comment analysis. The API is part of the Semust SEO platform.

How it works

Your code sends POST /v1/youtube to Semust and receives YouTube data as JSON. Long requests return 202 and are collected from /v1/tasks.

1. Get your API credentials

Create an API user on the Semust API access page. You get a username and a password. Every request sends them as two headers:

Header Value
SEMUST-API-USER Your API username
SEMUST-API-PASSWORD Your API password

The examples in this repository read them from environment variables, so they never end up in your code:

export SEMUST_API_USER="your_username"
export SEMUST_API_PASSWORD="your_password"

Tip

There is no subscription. You top up a prepaid balance and pay only for successful requests; failed requests are refunded automatically. Prices are on the YouTube API page.

2. Send a request

import os, time, requests

HEADERS = {
    "SEMUST-API-USER": os.environ["SEMUST_API_USER"],
    "SEMUST-API-PASSWORD": os.environ["SEMUST_API_PASSWORD"],
}

resp = requests.post(
    "https://data.semust.com/v1/youtube",
    params={"wait": 60},
    headers=HEADERS,
    json={"type": "search", "keyword": "technical seo", "country": "US", "language": "en", "limit": 20},
    timeout=90,
)
while resp.status_code == 202:  # still running: poll the task
    time.sleep(int(resp.headers.get("Retry-After", 5)))
    resp = requests.get(resp.json()["poll_url"], headers=HEADERS, timeout=30)

for row in resp.json()["items"]:
    print(row["position"], row["type"], row["title"], row["views"])

3. Run the examples

Language File Run
Python examples/python/youtube.py python youtube.py "technical seo"
Python, transcript downloader examples/python/transcript.py python transcript.py "https://www.youtube.com/watch?v=_bewU9AvKwU"
Node.js 18+ examples/node/youtube.mjs node youtube.mjs "technical seo"
Go examples/go/main.go go run . "technical seo"
PHP examples/php/youtube.php php youtube.php "technical seo"
cURL examples/curl/youtube.sh ./youtube.sh

Request parameters

POST https://data.semust.com/v1/youtube with a JSON body. One endpoint serves four reports, chosen with type:

type Returns Needs
search (default) YouTube results for a keyword, in ranking order: videos, Shorts, playlists, channels and ads keyword
video One video's details: views, likes, comment count, channel and subscribers, exact publish date, duration, category, tags, and which transcripts it has video_id
transcript One video's transcript as plain text plus timed segments, optionally translated video_id
comments A video's top-level comments with author, likes and reply counts video_id
Parameter Type Default Used by Description
type string search all search, video, transcript or comments.
keyword string – search (required) The search query, up to 200 characters.
video_id string – video, transcript, comments (required) The 11-character video ID or any YouTube video URL (watch?v=, youtu.be/, shorts/, embed/, live/).
country string TR all Two-letter country code: where the search runs from and the region a video is read in. Send it explicitly; the default is Türkiye.
language string tr for TR, else en search Interface language of the search, such as en, de, pt-BR.
device string desktop search desktop or mobile.
limit integer 20 search, comments Results to return, 1–200. Billed per started block of 20, so 20, 40 and 60 are the economical sizes.
transcript_language string tr for TR, else en transcript Which transcript to read, such as en or en-GB. type: "video" lists the transcripts a video has.
translate_to string – transcript Translate the transcript into this language, such as de.
idempotency_key string – all Optional, up to 128 characters. Same as the Idempotency-Key header; if you send both, this field wins.

A parameter the chosen type does not take is rejected with PARAMETER_NOT_ALLOWED instead of being ignored, and a misspelled one is named in the error with a suggestion. GET https://data.semust.com/v1/youtube/markets lists every supported country and search language, free of charge.

Query parameter Default Description
wait 60 Seconds to hold the connection before answering 202, 0–80. 0 answers 202 at once (fire and collect).
Header Description
Idempotency-Key Optional, up to 128 characters. Repeating a request with the same key returns the same task and is charged once.
Accept-Language Optional. tr returns error messages in Turkish.

Output sample

YouTube search results for "technical seo" returned by the Semust YouTube API

A shortened response for {"type": "search", "keyword": "technical seo", "country": "US", "language": "en", "limit": 20}. Lists are cut to two items; the complete response is in output-youtube-scraper.json. The per-call request_id is removed from the sample file.

{
  "success": true,
  "type": "search",
  "keyword": "technical seo",
  "country": "US",
  "language": "en",
  "device": "desktop",
  "total": 4603789,
  "count": 20,
  "limit": 20,
  "items": [
    {
      "position": 1,
      "type": "video",
      "title": "What is Technical SEO and Why is it Important? - 4.1. SEO Course by Ahrefs",
      "url": "https://www.youtube.com/watch?v=_bewU9AvKwU",
      "video_id": "_bewU9AvKwU"
    },
    {
      "position": 2,
      "type": "video",
      "title": "9 Must-Know Technical SEO Practices for 2026",
      "url": "https://www.youtube.com/watch?v=o7miIuomJoE",
      "video_id": "o7miIuomJoE"
    }
  ],
  "cost": 0.0022,
  "cached": false
}

Every documented key is on every row. A value that does not exist or does not apply is null, never 0: a playlist has "views": null and a video has "video_count": null.

JSON output structure

Envelope (every type)

Field Type Description
success boolean true for a successful request.
type string The report that ran.
keyword string search only. The query as run.
video_id string video, transcript, comments. The 11-character ID, also when you sent a URL.
country string The country the request ran in.
language, device string search only. Interface language and device.
total integer search: the result count YouTube reports. comments: the video's comment count.
count integer search, comments. Rows in items.
limit integer search, comments. The limit that was requested.
items array search and comments rows.
data object video and transcript result.
cost number What this request cost, in USD.
cached boolean true when the answer came from cache.
request_id string Identifier of this request; quote it when you contact support.

search row

Field Type Description
position integer Rank on the results page, starting at 1.
type string video, short, playlist, channel or ad.
title, url string Title and canonical YouTube link.
video_id string | null For videos, Shorts and ads.
channel_name, channel_url string | null The channel that published it.
views integer | null View count, for videos.
video_count integer | null Number of videos, for playlists and channels.
published_at string | null Publish time, ISO 8601 in UTC. Approximate here, because YouTube shows relative dates in search ("5 years ago"); type: "video" gives the exact date.
duration_seconds integer | null Length in seconds, for videos.
is_live boolean | null true for a live stream.

video → data

Field Type Description
video_id, title, url string The video.
description string | null Full description.
channel_name, channel_url string | null The channel.
channel_subscribers integer | null The channel's subscriber count.
views, likes, comments integer | null Engagement counts.
published_at string | null Exact publish time, ISO 8601 in UTC.
duration_seconds integer | null Length in seconds.
category string | null YouTube category.
tags array The uploader's tags.
is_live boolean true for a live stream.
transcripts array Transcripts the video has, each {language, auto_generated}. Pass a language as transcript_language.

transcript → data

Field Type Description
video_id string The video.
title string | null Video title.
language string | null Language of the transcript that was read.
translated_to string | null Target language when translate_to was sent.
text string The whole transcript as one string.
segments array Timed lines, each {start, end, text}, times in seconds.

comments row

Field Type Description
author, author_url string Comment author and their channel link (author_url can be null).
text string Comment text.
likes, replies integer Like and reply counts.
published_at string | null When it was posted, ISO 8601 in UTC.

Long-running requests (202 and polling)

Most requests finish in a few seconds and return 200 with the result. If a request is still running after wait seconds (60 by default, maximum 80), the API returns 202 Accepted with a task_id instead. Nothing is lost and you are not charged twice:

  1. Read task_id from the body (also in the X-Task-Id header).
  2. Wait Retry-After seconds.
  3. Call GET https://data.semust.com/v1/tasks/{task_id} with the same headers until the status is no longer 202. The final answer is exactly what the original request would have returned.

Every example in examples/ already handles this. Results stay available for 72 hours, and fetching them again is free. Set your HTTP client's read timeout above wait (for example wait + 30 seconds). Send an Idempotency-Key header to retry a request safely without paying twice. Details: Tasks & long-running requests.

Errors

Errors return JSON with a readable error, a stable code and retryable; where it helps also field, hint and allowed. Errors are never charged.

HTTP code Meaning
400 INVALID_JSON, UNKNOWN_PARAMETER, INVALID_TYPE, PARAMETER_NOT_ALLOWED, INVALID_PARAMETER The body is not a JSON object, a parameter is misspelled or not taken by this type, or a value is out of range. field names it.
400 KEYWORD_REQUIRED, VIDEO_ID_REQUIRED, INVALID_VIDEO_ID search without a keyword, a video report without video_id, or a value that is not a video ID or URL.
400 UNSUPPORTED_MARKET Unknown country or language. GET /v1/youtube/markets lists them.
401 MISSING_CREDENTIALS, INVALID_CREDENTIALS, CREDENTIALS_EXPIRED Check the two auth headers.
402 INSUFFICIENT_CREDITS Your balance does not cover the request. Top up or lower limit.
403 IP_NOT_WHITELISTED, SERVICE_NOT_ENABLED Your API user only accepts listed IP addresses, or YouTube is not enabled for it.
404 VIDEO_NOT_FOUND, TRANSCRIPT_NOT_FOUND The video does not exist or is private, removed or blocked in that country; or it has no transcript in that language.
429 RATE_LIMIT_EXCEEDED, TOO_MANY_CONCURRENT_REQUESTS Slow down. At most 10 YouTube requests per API user run at the same time; wait Retry-After seconds.
503 REQUEST_FAILED, SERVICE_BUSY, SERVICE_UNAVAILABLE, TIMEOUT Temporary failure. If retryable is true, retry with the same Idempotency-Key.

Pricing

Report Price
search, comments $0.0022 per started block of 20 results
video $0.0066 per video
transcript $0.0066 per video

The cost of limit is reserved when a request starts and anything unused is refunded when it finishes, so a search with limit: 40 that returns 18 results costs one block. A search or comment list with no results is a valid answer, billed at one block. Answers are cached (search, video details and comments for 24 hours, transcripts for 30 days); a cached answer is marked "cached": true and costs the same as a live one. Failed requests are refunded automatically. Current prices are on the YouTube API page.

Use cases

  1. YouTube rank tracking. Check where your videos rank for each keyword, by country and on desktop or mobile, and watch competitors move.
  2. Video competitor research. Pull the titles, tags, durations, views and channel sizes of the videos that rank, and see what a winning video looks like for a topic.
  3. Transcripts for content and AI. Turn videos into blog posts, summaries, subtitles or retrieval data for an LLM, in the original language or translated. Start from transcript.py.
  4. Comment mining. Collect audience questions, objections and feature requests from comments to plan FAQs, scripts and product pages.
  5. Creator and channel discovery. Find the channels that rank for your niche keywords, with subscriber counts, for partnerships or influencer outreach.

Why Semust

  • Pay as you go. No monthly plan or minimum commitment for the API. Top up once, pay per successful request, and get failed requests refunded automatically.
  • One account, every SEO dataset. SERP, keyword data, backlinks, domain research, YouTube, Google Trends, Lighthouse and Google Business data use the same credentials, the same error format and the same task system.
  • Any country, any language. Localised results for every Google market, including strong coverage of Türkiye and Turkish-language queries.
  • Built for AI workflows. Plug the same data into Claude, Cursor or ChatGPT with the open-source Semust MCP server.

FAQ

Is scraping YouTube data legal?

The API reads public data: search results, public video pages, captions and comments. Collecting public data is generally lawful in many jurisdictions, but laws differ by country and how you store and reuse the data matters, especially transcripts, which belong to their creators. Check the rules that apply to you, or ask a lawyer. This is not legal advice.

Do I need a YouTube Data API key or quota?

No. You only need your Semust API credentials. There is no daily quota; you pay per request, and requests are limited by the rate limits on your API user.

Can I get the transcript of any video?

Any public video that has a transcript, not only your own. Send type: "video" first to see which transcript languages a video has, then pass one as transcript_language. Add translate_to to get it in another language.

Can I paste a full YouTube URL instead of the video ID?

Yes. video_id accepts the 11-character ID or any common URL form: watch?v=, youtu.be/, shorts/, embed/ and live/, on www., m. and music. hosts.

How many results can I get per request?

Up to 200 search results or comments with limit. Billing is per started block of 20, so ask for the depth you will actually use.

Can I use it from Claude, ChatGPT or Cursor?

Yes, through a tool your agent can call: the Python example is a ready-made starting point. The Semust MCP server also connects AI assistants to your Semust account data; see Semust MCP for what it covers.

Learn more

Related repositories

SEO data APIs

Repository What it does Product page
google-serp-scraper Organic results, People Also Ask, AI Overviews, ads and more as JSON Google SERP API
google-images-scraper Google Images results with titles, source pages and image URLs Google Images API
google-trends-scraper Interest over time, regions, related queries and demographics Google Trends API
google-business-scraper Google Business profiles, local search and reviews Google Business Data API
keyword-research-api Search volume, CPC, competition, intent and related keywords Keyword Research API
backlinks-api Backlinks, referring domains, anchors and link history Backlinks API
domain-research-api Organic keywords, competitors, top pages and keyword gaps for any domain Domain Research API
technical-seo-api 27 technical SEO checks for any URL in one call Technical SEO API
lighthouse-on-page-api Lighthouse scores, on-page audits and page content extraction Lighthouse & On-Page API

MCP servers for AI assistants

Repository What it does Product page
semust-mcp One MCP server for Search Console, GA4, Google Ads, rank tracking and social posting Semust MCP Server
seo-mcp Search Console, rank tracking, indexing and competitor tools for AI assistants SEO MCP
google-search-console-mcp Ask your AI assistant about clicks, queries and pages Google Search Console MCP
google-analytics-mcp GA4 traffic, channels and conversions in your AI assistant Google Analytics MCP
google-ads-mcp Campaigns, search terms and spend in your AI assistant Google Ads MCP
rank-tracker-mcp Keyword rankings and AI-search visibility for AI assistants Rank Tracker MCP
web-analytics-mcp Privacy-friendly first-party analytics in your AI assistant Web Analytics MCP
bing-webmaster-mcp Bing queries, pages, links and crawl issues Bing Webmaster MCP
yandex-metrica-mcp Yandex Metrica traffic and search phrases Yandex Metrica MCP
social-media-mcp Draft and schedule LinkedIn, Facebook and Instagram posts Social Media MCP

Support

Found a problem with an example? Open an issue.

License

The code examples in this repository are released under the MIT License. Use of the Semust API is subject to the Semust Terms of Service.

About

YouTube API without quotas: scrape YouTube search rankings, video details, transcripts (with translation) and comments as structured JSON from one endpoint, in any country. Python, Node.js, Go, PHP and cURL examples.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors