Search Videos

GET /api/search

Search Videos

cURL

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

200

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

Search for YouTube videos by query or fetch information from a direct URL.

Query Parameters

q · string · required

Search query or YouTube URL. Can be:

• Search keywords (e.g., “python tutorial”)
• Direct YouTube video URL
• YouTube playlist URL

max_results · integer · default: "20"

Maximum number of results to return (1-50)

Response

results · array

Array of video objects matching the search criteria

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

Search by Keywords

curl -X GET "http://localhost:8001/api/search?q=python+tutorial&max_results=10"

Search by URL

curl -X GET "http://localhost:8001/api/search?q=https://www.youtube.com/watch?v=dQw4w9WgXcQ"

Example Response

{
  "results": [
    {
      "id": "dQw4w9WgXcQ",
      "title": "Python Tutorial for Beginners",
      "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg",
      "duration": 3600,
      "uploader": "Tech Academy",
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "view_count": 1500000
    },
    {
      "id": "abc123def45",
      "title": "Advanced Python Programming",
      "thumbnail": "https://i.ytimg.com/vi/abc123def45/hqdefault.jpg",
      "duration": 7200,
      "uploader": "Code Masters",
      "url": "https://www.youtube.com/watch?v=abc123def45",
      "view_count": 850000
    }
  ]
}

Error Responses

400 Bad Request

Returned when the q parameter is missing or empty.

{
  "detail": "El parámetro 'q' es requerido"
}

500 Internal Server Error

Returned when the search operation fails.

{
  "detail": "Error en búsqueda: [error message]"
}

Implementation Notes

• When q starts with http, the endpoint treats it as a direct URL and extracts video info
• For search queries, uses YouTube’s search functionality via yt-dlp
• Results are limited by max_results parameter (default: 20)
• Thumbnail URLs use YouTube’s hqdefault quality for consistent sizing