Wednesday, November 7, 2007

JTV Search API

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:




qThe search query (required). Keywords are separated by url-encoded spaces ('+' or '%20'). Anything non-alphanumeric is ignored.
sort-byOne of 'bestmatch' (default), 'newest', 'oldest', 'mostviews'.
pagePage number in results set, default 1.
results-per-pageMaximum 100, minimum 10, default 10.
show-archivesReturn video archives. 'yes', 'true', 'on' all do the same thing.
show-live-broadcastersReturn users who are currently broadcasting. 'yes', 'true', 'on' all do the same thing.
show-offline-broadcastersReturn 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'.
broadcastersOnly return results from a list of named broadcasters, e.g. 'b1,b2,b3'.
encode-asOne 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=catWe're interested in search results whose metadata contain the word "cat".
sort-by=newestWe want the most recently produced results.
show-archives=trueWe 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=jsonThe 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.

37 comments:

rog said...

Good to see some a lisp example.

Just in case someone has problems with trivial-http (it is not maintained anymore), here you can find an example with drakma, trivial-http's replacement

Unknown said...

Hi, I'm having troubles in using the SearchAPI, I copied the http address that was in this post (http://search.justin.tv:6979/?q=cat&sortby=newest&show-archives=true&encode-as=json) to try it out and it doesn't work. I am unable to get the SearchAPI working for me... :S

I just keep getting a Failed to Connect error in Firefox every time.

Is there something wrong with the server? Oo

aio said...

same thing here!
error in firefox

anyone can help us??

Anonymous said...

This post is way out of date. The current search api docs are here.

Anonymous said...

Well I really like the ad and i think there is an immediate need of this among youngsters, It’s a fastidious and instructive. Things are ordered wellspring. acai berry
Best Acne Treatment
acai berry weight loss

Daniel Rusu said...

In case you dolce and gabbana light blue perfume or somebody you realize home security safe is ever charged aided by the crime of driving below home mortgage calculator the affect, the initial thing that you just auto tint must do is tiny bluetooth usb adapter dongle black consult a criminal law firm dual alarm clock radio about the circumstance. lip liners There are a lot of lcd hd tv optimistic things that wine glass racks an experienced prada laptop bag Alameda County DUIwaste compactors lawyer can deliver to a situation. gold necklace With in depth knowledge booster car seat about the law, a attorney may be casio cameras suitable there with you to help defend spouse visas your constitutional rights and freedoms. dvd editing software free

coloncleansehomekits said...

This is really nice post, I found and love this content. I will prefer this, thanks for sharing. intestinal cleanse.

SAFE SITES18 said...

Thanks for sharing this brilliant article it was a very useful and helpful article. 토토사이트

casinositetop 카지노사이트 said...

You make so many great post here. I read your article twice. Its good!
바카라사이트
카지노사이트
온라인카지노
바카라사이트닷컴

casinositeone.JDS said...

Very great post. I just stumbled 카지노사이트 upon your blog and wanted to say that I have truly loved browsing your blog posts.

SAFE SITES18 said...

This blog is very informative the stuff you provide I really enjoyed reading. 바카라사이트

SAFE SITES18 said...

Your way of working is very great and cool. This article is very informative and helpful for a lot of people. Thanks for sharing and keep sharing. 배트맨토토

gostopsite 고스톱사이트 said...

I really enjoy your web’s topic. Very creative and friendly for users. Definitely bookmark this and follow it everyday.
안전카지노사이트

casinosite 카지노사이트존 said...

My incredibly long internet look up has at the end been rewarded with reliable insight to share with my good friends
먹튀검증

trusted sites said...

Thank you, 카지노사이트 I’ve recently been searching for information about this subject for a long time, and yours is a great one that I have discovered so far.

바카라 said...

This is such an outstanding article; 카지노사이트 have appreciated the fact that you took take some good time to work on this very blog.

sports site! said...

This article gives the light in which we can observe the reality. 바카라사이트 This is very nice one and gives indepth information. Thanks for this nice article.

Co SportsToTo 365 said...

I just could not depart your website before suggesting that I actually enjoyed the standard info a person provide for your visitors? Is gonna be back often to check up on new posts

프로야구경기결과
라이브스코어코리아사이트
국내야구

Co PowErBalL siTe said...

You actually make it seem so easy together with your presentation however I find this matter to be actually one thing that I think I’d never understand. It kind of feels too complex and extremely broad for me.

사설토토
파워볼
안전놀이터

Co ToToSaFe Guide said...

obviously like your web-site but you have to check the spelling on quite a few of your posts. Many of them are rife with spelling issues and I find it very troublesome to tell the truth nevertheless I’ll surely come back again.

NBA배당
NBA모자추천
NBA분석느바챔프

lucky me! said...

It’s awesome to pay a visit to this web page and reading the views of all friends regarding this paragraph, while I am also eager of getting experience. 카지노사이트

onlyblog said...

Nice Blog. Thanks for sharing with us. Such amazing information.

Only Blog

Guest Blogger

Guest Blogging Site

Guest Blogging Website

Guest Posting Site

blog-web-com said...

There is evidently a bunch to realize about this. I consider you made some good points in features also.

스포츠
사다리게임
토토사다리타기
배당사이트

slot gacor said...

Easy win online site slot offers you thousands of games from all the best game products. like online slot games. live casino. online poker. sports games. fish pond. and online lottery.

mizasalsa said...

the king slot site as the best quality online bookie and gambling stall will give you big profits in playing games slot online will bring you to the pinnacle of victory in playing online slot games

situs gacor said...

Raja site slot kamboja has thousands of online slot game games from well-known providers that offer and play online slot games, mduah maxwin

johnass said...

thank you for sharing this post! you done great effort
Abogado DUI Manassas VA

situs gacor said...

for those of you who like to play online slot games. The king of gambling site offers you to play speedgaming online slot games which have the highest slot rtp which will make it easier for you to play online slot games, click https://akdizayn.net

mateo said...

Technology Blog is a great resource for staying up-to-date on the latest technology news and trends. The blog posts are well-written and informative, and they cover a wide range of topics, from new gadgets to emerging technologies. I would definitely recommend Technology Blog to anyone who is interested in technology.
contract dispute litigation
lawyer for flsa claim

judasanjoy said...

The 2007/11/jtv-search-api review praises the JTV Search API for its ease of use, comprehensive features, well-documented support, and responsive support team. However, it suggests improvements such as support for more search operators like proximity search and wildcard searches, and more detailed error messages. Despite these criticisms, the reviewer recommends the JTV Search API for its versatility in applications like e-commerce websites, search engines, and content management systems. motorcycle accident attorney

Mybloggerclub said...

Nice Blog. Thanks for sharing with us. Such amazing information.

Why to hire business consultant in Dubai for new startup?

jameshendry said...

The JTV Search API is a revolutionary tool for developers, offering seamless integration and robust search capabilities. Its user-friendly design and comprehensive documentation make implementation easy. The API's speed and accuracy in search results are impressive. Its customizable features and excellent support make it a valuable tool for enhancing search functionalities in various applications.
Orden Protección Civil Nueva Jersey

simon said...

The TV Search API is a powerful tool for developers, offering seamless integration and access to a comprehensive database of television content. Its user-friendly documentation simplifies the implementation process, making it an efficient solution for applications that require TV-related data. The API's robust search functionality and detailed metadata ensure accurate and relevant results for users. With its versatility and ease of use, the TV Search API stands out as a valuable resource for creating innovative and engaging television-related experiences within various applications. Overall, it proves to be a reliable and efficient asset for developers in the realm of TV content.divorcio en las leyes de nueva jersey

martin03481 said...

The code demonstrates how to create a program that alerts users about new cat videos using the Justin.tv search API in Common Lisp. The program makes an HTTP request to the API, parses the JSON response, extracts information about cat videos, and prints out details of new cat videos. The program periodically checks for new videos and alerts the user whenever it finds one. To further enhance the program's functionality, additional lines can be added, such as error handling, logging, user interaction, and throttling requests. These additions will make the program more robust, informative, and user-friendly. Customizing these lines based on specific requirements and preferences is also possible. abogado de derecho de familia

Thomson said...


The JTV Search API offers developers a powerful tool for integrating advanced search functionality into their applications. With robust features and customizable options, this API provides access to a vast database of content. Developers can leverage the JTV Search API to enhance user experiences, streamline information retrieval, and drive engagement. Its user-friendly interface and comprehensive documentation make implementation straightforward and efficient. Explore the possibilities of the JTV Search API and elevate your application's search capabilities to new heights.abogado de planificación patrimonial fairfax va

lucask110198 said...

A powerful tool created to improve and expedite search functions within the JTV platform is the JTV Search API. This API's robust capabilities and user-friendly UI enable developers to easily incorporate thorough search capability into their apps. By providing developers with access to comprehensive product information and sophisticated filtering options, the JTV Search API enables them to provide customers with an enhanced search experience that increases user satisfaction and engagement. For maximizing search capabilities within the JTV ecosystem, this is the go-to solution due to its adaptable customization possibilities and dependable performance.
fatal motorcycle accident in virginia

felipstar2 said...

Outstanding post once again. I am looking forward to more updates.
casinositetop.com