Author: Bill
We launched the new justin.tv search engine a few days ago. Now I'm excited to announce that it has an API you can use in your own programs.
We've based the API on some very familiar open standards - basically HTTP and JSON, so using it should be a piece of cake from just about any language. To see an example in Common Lisp, scroll to the end of this post.
To use our search API, you just need to send an HTTP request to http://search.justin.tv:6979/ with a bunch of parameters. Here's a complete list of the parameters that are available right now:
| q | The search query (required). Keywords are separated by url-encoded spaces ('+' or '%20'). Anything non-alphanumeric is ignored. |
| sort-by | One of 'bestmatch' (default), 'newest', 'oldest', 'mostviews'. |
| page | Page number in results set, default 1. |
| results-per-page | Maximum 100, minimum 10, default 10. |
| show-archives | Return video archives. 'yes', 'true', 'on' all do the same thing. |
| show-live-broadcasters | Return users who are currently broadcasting. 'yes', 'true', 'on' all do the same thing. |
| show-offline-broadcasters | Return users who are not currently broadcasting. 'yes', 'true', 'on' all do the same thing. |
| If none of the above three are specified, they are all assumed to be 'true'. |
| broadcasters | Only return results from a list of named broadcasters, e.g. 'b1,b2,b3'. |
| encode-as | One of 'html-fragment' (default), 'html-page', 'json'. |
So let's say we want to build a small application, using the search api, that alerts us whenever a new video clip is available that has something to do with cats. Here's a query that would be a good starting point for an application like that:
?q=cat&sort-by=newest&show-archives=true&encode-as=json
Let's pull that apart and look at what each piece does.
q=cat | We're interested in search results whose metadata contain the word "cat". |
sort-by=newest | We want the most recently produced results. |
show-archives=true | We do want video archives in our results. Note that show-live-broadcasters and show-offline-broadcasters will both default to 'false' because we've set show-archives to 'true'. |
encode-as=json | The results set should be encoded using json. |
Let's send that query to search.justin.tv and see what we get back:
http://search.justin.tv:6979/?q=cat&sortby=newest&show-archives=true&encode-as=json
returns:
[{"type": "video_archive", "broadcaster": "ggjeffy", "id": 28144, "title": "Cat doing cat stuffs", "start_time": 1186542932, "duration": 180}, {"type": "video_archive", "broadcaster": "nekomimi_lisa", "id": 39175, "title": "Nekomimi Cat Doing The Cat Dance", "start_time": 1191805139, "duration": 108}, {"type": "video_archive", "broadcaster": "nekomimi_lisa2", "id": 9832, "title": "CAT FIGHT!!", "start_time": 1185954224, "duration": 180}, {"type": "video_archive", "broadcaster": "nekomimi_lisa2", "id": 9818, "title": "cat trying to hump blanket", "start_time": 1185939617, "duration": 180}, {"type": "video_archive", "broadcaster": "ashleymarie", "id": 36553, "title": "Sister Cat Fight Part 1", "start_time": 1190060150, "duration": 80}, {"type": "video_archive", "broadcaster": "ibrbigottopee", "id": 34698, "title": "I thought i saw a putty cat", "start_time": 1189149636, "duration": 66}, {"type": "video_archive", "broadcaster": "ashleymarie", "id": 36555, "title": "Sister Cat Fight Part 2", "start_time": 1190060349, "duration": 66}, {"type": "video_archive", "broadcaster": "audratv", "id": 39679, "title": "Attack of the Fuzzy Cat Part 2", "start_time": 1191985459, "duration": 180}, {"type": "video_archive", "broadcaster": "audratv", "id": 39656, "title": "Cat Attack", "start_time": 1191980666, "duration": 180}, {"type": "video_archive", "broadcaster": "xk3ll3yx", "id": 40879, "title": "Cat on Head!", "start_time": 1192431728, "duration": 71}]
Now we need to decode that blob of json. Fortunately there's a library to do that for every language under the sun (look on the json page for yours).
So let's see how we would start writing that feline-video-feed in my favorite language, Common Lisp. First we need libraries for doing the http request and the json decoding. trivial-http and cl-json are more than good enough:
(require :trivial-http)
(require :json)Let's write a "find-cats" function, which will send the http request and return the results as a string:
(defparameter *url*
"http://search.justin.tv:6979/?q=cat&sort-by=newest&show-archives=true&encode-as=json")
(defun find-cats ()
(let ((stream (first (last (trivial-http:http-get *url*))))
(json nil)
(line nil))
(loop while (setf line (read-line stream nil nil)) do
(push line json))
(apply #'concatenate 'string (nreverse json))))
Now we just need to call that function periodically, parse the json, and print any new cat videos:
(defun cats-alert ()
(let ((known-cat-videos (make-hash-table :test #'equalp)))
(loop
(let ((cats (json:decode-json-from-string (find-cats))))
(dolist (cat cats)
(unless (gethash cat known-cat-videos)
(setf (gethash cat known-cat-videos) t)
(format t "New cat video!~%~A~%http://www.justin.tv/~A/~A~%~%"
(rest (assoc 'title cat))
(rest (assoc 'broadcaster cat))
(rest (assoc 'id cat)))
(force-output))))
(sleep 600))))
That's it, we're done! Here's an example of the program's output:
CL-USER> (cats-alert)
New cat video!
Get the cat butt out of the way!
http://www.justin.tv/fistonet/44923
New cat video!
cat vs dog
http://www.justin.tv/midolgirl/44656
New cat video!
scared cat!
http://www.justin.tv/bobtv/43959
New cat video!
Bob scares the cat! lol
http://www.justin.tv/bobtv/43970
New cat video!
Cat fight. Or something.
http://www.justin.tv/ashleyisawesome/43814
New cat video!
Cat on Head - Part II (With New Web Cam)
http://www.justin.tv/shamrox/43719
New cat video!
Cat fight
http://www.justin.tv/nerdette/42933
New cat video!
Dear cat in the middle of the road, i hate you.
http://www.justin.tv/icantstopiwontstop/42878
New cat video!
Jasmine Playing... (& the amazing flying cat-jumps) TOO CUTE!
http://www.justin.tv/lizzymayhem/42798
New cat video!
KT, the cat, running around acting strange, then craps on the floor
http://www.justin.tv/nekomimi_lisa/43225
We can't wait to see what you do with the APIs we're developing. Email me (bill at justin dot tv) if you have something cool to show off, or if you have any questions or comments.
