Trending Videos

GET /api/trending

Trending Videos

cURL

curl --request GET \
  --url https://api.example.com/api/trending

200

{
  "results": [
    {
      "id": "<string>",
      "title": "<string>",
      "thumbnail": "<string>",
      "duration": 123,
      "uploader": "<string>",
      "url": "<string>",
      "view_count": 123
    }
  ]
}

Fetch currently trending videos from YouTube.

Query Parameters

max_results · integer · default: "20"

Maximum number of trending videos to return (1-50)

Response

results · array

Array of trending video objects

Show Video Object

id · string

YouTube video ID

title · string

Video title

thumbnail · string

Thumbnail image URL (hqdefault quality)

duration · integer

Video duration in seconds

uploader · string

Channel name or uploader name

url · string

Full YouTube video URL

view_count · integer

Number of views

Example Request

curl -X GET "http://localhost:8001/api/trending?max_results=15"

Example Response

{
  "results": [
    {
      "id": "xyz789abc12",
      "title": "Trending Music Video 2026",
      "thumbnail": "https://i.ytimg.com/vi/xyz789abc12/hqdefault.jpg",
      "duration": 240,
      "uploader": "Popular Artist",
      "url": "https://www.youtube.com/watch?v=xyz789abc12",
      "view_count": 5000000
    },
    {
      "id": "def456ghi78",
      "title": "Viral Comedy Sketch",
      "thumbnail": "https://i.ytimg.com/vi/def456ghi78/hqdefault.jpg",
      "duration": 180,
      "uploader": "Comedy Channel",
      "url": "https://www.youtube.com/watch?v=def456ghi78",
      "view_count": 3200000
    }
  ]
}

Error Responses

500 Internal Server Error

Returned when unable to fetch trending videos.

{
  "detail": "Error obteniendo tendencias: [error message]"
}

Implementation Notes

• Fetches from YouTube’s trending feed (https://www.youtube.com/feed/trending)
• Falls back to popular music search if trending feed is unavailable
• Results are capped at the max_results parameter value
• May vary by region (currently optimized for Spain with global fallback)
• Uses yt-dlp’s extract_flat mode for efficient metadata retrieval