# YouTube Movies & TV Catalog Scraper (`drtikol/youtube-movies-catalog`) Actor

Scrapes YouTube's Movies & TV storefront for any region into a structured, daily-refreshed catalog: titles, credits, genres, full audio/subtitle language lists, direct links and availability.

- **URL**: https://apify.com/drtikol/youtube-movies-catalog.md
- **Developed by:** [Midar](https://apify.com/drtikol) (community)
- **Categories:** Agents, Automation, Videos
- **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## YouTube Movies & TV Catalog Scraper

Turns YouTube's Movies & TV storefront into a structured, daily-refreshable
dataset — no official API for this exists. Point it at a region and get back
every title currently listed there: names, credits, genres, **full audio and
subtitle language lists**, direct links and live availability.

### Why this instead of scraping the page yourself

- **No browser needed.** Talks to YouTube's internal data API directly, so
  runs are fast and cheap.
- **Region-correct by construction.** YouTube keys its entire catalog off
  the request's IP — including using *different video IDs for the same film*
  in different countries. This actor pairs the region parameter with a
  matching proxy automatically, a trap that's easy to get wrong by hand.
- **Full language lists, not summaries.** Most scrapes stop at "English (+19
  more)". This one reads the labelled per-title language table and returns
  every dubbed audio track and every subtitle language by name — with
  machine-translated subtitles kept separate from human-authored ones.
- **Stateful.** Re-running the actor doesn't just re-scrape from scratch: it
  tracks which titles it has already seen, adds new releases, and re-checks
  older titles to catch ones that quietly dropped out of the catalog.

### What you get (one record per title)

```json
{
  "youtubeId": "SttkHPYZAQo",
  "title": "Project Hail Mary",
  "originalTitle": "Project Hail Mary",
  "year": 2026,
  "genre": "Action & Adventure",
  "genres": ["Action & Adventure", "Sci-Fi", "Drama"],
  "directors": ["Christopher Miller", "Phil Lord"],
  "cast": ["Ryan Gosling", "Sandra Hüller", "..."],
  "studio": "MGM TVOD",
  "durationSeconds": 9383,
  "ageRating": "PG-13",
  "offerType": "Buy or rent",
  "directLink": "https://www.youtube.com/watch?v=SttkHPYZAQo",
  "thumbnailUrl": "https://i.ytimg.com/vi_webp/SttkHPYZAQo/movieposter.webp",
  "available": true,
  "audioLanguages": ["English", "French (France)", "German", "..."],
  "subtitleLanguages": ["English", "German", "Spanish", "..."],
  "autoSubtitleLanguages": [],
  "hasCzechAudio": false,
  "hasCzechSubtitles": false
}
```

See the **Output tab** for the complete field reference.

### A note on prices

YouTube hides numeric buy/rent prices from logged-out requests entirely —
there's no way around that without a personal account's session, which this
actor deliberately never uses (a shared credential would put every user's
traffic on one Google account and risk it getting banned). `offers` is
therefore always empty and `priceRequiresAuth` is always `true`. Everything
else — catalog, credits, languages, live availability — is complete.

### Input

| Field | Default | Notes |
|---|---|---|
| `gl` | `US` | Region code. **Must match the proxy country** — see below. |
| `hl` | `en` | Interface language for titles/labels. |
| `enrichDetails` | `true` | Fetch each title's page for credits, languages, synopsis. |
| `recheckAvailability` | `true` | Re-check known titles to catch ones removed from sale. |
| `recheckIntervalDays` | `5` | Spreads re-checks across runs instead of hitting everything every time. |
| `forceRecheckAll` | `false` | One-off full refresh, ignoring the interval. |
| `seedVideoIds` | — | Extra YouTube video IDs to track alongside the storefront. |
| `proxyConfiguration` | Apify Proxy | **Use a proxy in the same country as `gl`.** A mismatch silently returns the wrong region's catalog rather than erroring. |

### Running it daily

Add an Apify Schedule (e.g. once a day). Each run publishes a full snapshot
to the dataset and persists its own catalog state, so new releases get added
and stale/removed titles get flagged automatically over time.

### Limitations

- Prices are not available (see above).
- YouTube's internal API can change its response shape without notice;
  parsing is defensive, but if a run ever returns near-zero results, that's
  the most likely cause — please open an issue.

# Actor input Schema

## `gl` (type: `string`):

Two-letter region code (e.g. CZ, US, DE). Drives which catalog you get. Must match the proxy country below — YouTube resolves the storefront by request IP, not by this parameter alone.

## `hl` (type: `string`):

Interface language for titles, genres and labels.

## `enrichDetails` (type: `boolean`):

Visit each title's page to add original title, synopsis, credits, full audio/subtitle language lists and availability. Slower but much richer — recommended.

## `recheckAvailability` (type: `boolean`):

Re-visit titles already in the catalog to detect ones that dropped out of the offering (available=false).

## `recheckIntervalDays` (type: `integer`):

Only re-check a known title if it hasn't been checked for this many days. Spreads availability checks across runs instead of re-checking everything every time.

## `forceRecheckAll` (type: `boolean`):

Re-check every known title this run, ignoring the interval. Use for a one-off full refresh.

## `seedVideoIds` (type: `array`):

Optional YouTube video ids to track alongside whatever the storefront lists.

## `proxyConfiguration` (type: `object`):

Use a proxy located in the SAME country as 'gl'. YouTube keys the entire catalog off the request's IP region — a mismatched proxy silently returns a different country's titles (and different video IDs for the same film), not an error.

## Actor input object example

```json
{
  "gl": "US",
  "hl": "en",
  "enrichDetails": true,
  "recheckAvailability": true,
  "recheckIntervalDays": 5,
  "forceRecheckAll": false,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("drtikol/youtube-movies-catalog").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("drtikol/youtube-movies-catalog").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call drtikol/youtube-movies-catalog --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,drtikol/youtube-movies-catalog"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/zJsFtolzX5bP1laTu/builds/UfF7UCw7hFFTNLq3x/openapi.json