Table of Contents

Other APIs

Video Search API 1.2

This API gives you access to all the power of VideoSurf's state of the art, vision assisted video search technology. Search on any topic and retrieve relevant videos, thumbnails, related topics, related people and more.

URL

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

  • query - The query to search for.
    • Required
    • Type: String
    • Example: query=Barack+Obama
  • sort - How to sort the results for your query
    • Optional
    • Type: String
    • Default: rel
    • Possible Values:
      relSort by relevancy (most relevant first)
      popSort by popularity (most popular first)
      dateSort by added date (newest first)
      durDownSort by video duration (longest first)
      durUpSort by video duration (shortest first)
    • Example: sort=pop
  • num_per_page - How many results to return per request
    • Optional
    • Type: Number
    • Default: 10
    • Maximum: 20
    • Example: num_per_page=15
  • page - Which page of the results to return
    • Optional
    • Type: Number
    • Default: 1
    • Minimum: 1
    • Maximum: 20
    • Example: page=3
  • safe_level - The safe-search level. You can optionally choose to show excplicit/adult material in your search results.
    • Optional
    • Type: Number
    • Default: 1
    • Minimum: 1
    • Maximum: 2
    • Possible Values:
      1Non-explicit material only.
      2Include explicit videos in search results
    • Example: safe_level=2
  • 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:
      1Include videos without summaries in the results, this is the default
      0Exclude videos without summaries
    • Example: include_videos_without_summaries=0
  • include_embed_code - Should your results include embed code HTML? Setting this to true (1) will include an embed code HTML in the results returned so you can play the video from the webpage you create. Note that some results may not be embeddable and will not contain the embed_code in the output.
    • Optional
    • Type: Number
    • Default: 0
    • Possible Values:
      1Include embed HTML
      0Exclude embed HTML, this is the default
    • Example: include_embed_code=0
  • refinements - This argument is used to specify which additional metadata about the search you would like VideoSurf to return with your results.
    • Optional
    • Type: String
    • Default: No refinements will be returned by default
    • Possible Values:
      visual_searchReturn information about people that appear in the search results
      content_typesReturn information about the content type buckets that the search results fall into
      categoriesReturn information about the category buckets that the search results fall into
      providersReturn information about the providers that the videos in the results belong to
    • Example: refinements=visual_search,content_types
  • refinement_providers - A comma-delimited list of provider IDs to include in or exclude from the results. Listing a provider ID includes search results from that provider. If a provider ID is listed as its negative, the argument's function is inverted and its results are excluded.
    • Optional
    • Type: String
    • Example: refinement_providers=1,3,5,7,11,13 (Will return results only from providers in this set)
    • Example: refinement_providers=-2,-7,-1,-8 (Will return results from all except providers in this set)
  • refinement_content_types - A comma-delimited list of content type ids to restrict results to. Listing a content type ID includes search results with that content type. If a content type ID is listed as its negative, such results are excluded.
    • Optional
    • Type: String
    • Possible Values:
      4Return only only full episodes
    • Example: refinement_content_types=3,1,4
  • refinement_categories - A comma-delimited list of category IDs to restrict results to. Listing a category ID limits search results to that category. If a category ID is listed as its negative, the argument's results are excluded.
    • Optional
    • Type: String
    • Example: refinement_categories=22,7
  • refinement_seasons - The integer value of the season you wish to restrict the search to.
    • Optional
    • Type: Number
    • Example: refinement_seasons=1
  • refinement_episodes - The integer value of the episode you wish to restrict the search to.
    • Optional
    • Type: Number
    • Example: refinement_episodes=1
  • refinement_shows - A comma-delimited list of show ids or the freebase id to restrict results to.
    • Optional
    • Type: String
    • Possible Values:
      1To restrict the search to a specific VideoSurf show
      freebase:/m/0d68qyTo restrict the search to a specific freebase show
    • Example: refinement_shows=freebase:/m/0d68qy
  • 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:
      jsonJSON 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.
      phpSerialized PHP (more info on serialized php)
    • Example: output_format=php

Output

  • matching_results - Count of the total number of search results matching the provided query and other inputs.
  • videos - 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
    • 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.
  • suggested_searches - A list of other queries that you might want to try that are similar or related to your current query
    • query - The query text
    • url - The VideoSurf search results page for this query
  • refinements - For each type of refinement requested, a mapping associated with the name of the refinement (such as visual_search) will be returned as follows:
    • providers
      • description -
      • items
        • id - The provider ID
        • title - The display name of this provider
        • count - How many videos in the result set came from this provider.
    • content_types
      • description -
      • items
        • id - The content type ID
        • title - The title of this content type
        • count - How many videos in the result are of this content type.
    • categories
      • description -
      • items
        • id - The category ID
        • title - The title of this category
        • count - How many videos in the result set are in this category

Please Log In / Sign Up
X
X

We'd love to hear your feedback!X

Select an option:


Add Comments:

Your Email
(Optional - So we can get back to you)

Cancel
Thanks !

Your feedback is vital to making VideoSurf better.