Video Search API 1.1

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

• The URL where you can access this API looks like:
  http://apis.videosurf.com/video_search/v1.1/?query=Barack+Obama

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:

    rel	Sort by relevancy (most relevant first)
    pop	Sort by popularity (most popular first)
    date	Sort by added date (newest first)
    durDown	Sort by video duration (longest first)
    durUp	Sort 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:

    1	Non-explicit material only.
    2	Include 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 20 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: 20
  • Example: visual_summary_size=12
• 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_search	Return information about people that appear in the search results
    content_types	Return information about the content type buckets that the search results fall into
    categories	Return information about the category buckets that the search results fall into
    providers	Return 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_visual_search - A visual search topic ID to limit the results to. This is a person who you would like to see appearances of. Note that you may only enter one topic ID and it must be a person.
  • Optional
  • Type: Number
  • Example: refinement_visual_search=12345
• 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
  • 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
• 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)
    php	Serialized 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.
  • 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.
      • 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 20 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.
• 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:
  • visual_search
    • id - The topic ID
    • title - The name of the person
    • thumbnail - url for a picture of this person
    • rank - Each person is ranked by their visual importance in the context of the search results for the provided query.
  • providers
    • 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
    • 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
    • id - The category ID
    • title - The title of this category
    • count - How many videos in the result set are in this category