# YouTube Search

Search YouTube directly for videos, channels, and playlists.

Search YouTube directly for videos, channels, and playlists. Returns a mixed-type result list where each item carries a `type` discriminator. Supports `sort_by=view_count`, fine-grained `upload_date` buckets, and a custom `published_within_days` filter.

### `GET /api/search`

Search everything on YouTube in one call — videos, channels, and playlists in the same result list, each tagged with its `type`.

**Query Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| q | string | Required | — | Search query. |
| type | string | Optional | all | `all`, `video`, `channel`, `playlist`, `movie`. |
| sort_by | string | Optional | relevance | `relevance`, `view_count`, `upload_date`, `rating`. |
| upload_date | string | Optional | all | `all`, `hour`, `today`, `week`, `month`, `year`. |
| duration | string | Optional | all | `short` (<4m), `medium` (4–20m), `long` (>20m). Videos only. |
| published_within_days | integer | Optional | — | Narrow videos to those posted in the last N days. Finer than `upload_date` — use for phrasings like “last 3 days”. Auto-picks the tightest native bucket, fetches a larger batch, and post-filters. |
| limit | integer | Optional | 30 | Max results (1–100). |

**Example Response**

```
{
  "success": true,
  "query": "the rise and fall",
  "limit": 20,
  "estimated_results": 1421503,
  "count": 20,
  "has_more": true,
  "results": [
    {
      "type": "video",
      "video_id": "uSCHW7vAq-s",
      "title": "The Rise and Fall of America's Most Infamous Detective Agency",
      "url": "https://www.youtube.com/watch?v=uSCHW7vAq-s",
      "channel_name": "Wendigang",
      "channel_id": "UCxxxxxxxxxxxxxxxxxxxxxx",
      "published_text": "2 days ago",
      "duration_text": "49:50",
      "duration_seconds": 2990,
      "view_count": 381848,
      "view_count_text": "381,848 views",
      "thumbnail_url": "https://i.ytimg.com/vi/uSCHW7vAq-s/hq720.jpg",
      "description_snippet": "..."
    },
    {
      "type": "channel",
      "channel_id": "UCnwUjPK7dXety-AJ4fNw_RQ",
      "name": "The Paint Explainer",
      "handle": "@ThePaintExplainer",
      "url": "https://www.youtube.com/channel/UCnwUjPK7dXety-AJ4fNw_RQ",
      "subscriber_count": 1840000,
      "subscriber_count_text": "1.84M subscribers",
      "description_snippet": "...",
      "thumbnail_url": "..."
    },
    {
      "type": "playlist",
      "playlist_id": "PLbdSi72ah3puMBGa4eLQMNKn4OqaVPsHF",
      "title": "All Casually Explained",
      "url": "https://www.youtube.com/playlist?list=PLbdSi72ah3puMBGa4eLQMNKn4OqaVPsHF",
      "channel_name": "Casually Explained",
      "channel_id": "UCr3cBLTYmIK9kY0F_OdFWFQ",
      "video_count": 85,
      "video_count_text": "85 videos",
      "thumbnail_url": "..."
    }
  ]
}
```

**Example Request**

```
# Top-viewed "rise and fall" videos posted in the last 3 days
curl -G "https://algrow.online/api/search" \
  -H "Authorization: Bearer algrow_..." \
  --data-urlencode "q=the rise and fall" \
  -d "type=video&sort_by=view_count&published_within_days=3&limit=20"
```

200 Success 401 Auth failed 500 Server error