| REST Search Services
|
||||||||||||||||||||||||||||
|
||||||||||||||||||||||||||||
HTTP Status Operation State Body Element Body Type Description 200 Success rss RSS Type Returns a page of the feed containing Asset information. 403 Failure The Account is suspended for downloads. 404 Failure The Application or Asset is unknown, or the URI used to access the service is incorrect. 500 Failure fqzat:f GUID Type An unrecoverable server side error has occurred. Returns the ID of the fault. If you require additional information regarding the nature of the error, send the ID returned to Fliqz for clarification.
Get Meta Data for an Asset
http://services.fliqz.com/assets/20090819/AssetSearch.svc/{asset ID}/applications/{application ID}
Where {asset ID} = the id of the target video, {application ID} = the Application ID provided to you by VBOSSREST Related Video Search Service
http://services.fliqz.com/assets/20090819/AssetSearch.svc/{asset ID}/applications/{application ID}/related/?n={page number}
Returns a collection of one or more Media Assets related to a Media Asset identified by an ID.
Where the ID identifies a single Media Asset, a Collection of similar Media Assets is returned. The Title of the Asset is parsed and a search is performed using each word found in the Title as Search criteria. The scope of the search includes all Assets in the Account containing one or more words from the Title in any of the following fields: Title, Description or Keywords.
The REST Video Search Service uses the HTTP GET Method to request search results from Fliqz REST Search Services.
Parameter Name Min Max Type Description asset ID 1 1 GUID Type The ID of the Asset. application ID 0 1 GUID Type The Application ID provided to you by Fliqz. page number 0 1 xs:int The page number to return. The default value is 1.
| HTTP Status | Operation State | Body Element | Body Type | Description |
|---|---|---|---|---|
| 200 | Success | rss | RSS Type | Returns a page of the feed containing Asset information. |
| 403 | Failure | The Account is suspended for downloads. | ||
| 404 | Failure | The Application or Asset is unknown, the URI used to access the service is incorrect, the page number parameter is less than 1, or the page number parameter is greater than the maximum number of pages. | ||
| 500 | Failure | fqzat:f | GUID Type | An unrecoverable server side error has occurred. Returns the ID of the fault. |
http://services.fliqz.com/assets/20090819/AssetSearch.svc/applications/{application ID}/?q=
The REST Video Search Service uses the HTTP GET Method to request search results from VBOSS REST Search Services.
q={query}
The main query selects Assets whose title, description or keywords contain any of the words or phrases within the expression. Phrases are enclosed within double quotes - for example Dog Cat "San Diego" returns assets with dog or cat or San Diego in the fields included in the search.
The following operators are also available:
- excludes words or phrases - for example, Dog Cat -Kitten returns assets with dog OR cat in the title or description but not kitten.
+ guarantees words or phrases - for example, Dog Cat +"San Diego" returns assets with either ((dog OR cat) AND San Diego) in the fields.
Note: The expression MUST be URL encoded.
Search for "alice", "fred" or "chester" and not "puppy"
- Search query: alice fred chester -puppy
- Encoded query: alice%20fred%20chester%20-puppy
http://services.fliqz.com/assets/20090819/AssetSearch.svc/applications/{application ID}/?q=alice%20fred%20chester%20-puppy
Search for phrase "secret santa"
- Search query: "secret santa"
- Encoded query: %22secret%20santa%22
http://services.fliqz.com/assets/20090819/AssetSearch.svc/applications/{application ID}/?q=%22secret%20santa%22
f={fields}
The query allows the targets for the search to be defined. The options are:
- All: The title, description and keywords fields are targeted in the search.
- Keywords: Only the keywords field is targeted in the search.
- Title and Description: The title and description fields are targeted in the search but not the keywords field.
An enumeration of the different types of asset information included in the search by query search.
Enumeration Value Description all The title, description and keywords information is all searched. keywords Only the keywords information is searched. titledescription The title and description information is searched.
All fields (Title, Description and Keywords)
http://services.fliqz.com/assets/20090819/AssetSearch.svc/applications/{application ID}/?q={query}&f=all
keywords (Only the keywords information is searched)
http://services.fliqz.com/assets/20090819/AssetSearch.svc/applications/{application ID}/?q={query}&f=keywords
{categoryName}={value}
Categories are available only in Gold Accounts. Categories are Meta-Data name-value pairs that you can associate with your assets. These name-value pairs can be pre-set using the configurable uploader, and/or assigned programmatically in the basic and http post uploaders.
Category query expressions are applied to named metadata categories and select assets which contain the word or phrase in the query expression. Phrases are enclosed within double quotes - for example Dog Cat "San Diego" returns assets with dog or cat or San Diego in the appropriate category.
Category queries modify the results returned from the main query, if included. Only those assets meeting the main query expression and ALL of the category query expressions are returned.
Note: The expression MUST be URL encoded.
Search for the "Channel" category with values of "6", "9" or "42"
If you have established a name-value pair for assets in your account with Name = "Channel", having values of 6, 9, or 42.
- Search query: &Channel=6&Channel=9&Channel=42
- Encoded query: &Channel=6&Channel=9&Channel=42
http://services.fliqz.com/assets/20090819/AssetSearch.svc/applications/{application ID}/?q={query}&f={target Fields}&Channel=6&Channel=9&Channel=42
o={sort order}
An enumeration of the ways that the results are sorted.
Enumeration Value Description title Ordered by title, in descending alphabetical order (Apple comes before Zone). date Ordered by upload date, in descending order (the most recently uploaded first). rating Ordered by rating, in descending rating order (highest rating first). use Ordered by the number of times that an asset has been displayed, in descending order (most frequently displayed first). share Ordered is ordered by the number of times that an asset has been shared, in descending order (most frequently shared first). Note: The secondary sort order is always upload date (i.e. if items sharing the same rating are ordered by upload date)
Sort by Title
http://services.fliqz.com/assets/20090819/AssetSearch.svc/applications/{application ID}/?q={query}&f={target Fields}&o=title
Sort by date
http://services.fliqz.com/assets/20090819/AssetSearch.svc/applications/{application ID}/?q={query}&f={target Fields}&o=date
A 32-character hexadecimal string in the following form:
0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}
Search Results
Search Results are returned in the form of an MRSS XML Feed. The contents of this feed are as follows:
Attribute Name Min Max Type Description version 1 1 "2.0" The RSS version supported. Element Name Min Max Type Description channel 1 1 Channel Type Contains information concerning the channel.
Element Name Min Max Type Description title 0 1 xs:string The name of the channel. description 0 1 xs:string A phrase or sentence describing the channel. link 0 1 xs:anyURI The URL to search results for the requested page. a10:link 1 6 Link Type Identifies links to the search results for current page, next page, last page, previous page. Link information included in feeds sourced from Fliqz allows enumeration across the asset information in pages. These links are provided to assist with navigation. (see Link Type Description for Details) fzat:pages 0 1 xs:int The number of pages of results returned. The default value is 1. fzat:itemTotal 0 1 xs:int The total number of items returned in the results. item 0 unlimited Item Type A media asset. (See Item Type Description for Details)
Attribute Name Min Max Type Description href 1 1 xs:string The URI of the resource. rel 1 1 Link Relationship Value The link relationship type. Fliqz uses the relationships defined in the Feed Paging and Archiving standard. (See Link Relationship Values for Details) The results always contain a link element with a relationship type of self.
Not all result pages contain a10:link_ elements for all relationship types.
For example, search result which are contained in a single page contain no a10:link_ navigation elements, the first search result page does not contain _a10:link_ elements defining the _first_ and _previous_ relationship types
Enumeration Value Description first The link's href attribute contains the URI of the first page of the search results. last The link's href attribute contains the URI of the last page of the search results. previous The link's href attribute contains the URI of the previous page of the search results. next The link's href attribute contains the URI of the next page of the search results. self The URL in the href attribute refers to the current document.
Element Name Min Max Type Description title 0 1 xs:string The title of the Asset. description 0 1 xs:string The description of the Asset. guid 1 1 RSS GUID Type A unique identifier of the Asset, the Asset ID. (See RSS GUID Type Type for details) pubDate 1 1 Date The date and time when the Asset was uploaded. link 1 1 xs:anyURI The URL of the Asset. In this case the permalink. category 0 unlimited Category Type Metadata Category information. An element is included for each Category Name / Value Pair associated with the Asset. (See Category Type for details) media:content 1 1 Content Type Contains more detailed information concerning the Asset. The value of the element is the category value associated with the Asset. (See Content Type for details)
The content of the element is a GUID
Attribute Name Min Max Type Description isPermaLink 1 1 xs:boolean A flag which identifies if the GUID is a permalink. This value is always set to 'false'.
Categories are name-value pairs that can be set via the HTTP POST and Basic Uploader implemented with a GOLD Account Plan.
Attribute Name Min Max Type Description domain 0 1 xs:string The URI that identifies the categorization domain. Value 0 1 xs:string The value assigned to the Category:Domain Name The domain URI is of the following form:
urn:fliqz:ast:s:20090819:{category name}
where category name is the name of the category registered at Fliqz.
Note: keywords are returned as a category domain(name) - value pair.
The value returned corresponds to the Category Domain. Each Category Domain (or Category Name) can have one corresponding value.
Attribute Name Min Max Type Description duration 0 1 xs:string The duration of the Asset in seconds. medium 1 1 Medium Value The medium type of the Asset. (see list of available Medium Value for details) fzat:state 1 1 Asset State Value The state of the Asset. (see list of available Asset State Value for details) fzat:approved 0 1 xs:boolean A flag indicating that the Asset is approved. The default value is true.
Element Name Min Max Type Description media:player 1 1 Player Type Provides access to the application used to display the Asset. (see Player Type for details) media:thumbnail 0 unlimited Thumbnail Type A preview of the Asset. All available previews are included. (see Thumbnail Type for details) media:keywords 0 1 xs:string The collection of comma-delimited keywords associated with the Asset. fzat:metrics 1 1 Metrics Type Fliqz derived metrics concerning the Asset. (see Metrics Type for details) fzat:behavior 0 1 Behavior Type Fliqz derived behavior concerning the Asset. (see Behavior Type for details) fzat:embed 1 1 xs:string The embed code to deliver the Asset using the Application identified in the request. An enumeration of the types of assets.
Enumeration Value Description audio An audio file. video A video. An enumeration of the state of assets.
Enumeration Value Description published The Asset was accepted, processed, approved and is ready to be played. processed The Asset was accepted and processed but is not yet approved for audience consumption. processing The Asset was accepted and is being processed. failed The Asset was accepted but could not be processed. deleted The Asset was deleted. suspended The Asset was accepted, processed, approved and is ready for audience consumption. However, your Account has been suspended for downloads. blocked The Asset was accepted and processed but was not approved for audience consumption. Provides access to the asset through a player.
Attribute Name Min Max Type Description url 1 1 xs:anyURI The URL of the player, including the query parameters necessary to play the asset. height 1 1 xs:int The height of the player in pixels. width 1 1 xs:int The width of the player in pixels. Contains information referring to a Preview Thumbnail Image for the media file. A Preview Thumbnail is a snapshot image of the Asset.
Attribute Name Min Max Type Description url 1 1 xs:anyURI The URL of the Preview Thumbnail. width 0 1 xs:int The width of the Preview Thumbnail in pixels. height 0 1 xs:int The height of the Preview Thumbnail in pixels. time 0 1 NTP The time index of the Preview Thumbnail. fzat:isDefault 1 1 xs:boolean A flag indicating that this is the default Preview Thumbnail. Contains VBOSS derived metrics concerning the asset.
Attribute Name Min Max Type Description plays 1 1 xs:int The number of times that the Asset has been played. rating 0 1 xs:double A rating value for the Asset between 0 and 5 where 5 is the highest rating. votes 0 1 xs:int The number of votes included in the rating. shares 0 1 xs:int The number of times that the Asset has been shared. Contains VBOSS derived behavior concerning the asset.
Attribute Name Min Max Type Description play 0 1 xs:boolean The Asset is played automatically by the display application. The default value is false. mute 0 1 xs:boolean The Asset sound is muted automatically. The default value is false. Sample MRSS XML Result
<<?xml version="1.0" encoding="utf-8"?> <rss version="2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:fzat="urn:fliqz:ast:s:20090819" xmlns:a10="http://www.w3.org/2005/Atom" xmlns:media="http://search.yahoo.com/mrss/"> <channel> <title>Results</title> <description>Description</description> <link>http://services.fliqz.com/assets/20090819/AssetSearch.svc/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/</link> <pubDate>Thu, 17 Dec 2009 13:09:31 -0800</pubDate> <lastBuildDate>Thu, 17 Dec 2009 13:09:31 -0800</lastBuildDate> <a10:link href="http://services.fliqz.com/assets/20090819/AssetSearch.svc/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/?n=1" rel="self"/> <fzat:pages>1</fzat:pages> <fzat:itemTotal>1</fzat:itemTotal> <item> <title>Mia and Mosi</title> <description>Mia and Mosi playing<description/> <guid isPermaLink="false">xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</guid> <link>http://www.fliqz.com/aspx/permalink.aspx?vid= xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</link> <category domain="urn:fliqz:ast:s:20090819:Channel">9</category> <category domain="urn:fliqz:ast:s:20090819:Subject">Kids</category> <pubDate>Tue, 21 Oct 2008 16:54:33 -0700</pubDate> <media:content fzat:state="published" fzat:approved="true" duration="42" medium="video"><fzat:metrics plays="6" ratings="-1" votes="0" shares="0"/> <fzat:behavior play="false" mute="false"/> <fzat:embed><embed name="player" src="http://applications.fliqz.com/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.swf" width="450" height="392" allowFullScreen="true" wmode="transparent" AllowScriptAccess="always" type="application/x-shockwave-flash" pluginspage="http://www.macromedia.com/go/getflashplayer" ></embed></fzat:embed> <media:player url="http://staging.applications.fliqz.com/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.swf" height="450" width="450"/> <media:thumbnail url="http://previews.fliqz.com/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.jpg?a= xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" height="392" width="450" time="0" fzat:isDefault="true"/> <media:thumbnail url="http://images.fliqz.com/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.jpg" height="392" width="450" time="0" fzat:isDefault="false"/> </media:content> </item> </channel> </rss>Note: The IDs in above example have been obfuscated with "xxxx". Normally, you would see the GUID assigned to the asset in question.
You may use whatever means you prefer for parsing the RSS XML feed that the Fliqz Rest Search Service returns.
The feed follows the MRSS extensions to the RSS Enclosures. VBOSS incorporates their own Namespace to encompass metadata specific to the VBOSS solution. Fliqz namespace enclosures are typically prefixed by "fzat:".
- You must URL encode your query to a format that is understood by "System.Uri.UnescapeDataString" in the .NET Framework. In practical terms this means that the '+' symbol cannot be used to signify a space (' ') and you must use '%20' instead. In the PHP realm, you must use the rawurlencode() function instead of the urlencode() function.
- Query strings cannot be empty, they must include at least one character.
