Related Video API 1.2

This API lets you retrieve related videos for a given video, broken down into various types.

URL

• The URL where you can access this API looks like:
  http://apis.videosurf.com/related_videos/v1.2/?id=60467075

Authentication

• Each use of any VideoSurf API is subject to the Terms Of Use and requires you to provide a valid client_id and client_key
• client_id - A human readable client identifier. Please pick something short and descriptive.
  • Required
  • Type: String
  • Example: client_id=your_domain
• client_key - This is an authorization token issued to you by VideoSurf. Obtain one here.
  • Required
  • Type: String
  • Example: client_key=900d77b8e40e60f0113dccc2973f2ed1

Inputs

• id - A VideoSurf video id.
  • Required
  • Type: String
  • Example: id=60467075
• visual_summary_size - The maximum number of thumbnails (per video) to return information for in the VideoSurf visual summary. Note that you will always receive information about the sprite that contains the top 12 most interesting frames in the video's summary. This argument specifies which frames you would like to receive more detailed information about. Each set of frame information includes a number indicating where it is found in the sprite so that you can display it correctly. The frames will be sorted by time. It is important to specify the correct count here so that you will be able to properly display the N most important thumbnails, as decided by our algorithms.
  • Optional
  • Type: Number
  • Default: 8
  • Maximum: 12
  • Example: visual_summary_size=12
• include_videos_without_summaries - Should your results include videos for which VideoSurf has not yet generated a visual video summary? Setting this to true (1) will improve the breadth of the results returned to you, but some of those results may contain an empty visual_video_summary in the output. You will still recieve a title, description, thumbnail and various other information about the video.
  • Optional
  • Type: Number
  • Default: 1
  • Maximum: 1
  • Possible Values:

    1	Include videos without summaries in the results, this is the default
    0	Exclude videos without summaries

  • Example: include_videos_without_summaries=0
• callback - An optional callback function to wrap the response. This is useful for client side scripting with a technique called JSONP. This will only be utilized if the output_format is json.
  • Optional
  • Type: String
  • Example: callback=my_fn - This will result in a response that looks like this: my_fn({ json goes here });
• output_format - Format of the response, either as a JSON object or serialized PHP.
  • Optional
  • Type: String
  • Default: json
  • Possible Values:

    json	JSON object (more info on json). You can also optionally specify &json_ctype_explicit=1 if you would like the json output to have the content type of application/json. By default it is text/html to aid in debugging in the browser.
    php	Serialized PHP (more info on serialized php)

  • Example: output_format=php

Output

• Related Videos Groups - A dictionary mapping each video group title to the list of videos in it. i.e. 'People who watched this video also watched' or 'Related from source site'
  • Group Name - Each video has the following information:
    • video_id - A unique ID identifying this video in the VideoSurf index.
    • title - Title of the video.
    • description - Text description of the video.
    • url - URL of the VideoSurf video page.
    • thumbnail - URL of the default VideoSurf thumbnail for this video.
    • length - Duration of the video in seconds.
    • length_display - Display the length in a more readable min:sec format.
    • date_added - A unix timestamp indicating when VideoSurf indexed this video.
    • date_added_display - A human readable display name for the date_added.
    • is_embeddable - Boolean indicating that this video is available to be embedded.
    • should_open_externally - This is true if VideoSurf can not embed or frame this video, it should be opened directly to the external source url.
    • embed_code - HTML used to embed the video.
    • embed_width - The width of the embed.
    • embed_height - The height of the embed.
    • source - Display name of the provider's site. (e.g. Hulu, Youtube)
    • source_id - VideoSurf's id for the provider's site. (e.g. Hulu=14, Youtube=2)
    • source_url - URL of the video on the provider's site.
    • source_video_id - The provider's ID for this video.
    • tags - Array containing tags assigned by the provider's site.
    • duplicate_video_ids - A list of video ids that our system has identified as duplicates of this video
    • content_type - An array of information about this video's content type if it has been assigned one.
      • id - The content type id
      • title - The title of this content type. i.e. 'Full Episode'
    • season - If this video is related to a specific season of a TV show, the season number will be here
    • episode - If this video is related to a specific episode of a TV show, the episode number will be there
    • related_entities - An array containing entities related to the video. An entity may be a person, TV show or other related topic.
      • entity_id - The entity ID.
      • thumbnail - URL of the thumbnail representing the topic.
      • title - The name of this topic
      • url - URL of the topic page.
      • is_person - Boolean indicating whether or not this topic is a person.
    • visual_video_summary - The visual summary for the video as a mapping structured as follows:
      • frames - An array of frame information in the size requested with visual_summary_size. This array may be empty if a video has not yet been visually indexed by VideoSurf.
        • sprite_position - The position of this frame in the sprite. Position 0 is the left most image in the sprite, position 5 is 6th from the left, etc.
        • time - The time point in seconds where the thumbnail was taken from the video.
        • time_display - A friendlier display version of the time in seconds for this frame.
        • url - The VideoSurf URL that jumps to the video at the moment the thumbnail was captured. The provider must support this functionality. If the provider does not, these URLs will be the same as the url variable at the top level of this video's mapping.
        • face_detected - Boolean indicating whether or not a face was detected in this frame.
      • sprites - Two images, one small, one large. Each contains the top 12 most interesting thumbnails for this video as selected by VideoSurf's algorithms. When displaying VideoSurf visual summaries, you must use these sprites as we do not provide the individual thumbnails. This approach will dramatically reduce page load time for your users. For more information about sprites and how to work with them, please see http://www.alistapart.com/articles/sprites/ and our API usage examples for more information.
        • 64x48 - The URL of a sprite image containing thumbnails of size 64x48.
        • 160x120 - The URL of a sprite image containing thumbnails of size 160x120.