# YouTube Trending Feed Extractor by Category & Market (`nimbryxo-studio/youtube-trending-feed-extractor-by-category`) Actor

Get video lists for YouTube's Gaming, Music, News, Movies and Trending sections in any of 31 regional markets, with views, duration and channel details; rows from a fallback search are labeled.

- **URL**: https://apify.com/nimbryxo-studio/youtube-trending-feed-extractor-by-category.md
- **Developed by:** [Nimbryxo-studio](https://apify.com/nimbryxo-studio) (community)
- **Categories:** Videos, Social media, News
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.49 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## YouTube Trending Feed Extractor by Category & Market

Pull video lists for YouTube's Gaming, Music, News, Movies and main Trending sections in any of 31 regional markets, with position, channel, view count, duration and thumbnail for each entry, and a clear label on rows that came from a fallback search.

### What this actor does

- Tries YouTube's Gaming, Music, News and main Trending pages first
- Uses a labeled public YouTube search instead when a page can't be read (always for Movies, and for Gaming when the page lists fewer than 10 items), marking every row with `sourceType` and the `fallbackQuery` used
- Targets any of 31 regional markets so results reflect what's trending in that country
- Captures playlists and albums alongside individual videos when a category page shows them, and removes duplicates
- Omits any field that has no value for a given row rather than returning null

### Output per item

| Field | Description |
|---|---|
| `position` | Order in the returned list (page order for category pages, search order for search-fallback rows) |
| `type` | `video`, `playlist`, or `album` |
| `videoId` | YouTube video ID, for video rows |
| `playlistId` | YouTube playlist/album ID, for playlist or album rows |
| `url` | Link to the video or playlist |
| `title` | Video or playlist title |
| `channelName` | Channel display name |
| `channelId` | Channel's YouTube ID, when resolved |
| `channelUrl` | Full channel URL, when resolved |
| `channelHandle` | Channel's @handle, when available |
| `isVerified` | Whether the channel shows a verified badge (video rows only) |
| `viewCount` | View count as a number, when parseable |
| `viewCountText` | View count exactly as displayed, e.g. "3.2M views" |
| `publishedTimeText` | Relative publish time as displayed, e.g. "2 days ago" |
| `publishedDate` | Upload date, when it can be read from the video's own page (video rows) |
| `durationText` | Duration as displayed, e.g. "12:34" |
| `durationSeconds` | Duration converted to seconds |
| `thumbnailUrl` | Highest-resolution thumbnail URL available |
| `badges` | Badge labels shown on the item, e.g. "4K", "CC" |
| `isLive` | Whether the item is a live stream |
| `category` | The input category used for this run |
| `market` | The regional market used for this run |
| `sourceType` | `category_page` when read directly, or `search_fallback` when a fallback search was used |
| `fallbackQuery` | The search query used, only present when `sourceType` is `search_fallback` |
| `scrapedAt` | UTC timestamp of when the record was scraped |

**Status rows:** if a run finds nothing, the dataset gets a single status row instead of video rows. For `category: "now"` when even the search fallback fails, that row is `{success: false, category, market, sourceType: "auth_required", error, scrapedAt}`. For any other category with no results, it is `{recordType: "status", status: "no_results", category, market, resultCount: 0, scrapedAt}`. Filter these out by checking for `videoId`/`playlistId`.

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `category` | string | `gaming` | Trending section to read: now (main Trending feed), gaming, music, movies, or news |
| `maxResults` | integer | `50` | Maximum number of items to return (1–200) |
| `market` | string | `US` | Regional market (31 options), e.g. US, GB, CA, AU, DE, FR, JP, KR, BR, IN, MX. It sets the region and interface language used for the page or search |

#### Category notes

- `gaming` reads the YouTube Gaming page; if that page shows fewer than 10 items, a search for "gaming" is used instead.
- `news` reads the YouTube News page's shelves; if they can't be read, it searches "latest news" (then "world news").
- `music` reads the YouTube Music channel's playlists and videos; if they can't be read, it searches "official music video" (then "new music").
- `now` tries the main Trending page, which usually needs a signed-in session; when it's unavailable, it searches "trending videos" (then "popular videos").
- `movies` always uses a search for "new movie trailer <current year>" (then "official movie trailer").

Search-fallback rows are ordinary search results for that phrase in the chosen market, not YouTube's own trending ranking.

#### Example: gaming trending in Japan

```json
{
  "category": "gaming",
  "maxResults": 20,
  "market": "JP"
}
```

#### Example: main trending feed, US

```json
{
  "category": "now",
  "maxResults": 50,
  "market": "US"
}
```

#### Example: music trending in Brazil

```json
{
  "category": "music",
  "maxResults": 20,
  "market": "BR"
}
```

### Use cases

- **Daily trend monitoring** — schedule runs to track what's rising in Gaming or Music each day
- **Content strategy** — see which video lengths, formats and titles are performing well right now
- **Competitive and creator intelligence** — spot which channels keep appearing across trending categories
- **Cross-market comparison** — run the same category across several `market` values to compare regional trends
- **News-cycle tracking** — use `news` to capture the day's top-story videos

### FAQ

**Why do some rows say `search_fallback`?**
YouTube's main Trending feed and the Movies channel aren't available without signing in, and the other category pages sometimes can't be read either. Rather than returning nothing, the actor runs a public search instead and marks every resulting row with `sourceType: "search_fallback"` plus the `fallbackQuery` it used, so you always know where a row came from. Rows read from the category page itself carry `sourceType: "category_page"`.

**How many items can one run return?**
Up to `maxResults` (200 max). The real number depends on how many items the category page or fallback search shows on the day, after duplicates are removed.

**What does `market` actually change?**
It sets YouTube's region and interface language for the category page or fallback search, so results lean towards that country instead of a global default.

**Are playlists and albums included, or only videos?**
Category pages that show ranked playlists or albums alongside videos will include them, distinguished by the `type` field (`video`, `playlist`, or `album`); `playlistId` is only present on non-video rows.

**Are live streams included?**
Yes. Live items are flagged with `isLive: true` and usually carry a "LIVE" badge in `badges`.

**Why are fields like `durationText` or `publishedTimeText` missing from some rows?**
Live streams don't have a fixed duration or publish time yet, so those fields are left out of that row rather than filled with a placeholder.

**Is this affiliated with YouTube?**
No. This actor reads YouTube's public pages and is not affiliated with, endorsed by, or sponsored by YouTube or Google.

# Actor input Schema

## `category` (type: `string`):

Which YouTube trending section to scrape. 'Gaming', 'News', and 'Music' work without authentication. 'Now' (main trending feed) and 'Movies' are auth-gated for cookieless requests and automatically use a clearly labeled public search fallback instead of returning nothing.

## `maxResults` (type: `integer`):

Maximum number of trending videos to return. YouTube Gaming typically surfaces 200-400 videos across all shelf sections.

## `market` (type: `string`):

Country/region for localized trending results. Sets the gl URL parameter to target the correct regional trending feed.

## Actor input object example

```json
{
  "category": "gaming",
  "maxResults": 20,
  "market": "US"
}
```

# Actor output Schema

## `videos` (type: `string`):

Dataset containing all scraped ranked trending video rows for the requested category.

# 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 = {
    "category": "gaming",
    "maxResults": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("nimbryxo-studio/youtube-trending-feed-extractor-by-category").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 = {
    "category": "gaming",
    "maxResults": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("nimbryxo-studio/youtube-trending-feed-extractor-by-category").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 '{
  "category": "gaming",
  "maxResults": 20
}' |
apify call nimbryxo-studio/youtube-trending-feed-extractor-by-category --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nimbryxo-studio/youtube-trending-feed-extractor-by-category"
        }
    }
}
```

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/GnLvTq8m3i6444nUe/builds/8MMI1b8gVkx1fXooU/openapi.json