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):


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.


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.


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:


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_keyRequired; contact us for a key at licensing [at] lumerias.com
queryRequired; the query string
pagePagination offset, starting with 1; defaults to 1
pagesizePagination page size; setable between 1-100; defaults to 25
do_spellcheckSpellcheck is currently only triggered on result-sets with less than 3 results; this switch forces spellching; defaults to 0
do_facetsWhether facets (grouping by video sources) should be computed or not; defaults to 0
do_data_urisExperimental: 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.
prettySet 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:

queryMirrors the input query-string
query_no_filtersThe input query-string with all filter-syntax removed
cntOverallNumber of total results
cntPagesThe number of pages it requires to display all results, given the current pagesize
pagesizeCurrent pagesize
timeSearchThe time in seconds the raw search took
timePostProcessingThe time post-processing results took
timeElapsedThe overall time it took the API to fulfill the query
spellcheckIf 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:

countResult-set position of this result; starts with 1, continued on subsequent pages
idA local/ internal alpha-numerical id identifying the result/ entry on Lumerias
titleTitle of the video
descriptionThe video's caption/ descriptive text
runtimeThe video's runtime/ duration in total seconds
runtime_formattedThe video's runtime in human-readable formatted form [hh:]mm:ss
userIf the remote site has the notion of user-accounts/ user-names, this is set
user_urlThe URL of the user's remote account
user_img_urlThe URL of the user's remote account image
user_url_ourThe local/ virtual URL listing all videos of this remote user
siteNice name of the remote site, as used by the remote service, probably without www. or .com
site_faviconURL of the remote site's favicon