Skip to content
Docs

Similar Videos API

REST API reference for finding YouTube videos related to any target video — endpoint, request body, and response schema for similarity search.

Find YouTube videos related to any target video by content topic and audience interest.

Base URL: https://prod.dashboard.nexlev.io — see Authentication.

Get Similar Videos

POST /api/external/similar-videos/videos

Description: Discover YouTube videos that are similar to a given video using advanced similarity algorithms. Returns a ranked list of videos based on content, topics, and video characteristics.

cURL Example:

curl -X POST https://prod.dashboard.nexlev.io/api/external/similar-videos/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"videoId": "xIL0ssyMh1k"}'

Request Body:

{
  "videoId": "xIL0ssyMh1k"
}

Body Parameters: videoId (required) - YouTube video ID to find similar videos for

Status Code: 200 OK

Description: Returns a list of videos similar to the target video, ranked by relevance. Each result includes video information, channel details, view count, and metadata about the video's performance and characteristics.

Response Body:

[
  {
    "title": "Complete Guide to Content Creation in 2024",
    "similarity_score": 85,
    "format_score": 92,
    "type": "video",
    "videoId": "aB3cD4eF5gH",
    "channelTitle": "Digital Creators Hub",
    "channelId": "UCxYz123ABC456DEF789GHI",
    "channelThumbnail": [
      {
        "url": "https://yt3.ggpht.com/example-channel-thumb-1/s68-c-k-c0x00ffffff-no-rj",
        "width": 68,
        "height": 68
      }
    ],
    "description": "Learn everything you need to know about creating engaging content in 2024. From planning to execution, this guide covers it all...",
    "viewCount": "145230",
    "publishedTimeText": "3 weeks ago",
    "lengthText": "15:42",
    "thumbnail": [
      {
        "url": "https://i.ytimg.com/vi/aB3cD4eF5gH/hq720.jpg?sqp=-oaymwEcCOgCEMoBSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLExample1",
        "width": 360,
        "height": 202
      },
      {
        "url": "https://i.ytimg.com/vi/aB3cD4eF5gH/hq720.jpg?sqp=-oaymwEcCNAFEJQDSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLExample2",
        "width": 720,
        "height": 404
      }
    ],
    "richThumbnail": [
      {
        "url": "https://i.ytimg.com/an_webp/aB3cD4eF5gH/mqdefault_6s.webp?du=3000&sqp=CMzYu8kG&rs=AOn4CLExample",
        "width": 320,
        "height": 180
      }
    ]
  }
]

Response Fields:

  • title - Video title
  • similarity_score - Similarity score (0-100), higher indicates greater similarity
  • format_score - Format similarity score (0-100)
  • type - Content type (typically "video")
  • videoId - Unique identifier for the video
  • channelTitle - Name of the channel that uploaded the video
  • channelId - Unique identifier for the video's channel
  • channelThumbnail - Array of channel profile image objects
    • url - URL to the channel's profile image
    • width - Width of the channel thumbnail image
    • height - Height of the channel thumbnail image
  • description - Video description/snippet
  • viewCount - Raw view count (numeric string)
  • publishedTimeText - Human-readable text of publish time (e.g., "3 weeks ago")
  • lengthText - Video duration in MM:SS or HH:MM:SS format
  • thumbnail - Array of video thumbnail objects with different sizes
    • url - URL to the video thumbnail
    • width - Width of the thumbnail image
    • height - Height of the thumbnail image
  • richThumbnail - Array of animated/rich thumbnail objects (may be empty)
    • url - URL to the animated thumbnail
    • width - Width of the rich thumbnail
    • height - Height of the rich thumbnail

Error Responses

Status Code: 400 Bad Request

Description: The request was invalid or malformed.

{
  "error": {
    "code": 400,
    "message": "Invalid video ID format",
    "details": "Video ID must be a valid YouTube video identifier"
  }
}

Last updated