APIs > Commercial API

The commercial API allows partnering services to leverage Lumerias' video-centric vertical search-infrastructure by offering result-sets in a number of machine-readable formats.

Response Formats

Responses always return the same data in all offered formats. Lumerias currently serves two popular response formats (additional formats can be set-up upon request):

JSON

Our JSON is compiled with Perl JSON::XS, served as UTF-8 and in an un-indented (non-pretty-printed) canonical JSON form. That should make your parsing easier, and makes it potentially directly usable in JavaScript and many other languages. For example, in PHP, just call json_decode() on the data to import it programmatically into your app's scope.

XML

Mostly a bit more verbose, the XML version of our data is a simple XML format that should be easy for you to parse. On our end, we use Perl to generate XML, which you can then parse on your end with Perl's XML::Simple or SimpleXML in PHP for example. The data is always UTF-8.

Requests

Our APIs are architecturally designed with a REST mindset. That means, the url represents the method while arguments to that method are POSTed as form-encoded data or directly appended to the url as url-parameters.

Use UTF-8 encoding when sending arguments to API methods.

Search Request

Doing searches, or asking for result-sets, is the main functionality of the commercial API. Think of it as normal Lumerias video search requests, only with the cover peeled off: the data only without the decoration.

With the requested format appended as suffix, a request to the search API can look like this:

https://www.lumerias.com/api/search.json

The search method accepts GET and POST requests for JSON and XML responses. For now, post'ing JSON or XML as the request body/content is not supported. Accepted request parameters are (unknown keys are silently ignored):

api_key	Required; contact us for a key at licensing [at] lumerias.com
query	Required; the query string
page	Pagination offset, starting with 1; defaults to 1
pagesize	Pagination page size; setable between 1-100; defaults to 25
do_spellcheck	Spellcheck is currently only triggered on result-sets with less than 3 results; this switch forces spellching; defaults to 0
do_facets	Whether facets (grouping by video sources) should be computed or not; defaults to 0
do_data_uris	Experimental: embed the actual binary thumbnail-images as base64 encoded data into the textual result-set response, which may slow-down responses; default 0; max. data-uris per page is currently 15.
pretty	Set this to true for debugging; JSON only, pretty-printing of output; default 0

The response is a hash containing the keys 'results' and 'meta', each pointing to a sub-data-structure holding more data. On successful requests, the 'meta'-hashref provides global information about the 'results'-arrayref. On invalid requests, or if there's some other problem with your query, the 'meta'-hash will hold an error key with details about the error as its value. An example response can look like this:

{
   "meta" : {
      "query" : "test",
      "timeSearch" : "0.12915",
      "timePostProcessing" : "0.22055",
      "timeElapsed" : "0.34970",
      "cntPages" : 12992,
      "pagesize" : 25,
      "cntOverall" : 324788,
      "query_no_filters" : "test"
   },
   "results" : [
      {
         "thumbnail_data" : null,
         "url" : "http://www.example.com/video/abc123",
         "user" : "Some User",
         "redir_enc_url" : "/lrd?v=KAD95lCbKgGzzrIbHFRYEiY",
         "user_img_url" : null,
         "id" : "0-10192222",
         "user_url_our" : "/search/user/Some%20User",
         "link" : "/video/test-example-video-0-10192222",
         "count" : "1",
         "thumbnail_url" : "http://s1.example.com/thumbs/version1.jpg",
         "user_url" : "http://www.example.com/Some_User",
         "runtime_formatted" : "01:10",
         "description" : "An example videos",
         "site" : "ExampleTube",
         "runtime" : "70",
         "site_favicon" : "http://www.example.com/favicon.ico",
         "title" : "Example"
      },
   ...
   ]
}
			

Key-value pairs in the 'meta'-hash of reponses have the following meaning:

query	Mirrors the input query-string
query_no_filters	The input query-string with all filter-syntax removed
cntOverall	Number of total results
cntPages	The number of pages it requires to display all results, given the current pagesize
pagesize	Current pagesize
timeSearch	The time in seconds the raw search took
timePostProcessing	The time post-processing results took
timeElapsed	The overall time it took the API to fulfill the query
spellcheck	If this key is set, it contains a hashref with global and per-token spellcheck results

The 'results'-array is made up of list-items, each representing one search "hit", which in turn is represented by a hash of key-value pairs. These key-value pairs have the following meaning:

count	Result-set position of this result; starts with 1, continued on subsequent pages
id	A local/ internal alpha-numerical id identifying the result/ entry on Lumerias
title	Title of the video
description	The video's caption/ descriptive text
runtime	The video's runtime/ duration in total seconds
runtime_formatted	The video's runtime in human-readable formatted form [hh:]mm:ss
user	If the remote site has the notion of user-accounts/ user-names, this is set
user_url	The URL of the user's remote account
user_img_url	The URL of the user's remote account image
user_url_our	The local/ virtual URL listing all videos of this remote user
site	Nice name of the remote site, as used by the remote service, probably without www. or .com
site_favicon	URL of the remote site's favicon