واجهة برمجة الفيديوهات الرائجة على YouTube

#What YouTube Trending solves

youtube/trending gives a live snapshot of the most popular videos per country, optionally focused on a specific YouTube category (e.g., 10 = Music). Use it for landing pages, auto-curated playlists, “Top Today” widgets, and weekly editorial picks.

#Endpoint & when to use it

#POST /v1/youtube/trending — Trending Feed

• Best for: Country dashboards, “New & Hot” rows, music-only charts (category=10).
• Output: Compact list of videos with id, title, channelId/channelTitle, publishedAt, categoryId, durationISO, counts, and a ready-to-use thumb.
• Tip: Cache per country for 5–10 minutes to reduce feed jitter and API costs.

#Quick start

# GB Music — Top 25
curl -X POST "https://api.yeb.to/v1/youtube/trending" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -d '{
    "country":  "GB",
    "category": "10",
    "limit":    25
  }'

# US default — Mixed categories, 12 items
curl -X POST "https://api.yeb.to/v1/youtube/trending" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -d '{ "limit": 12 }'

#Parameters that actually matter

#Reading & acting on responses

{
  "data": {
    "country": "GB",
    "category": "10",
    "cnt_results": 1,
    "videos": [
      {
        "id":           "abc123XYZ",
        "title":        "Top UK Hit 2025",
        "description":  "Official video…",
        "channelId":    "UCmusic",
        "channelTitle": "HitsNow",
        "publishedAt":  "2025-07-06T17:01:02Z",
        "categoryId":   "10",
        "durationISO":  "PT3M12S",
        "viewCount":    4500000,
        "likeCount":    128000,
        "commentCount": 9800,
        "thumb":        "https://i.ytimg.com/vi/abc123XYZ/hqdefault.jpg"
      }
    ]
  }
}

• id — YouTube Video ID. Build links: https://www.youtube.com/watch?v={id}.
• channelId — Channel ID for badges or deep links: https://www.youtube.com/channel/{channelId}.
• thumb — Ready “high” thumbnail. Derive sizes via i.ytimg.com/vi/{id}/….
• durationISO — ISO-8601 (PT#M#S). Convert to mm:ss labels for cards.
• publishedAt — UTC timestamp. Show “NEW” if < 72h old.
• viewCount — Snapshot for social proof; trending is volatile, don’t over-sort by it alone.

#Practical recipes

• Music-only grid: Call with {"country":"DE","category":10,"limit":12}. Render thumb, title, channel, mm:ss, and a small views chip.
• Weekly editorial: Cache by country for 7 days, but refresh every hour to catch breakouts; pin manually selected IDs on top.
• Playlist builder: De-dupe by channelId to avoid stacking multiple uploads from the same channel.
• Edge caching: Key on country + category; TTL 300–600s keeps UIs stable without feeling stale.

#YouTube IDs you’ll work with

#Common YouTube Category IDs

Availability of categories can vary by region; 10 is universally safe for music use-cases.

#Errors & troubleshooting

• 400 "Invalid country code. Use ISO 3166-1 alpha-2 format." — Two uppercase letters (e.g., US, GB).
• 400 "Invalid category. Must be a numeric YouTube category ID." — Provide an integer like 10.
• 502 "YouTube API error: …" — Upstream hiccup. Retry with exponential backoff (1s → 2s → 4s) and respect quotas.

#API Changelog (youtube/trending)