It’s ready and it’s hot. First totally open and free (as in beer and as in freedom) film recommendations API is here for you as a gift from Filmaster. The API enables external programmers to create independent services or apps using our data and algorithms, it allows to easily integrate any website with Filmaster by presenting our content like reviews and film recommendations. Sounds interesting? Read on!

What’s in the API?

The first version of Filmaster API is already pretty complete, i.e. it allows you to do anything that you can do on the website. In particular:
- authenticate using OAuth standard (recommended) or using basic authentication (not recommended),
- rate movies and get access to personalized film recommendations
- search for movies,
- fetch movie reviews,
- list and add new comments to reviews,
- access the interconnections between users (who follows who) and modify it (start following / unfollow),
- access the users’ public film collections (wishlist, personal collections, etc),
- get contextual information about Filmaster users (i.e. list users with the most common taste or list users who are located close to where we live).

There are also some beta features that we have not fully tested, but you are welcome to test them and use them if you are not afraid:
- getting local showtimes
- checking-in to a film screening in a movie theater

And more are coming soon being:
- express recommendations (i.e. rate 10 films and get recommendations immediatelly, without wating for half a day to get them generated),
- show films similar to the selected film (based on a pretty complex algorithm that uses films metadata and users ratings),
- and… many more

Technical stuff

The API has been crafted using the REST standard, i.e. we’re using HTTP protocol, all resources are acessible via URI addresses and each operation (read, write/update, delete) are realized through corresponding HTTP calls (GET, POST/PUT, DELETE). The data is packed in JSON format. All URI addresses in the API start with the API version (currently it’s the 1.0 prefix).

I’m a programmer. What can I do with the API?

Quite a lot! Wiele! As we give you access to almost all the features currently available on Filmaster.com (with some that are still being beta-tested), Filmaster itself is the only limit.

Here are a few ideas though:
- You can create a Filmaster client for your favorite mobile platform. We are committed to iPhone and Android applications. The rest is yours. Want an Palm webOS app? Go for it! Prefer Samsung Bada, Symbian, Meego or even Windows Phone 7? No problemo! Want an app for iPad, Blackbery Playbook or Amazon Kindle? Can’t see a reason why not. Just code it, publish it and let us know. We’ll be very happy to help promoting it!
- Integrate some of the best Filmaster features with your movie website or blog! Allow your users/readers to rate movies and serve them recommendations based on their ratings! Show them the reviews written by Filmaster bloggers, list flim rankings and film synopses. Well… list anything you like as all the content it licensed under Creative Commons Attribution!
- Simply write your own website or app that uses our data. Like an application that rewards people for checking-in to niche cinemas. Or a website that shows two movies and asks users to choose the better one. Or… well…. use your imagination (like the protagonist in The Limits of Control).

Sample app

Mariusz Kryński, the author of the API (written in Python, just like Filmaster) wrote a sample app to show you how the API works in practice.

The app fetches all your Filmaster friends (people you follow). You can choose any of them and then it computes the films that you should watch together. Pretty brilliat for film parties! (obviously you all need to use Filmaster for the app to work).

There is the code of the app. Contrary to the Filmaster code base (which is licensed under Affery GPLv3), this is public domain so you can use it in your application with no restrictions: https://bitbucket.org/mrk/filmaster-api-sample

Mariusz’s test app

License and restrictions

All the user-contributed content (like reviews, opinions) is licensed under Creative Commons Attribution 3.0. This means you can use any of it on your website or app as long as you comply with the license terms.

Using Filmaster API is free and it should stay this way for people. Still, we’d like to keep the possibility to, at some point, start charging a minimal amount of money in case your monthly transfer usage is very high. More clarifications below:

- If you have a blog and you would like to place a widget with your latest film ratings from Filmaster, you can be sure you will be always able to do that. Even if your blog is Cinematical.com (or perhaps especially then).
- If you work for Yahoo! and are planning to integrate Yahoo Movies with Filmaster, give us a ring, just in case, so that we can both benefit from such relationship
- If you are creating a mobile version of Filmaster for iPhone or Android, also let us know. We should not have issues with that (the more competition, the better, especially if all of it uses the Filmaster API) but we’d prefer you created versions for other mobile platforms first, obviously.

In any case, if you decide to start using Filmaster API, please tell us about your project. We’d be very happy to promote it. Just send an e-mail to filmaster@filmaster.com explaining your idea.

Documentation and support

The API is documented on our wiki: http://filmaster.org/display/DEV/API. The contact person for API is Mariusz Kryński, but please e-mail us at dev@filmaster.pl if you need support or advice. We’ll be glad to help!