This is the documentation for the 1.1 version of Filmaster's movie recommendations and reviews API. Read more about the release on our blog: Filmaster unveils movie recommendation API.
The code of the API is licensed under AGPLv3 and you can track it here: https://bitbucket.org/filmaster/filmaster-stable/src/cb9b4d62f8de/film20/api/
Filmaster API, version 1.1
General rules
Filmaster API uses REST architecture.
CRUD - Create, Read, Update, Delete - HTTP request methods
Request method (GET, POST, PUT, DELETE) determines operation you perform on resource specified by URI.
- GET - reading resources
- POST - creating new resources (you POST on resource collection/list URI, as response You will get new object with resource_uri field containging resource URI of new created object. This URI may be used for subsequent edit of object)
- PUT - update resource specified by URI. Resources may also be created using PUT if resource URI is known erlier.
- DELETE - remove resource specified by URI
Production and development APIs
For development and testing (especially testing of POST/PUT/DELETE operations) use these dev hosts:
(currently only Polish dev is deployed)
FILMASTER_HOST: reloaded.filmmaster.pl
FILMASTER_API_HOST: api.reloaded.filmmaster.pl
(note that there are to 'm' letters)
For deploying on production use these hosts
(International version):
FILMASTER_HOST: filmaster.com
FILMASTER_API_HOST: api.filmaster.com
(Polish version):
FILMASTER_HOST: filmaster.pl
FILMASTER_API_HOST: api.filmaster.pl
(one 'm' in filmaster)
API version
Currently there are two API versions: 1.0 (deprecated) and 1.1 (current), so for most cases you need to set:
API_VERSION: 1.1
Input and Output Data encoding
Output response is JSON-encoded (with mimetype application/json).
Input encoding depends of Content-Type request header, supported types: application/x-www-form-urlencoded or application/json
Example - send data using JSON format:
curl -X PUT -u alice:pass http://FILMASTER_API_HOST/API_VERSION/profile/ratings/film/pulp-fiction/1/ \ -H "Content-Type: application/json" -d '{"rating":10}' { "rating": 10, "resource_uri": "/API_VERSION/user/mrk/ratings/film/pulp-fiction/1/", "type": 1, "film_uri": "/API_VERSION/film/pulp-fiction/" }
JSONP output
If request contains 'callback' URL parameter, JSON response will be JSONP-compatible:
curl 'http://FILMASTER_API_HOST/API_VERSION/user/michuk/?callback=response_cb' response_cb({ "website": "http://borys.musielak.eu", "last_name": "Musielak", "date_joined": "2008-10-29 21:35:42", "first_name": "Borys", .... })
jQuery example:
jQuery.getJSON('http://FILMASTER_API_HOST/API_VERSION//user/michuk/?callback=?', null, function(data) {
console.log(data);
})
Authentication
Some resources needs authentication - unautenticated access results with 401 response.
Filmaster API supports OAuth and Basic authentication protocols.
OAuth
Filmaster uses OAuth 1.0a version of OAuth protocol.
Your application needs to be registered at http://FILMASTER_HOST/applications/ (or http://FILMASTER_HOST/aplikacje/ if the locale is Polish), you will get CONSUMER_KEY i CONSUMER_SECRET. In case of desktop application you may leave callback_url empty - after user confirm application access to service, PIN will be shown which may be used as oauth_verifier parameter in application.
OAuth URLS:
- http://FILMASTER_HOST/oauth/request/token/ - request token URL
- http://FILMASTER_HOST/oauth/access/token/ - access token URL
- http://FILMASTER_HOST/oauth/authorize/ - authorization of access token
Basic
Example - fetching profile of authenticated user:
curl --basic -u alice:pass http://FILMASTER_API_HOST/API_VERSION/profile/
Collections of items - pagination
Collections (lists) of items are represented in a unified way, allowing simple pagination of result.
Each collection is represented by object with following fields:
- 'objects' - contains list of items
- 'paginator' - optional field containing paginator object
Example:
curl http://FILMASTER_API_HOST/API_VERSION/user/alice/recommendations/
{
"paginator": {
"next_uri": "/API_VERSION/user/alice/recommendations/?page=2",
"prev_uri":null,
"page": 1
},
"objects": [ {...}, {...} ]
}
paginator fields 'next_uri', 'prev_uri' contains URI of next and previous pages of result (if available). Default number of results on single page is 10, it may be changed using 'limit' request parameter (IMPORTANT - we can limit value of 'limit' parameter to reasonable value, do not expect 1000000 items in response after specifing limit=1000000)
'include' parameter
Using this request parameter you can request some object fields 'on demand'. Value of this parameter is comma-separated list of on-demand fields. Each field is specified as '.' separated path.
Example:
/API_VERSION/user/mrk/filmbasket/ returns objects like:
{
"film_uri": "/API_VERSION/film/the-shining/",
"wishlist": 9,
"owned": 1,
"resource_uri": "/API_VERSION/user/mrk/filmbasket/the-shining/"
}
with following include: /API_VERSION/user/mrk/filmbasket/?include=film,film.guess_rating
{
"film": {
"permalink": ....
"guess_rating": ...
},
"film_uri": "/API_VERSION/film/the-shining/",
"wishlist": 9,
"owned": 1,
"resource_uri": "/API_VERSION/user/mrk/filmbasket/the-shining/"
}
'striphtml' parameter
To some requests 'striphtml' parameter may be added to strip html tags from response.
Available resources
Users
User profile resources are available using following URI format:
/API_VERSION/user/USERNAME/
profile of authenticated user is available at:
/API_VERSION/profile/
Example:
curl -X GET -u mrk:pass http://FILMASTER_API_HOST/API_VERSION/profile/ { "website": "http://mrk.sed.pl/", "last_name": "Kryński", "date_joined": "2008-12-16 02:26:53", "first_name": "Mariusz", "films_owned_uri": "/API_VERSION/user/mrk/films-owned/", "last_login": "2010-12-03 21:15:56", "location": "Warsaw", "latitude": "52.237394", "recommendations_uri": "/API_VERSION/user/mrk/recommendations/", "recommendations_status": 1, "channel_showtimes_uri": "/API_VERSION/user/mrk/channel/showtimes/", "username": "mrk", "wishlist_uri": "/API_VERSION/user/mrk/wishlist/", "description": "", "posts_uri": "/API_VERSION/user/mrk/posts/", "ratings_uri": "/API_VERSION/user/mrk/ratings/film/", "films_unrated_uri": "/API_VERSION/user/mrk/films-unrated/", "short_reviews_uri": "/API_VERSION/user/mrk/short-reviews/", "shitlist_uri": "/API_VERSION/user/mrk/shitlist/", "country": "PL", "filmbasket_uri": "/API_VERSION/user/mrk/filmbasket/", "longitude": "21.005142", "showtimes_uri": "/API_VERSION/user/mrk/showtimes/", "avatar": { "image_128": "/static/avatars/generic.128.jpg", "image": "/static/avatars/generic.jpg", "image_96": "/static/avatars/generic.96.jpg", "image_32": "/static/avatars/generic.32.jpg", "image_48": "/static/avatars/generic.48.jpg", "image_72": "/static/avatars/generic.72.jpg" }, "gender": "M", "activities_uri": "/API_VERSION/user/mrk/activities/", "community_uri": "/API_VERSION/user/mrk/community/" }
Fields with _uri suffix contains URIs of user-related resources.
User profile data may be changed using PUT method.
For example, to set profile description of authenticated user:
curl -X PUT -u alice:pass http://FILMASTER_API_HOST/API_VERSION/profile/ -d description="lorem ipsum"
recommendations_status field may contain following values:
0 - no recommendations
1 - normal recommendations
2 - preparing fast recommendations
3 - fast (partial) recommendations
User's Film Recommendations
Resource URI of user's film recommendations is available at 'recommendations_uri' field of user profile.
Following request parameters can be used to filter result:
- tags - comma-separated list of tags
- year_from - start release year
- year_to - end release year
- director_uri - resource URI of related director (absolute path, without host part)
- actor_uri - resource URI of related actor
Example:
curl 'http://FILMASTER_API_HOST/API_VERSION/user/alice/recomendations/?actor_uri=/API_VERSION/person/al-pacino/&year_from=1990&year_to=2000'
Film ratings
Fetching collection of user's unrated films:
curl http://FILMASTER_API_HOST/API_VERSION/user/alice/unrated-films/
User ratings of particular film are available as resource with following URI format:
/user/<USERNAME>/ratings/film/<FILM-PERMALINK>/
curl http://FILMASTER_API_HOST/API_VERSION/user/alice/ratings/film/pulp-fiction/ { "objects": [ { "rating": 10, "type": 1, "film_uri": "/API_VERSION/film/pulp-fiction/" "resource_uri": "/API_VERSION/user/alice/ratings/film/pulp-fiction/1/" }, { "rating": 9, "type": 2, "film_uri": "/API_VERSION/film/pulp-fiction/" "resource_uri": "/API_VERSION/user/alice/ratings/film/pulp-fiction/2/" }, { "rating": 10, "type": 15, "film_uri": "/API_VERSION/film/pulp-fiction/" "resource_uri": "/API_VERSION/user/alice/ratings/film/pulp-fiction/15/" }, { "rating": 10, "type": 6, "film_uri": "/API_VERSION/film/pulp-fiction/" "resource_uri": "/API_VERSION/user/alice/ratings/film/pulp-fiction/6/" }, { "rating": 10, "type": 14, "film_uri": "/API_VERSION/film/pulp-fiction/" "resource_uri": "/API_VERSION/user/alice/ratings/film/pulp-fiction/14/" } ] }
As you see, result does not contains paginator subobject, so it is complete.
'type' field is specified as follows:
1 - FILM
6 - SCREENPLAY,
7 - SPECIAL_EFFECTS,
8 - EDITING,
9 - MUSIC,
10 - CAMERA,
11 - NOVELTY,
14 - DIRECTORY,
15 - ACTING,
To rate particular film create URI with following format:
/profile/ratings/film/<FILM-PERMALINK>/<TYPE>/
and PUT object with rating field, example:
curl -X PUT -u alice:pass \
http://FILMASTER_API_HOST/API_VERSION/user/alice/ratings/film/pulp-fiction/1/ \
-d rating=8
Read Alice's FILM rating of 'Pulp Fiction':
curl http://FILMASTER_API_HOST/API_VERSION/user/alice/ratings/film/pulp-fiction/1/ { "rating": 10, "type": 1, "resource_uri": "/API_VERSION/user/alice/ratings/film/pulp-fiction/1/" }
Search API:
Film search:
curl http://FILMASTER_API_HOST/API_VERSION/search/film/?phrase=pulp
Person search (actor, director):
curl http://FILMASTER_API_HOST/API_VERSION/search/person/?phrase=tarantino
User search:
curl http://FILMASTER_API_HOST/API_VERSION/search/user/?phrase=michuk
Overall search (Film, Person or User):
curl http://FILMASTER_API_HOST/API_VERSION/search/?phrase=
Town search:
curl http://FILMASTER_API_HOST/API_VERSION/search/town/?phrase=warsz&country=PL
Short Reviews API
User's short review collection resource URI is stored in 'short_reviews_uri' field of user's profile
Fetching collection of user's short reviews:
curl -u mrk:qwerty http://FILMASTER_API_HOST/API_VERSION/user/alice/short-reviews/
Create / replace of short review:
User's short review of particular film is available at URI with following format:
/user/USERNAME/short-reviews/FILM_PERMALINK/. To create short review PUT object
with 'review_field" filled:
curl -u alice:pass http://FILMASTER_API_HOST/API_VERSION/profile/short-reviews/pulp-fiction/ \
-X PUT -d review_text='lorem ipsum ...'
Remove of short review:
curl -u alice:pass -X DELETE http://FILMASTER_API_HOST/API_VERSION/user/alice/short-reviews/pulp-fiction/
Short review resource supports include parameter 'author_ratings' which includes field containing author's ratings of related film
Blog Post API - (reviews)
User posts collection resource URI is stored in 'posts_uri' field of user's profile.
Fetching collection of user posts:
curl -u mrk:qwerty http://FILMASTER_API_HOST/API_VERSION/user/alice/posts/
To create blog post, create object with fields:
body - post body (required)
title - post title (required)
lead - post lead (optional)
spoilers - true/false (optional, default false)
status - 1 - PUBLIC, 2 - DRAFT (optional, default DRAFT)
and send it using POST method on user's posts resource URI. As a result new post object will be returned, with 'resource_uri' field filled. Post may be edited using PUT method sent to 'resource_uri'
address.
Example:
curl -X POST http://FILMASTER_API_HOST/API_VERSION/user/alice/posts/ -d body='post body' -d title='post title' -u alice:pass
Post may be removed using DELETE request sent to resource_uri address.
Post resource supports include parameter 'author_ratings' which includes field containing post author's ratings of first related film.
Posts may contain lists of related films and persons.
Related films are represented by resource pointed by 'related_films_uri' post's field. Related persons are represended by resource pointed by 'related_persons_uri' field.
To add film to post related films, create object with film_uri containing URI of related film and POST this object to URI read from 'related_film_uri'.
Example:
curl http://FILMASTER_API_HOST/API_VERSION/user/alice/post/123/related-films/ -X POST \ -d film_uri=/API_VERSION/film/pulp-fiction/ -u alice:pass { "film_uri": "/API_VERSION/film/pulp-fiction/", "film": {...}, "resource_uri": "/API_VERSION/user/alice/posts/123/related-films/pulp-fiction/" }
To remove related film sent DELETE request to resource_uri of association:
curl http://FILMASTER_API_HOST/API_VERSION/user/alice/posts/123/related-films/pulp-fiction/ \
-X DELETE -u alice:pass
Followers API
Following resources are defined:
/API_VERSION/user/<USERNAME>/following/ - list of users <USERNAME> follows
/API_VERSION/user/<USERNAME>/followers/ - list of users following <USERNAME>
/API_VERSION/user/<USERNAME>/blocking/ - list of users blocked by <USERNAME>
/API_VERSION/user/<USERNAME>/blockers/ - list of users blocking <USERNAME>
/API_VERSION/user/<USERNAME>/friends/ - list od users we are follow and they follow us
resources /following/ and /blocking/ are RW - authenticated user can
follow or block particular user sending POST request with user_uri field filled
supported include parameters: user, avatar
Examples:
retrieving list of users mrk follows:
curl http://FILMASTER_API_HOST/API_VERSION/user/mrk/following/ { "paginator": { "prev_uri": null, "next_uri": null, "page": 1 }, "objects": [ { "user_uri": "/API_VERSION/user/michuk/", "resource_uri": "/API_VERSION/user/mrk/following/michuk/" }, { "user_uri": "/API_VERSION/user/xmariadjx/", "resource_uri": "/API_VERSION/user/mrk/following/xmariadjx/" } ] }
The same as above, but with avatar included
curl http://FILMASTER_API_HOST/API_VERSION/user/mrk/following/?include=avatar { "paginator": { "prev_uri": null, "next_uri": null, "page": 1 }, "objects": [ { "user_uri": "/API_VERSION/user/michuk/", "avatar": { "image": "/static/avatars/2010/Feb/07/michuk_.jpg", .... }, "resource_uri": "/API_VERSION/user/mrk/following/michuk/" }, .... }
To follow user adz:
curl -X POST http://FILMASTER_API_HOST/API_VERSION/user/mrk/following/ -d user_uri='/API_VERSION/user/adz/' -u mrk:pass { "user_uri": "/API_VERSION/user/adz/", "resource_uri": "/API_VERSION/user/mrk/following/adz/" }
To unfollow user adz:
curl -X DELETE http://FILMASTER_API_HOST/API_VERSION/user/mrk/following/adz/ -u mrk:pass
To block user adz:
curl -X POST http://FILMASTER_API_HOST/API_VERSION/user/mrk/blocking/ -d user_uri='/API_VERSION/user/adz/' -u mrk:pass { "user_uri": "/API_VERSION/user/adz/", "resource_uri": "/API_VERSION/user/mrk/blocking/adz/" }
Film Basket API - (shitlist, wishlist, films_owned)
User's film basket resource URI is stored in 'filmbasket_uri' field of user's profile.
Film basket contains objects with following fields:
film_uri - resource URI of related film.
wishlist - number from 1 to 9 or null, where 1 means film is wished (is on wishlist), 9 - unwished (is on shitlist) (null - not set)
owned - value 1 means film is owned (null - otherwise)
Example - place 'The Shining' movie on wishlist and 'films owned' list:
curl -X PUT http://FILMASTER_API_HOST/API_VERSION/user/alice/filmbasket/the-shining/ \ -u alice:pass -H "Content-Type: application/json" -d '{"wishlist":1,"owned":1}'
'wishlist_uri', 'shitlist_uri' and 'films_owned_uri' profile fields contains URI of 'filters' of film basket (wishlist, shitlist and films owned respecivetly)
Comments API
To create comment (for post or short review) create object with following fields:
comment - comment text (required)
parent_uri - URI of parent comment (optional, default: null)
object_uri - URI of commented object (post or short review)
then POST object to comments resource URI: /API_VERSION/comments/
Example - comment mrk's short review:
curl -X POST http://FILMASTER_API_HOST/API_VERSION/comment/ \ -d object_uri=/API_VERSION/user/mrk/short-reviews/pulp-fiction/ \ -d comment='lorem ipsum' -u alice:pass { "comment": "lorem ipsum", "resource_uri": "/API_VERSION/comment/1123199/", "date_submitted": "2010-08-16 15:38:04", "parent_uri": null, "date_modified": "2010-08-16 15:38:04" }
To edit created comment, send PUT request to resource_uri address of comment:
curl -X PUT http://FILMASTER_API_HOST/API_VERSION/comment/1123199/ -d comment='lorem ipsum ...' \
-u alice:pass
Collection of comments for particular object (post, short review or check-in) is available at URI contained in 'comments_uri' field.
Example:
curl -X GET http://FILMASTER_API_HOST/API_VERSION/user/mrk/short-reviews/pulp-fiction/ { "film_uri": "/API_VERSION/film/pulp-fiction/", "user_uri": "/API_VERSION/user/mrk/", "comments_uri": "/API_VERSION/user/mrk/short-reviews/pulp-fiction/comments/", "created_at": "2010-08-15 14:17:50", "review_text": "must see movie", "updated_at": "2010-08-16 15:38:04", "resource_uri": "/API_VERSION/user/mrk/short-reviews/pulp-fiction/" } curl -X GET http://FILMASTER_API_HOST/API_VERSION/user/mrk/short-reviews/pulp-fiction/comments/
Private messages & conversation API
Resource URI: /API_VERSION/profile/messages/
and:
/API_VERSION/profile/messages/inbox/ - messages received
/API_VERSION/profile/messages/outbox/ - messages sent
/API_VERSION/profile/messages/trash/ - messages deleted
To send message create object with following field:
recipient_uri - recipient URI
parent_uri - parent message URI (optional)
subject - message subject
body - message text
Created object POST to address: /API_VERSION/profile/messages/.
Example:
curl http://FILMASTER_API_HOST/API_VERSION/profile/messages/ -u alice:pass -X POST \ -d recipient_uri=/API_VERSION/user/bob/ -d subject=temat { "body": "", "recipient_uri": "/API_VERSION/user/bob/", "sender_uri": "/API_VERSION/user/test/", "read_at": null, "date": "2010-08-24 01:18:52", "resource_uri": "/API_VERSION/profile/messages/3/", "parent_uri": null, "subject": "temat" }
'parent' message field groups messages into conversations (threads).
User's conversation collection is available at following resource URI:
/API_VERSION/profile/conversations/
Example:
curl http://FILMASTER_API_HOST/API_VERSION/profile/conversations/ -u alice:pass { "paginator": { "prev_uri": null, "next_uri": null, "page": 1 }, "objects": [ { "body": "msg body", "message_cnt": 1, "unread_cnt": 1, "sender_uri": "/API_VERSION/user/mrk/", "messages_uri": "/API_VERSION/profile/conversations/48/messages/", "created_at": "2011-01-10 00:24:49", "updated_at": "2011-01-10 00:24:49", "resource_uri": "/API_VERSION/profile/conversations/48/", "subject": "msg subject" } ] }
Conversation object fields:
body - body of last message in conversation
subject - subject of last message in conversation
sender_uri - sender of last message in conversation
unread_cnt - number of unread messages in conversation
messages_uri - collection of all conversation messages
User activities and Planet API
particular user activities are available at following URI:
/API_VERSION/user/USERNAME/activities/
All users activities (planet) are available at:
/API_VERSION/planet/
Following filters may be specified as request parameters:
favorites - returns objects marked as 'favorite'
interesting - returns featured posts
'short_reviews', 'posts', 'comments', 'links', 'follows', 'checkins' (or any combination of them) - filter only selected types of activities
In case of authenticated request following parameters may be specified:
'following' - only activities of users we are following
'similar-taste' - similar users activities
example - retrieve posts & short_reviews of users we are following
curl http://FILMASTER_API_HOST/API_VERSION/planet/?short_reviews&posts&following
Community Resource
Community resource is available at /user/USERNAME/commmunity/ URI (this URI is also available via community_uri field in user object)
By default this resource returns paginated collection of all Filmaster users, sorted by descending order of common taste parameter. Additional filters may be applied using following request parameters:
- distance=distance - returns only nearby users (distance specified in km)
- following - returns only users that particular user is following
Sort order may be changed by 'sort_by' parameter:
- sort_by=[common_taste | common_films | username | date_joinded | distance] - sort order
Supported values of 'include' parameter:
- common_taste - appends common_taste field
- common_films - appends common_films field containing number of common films
- distance - distance between users
Example:
curl http://FILMASTER_API_HOST/API_VERSION/user/michuk/community/?distance=200&include=common_taste,common_films,distance&sort_by=distance
Showtimes API
Using showtimes API You can fetch list of film screenings in nearest cinemas and user-selected TV Channels. You may also fetch collections of available town cinemas and country tv channels and fetch list of screenings for particular cinema / tv channel.
Both cinema and TV Channel are represented by Channel resource. Channel type is determined by 'type' field and may contain following values:
1 - Cinema
2 - TVChannel
Showtimes resources accept also 'type' request parameter, which may be used for filtering only particular channel type. In this case additional value is recognized - type=3 means 'both cinema and tv channels'. For backward compatibility type defaults to '1' when not specified.
Nearest cinemas are determined automatically (after latitude/longitude update in user profile), user TV channel list is managed using separate resource.
Country resource
country list is represented by
/API_VERSION/country/
Town and Country resource
Country list is available at /API_VERSION/country/ resource URI. It returns collection of Country objects.
Example:
curl http://FILMASTER_API_HOST/API_VERSION/country/ { "paginator": { "prev_uri": null, "next_uri": "/1.0/country/?page=2", "page": 1 }, "objects": [ { "towns_uri": "/1.0/town/US/", "code": "US", "name": "United States", "resource_uri": "/1.0/country/US/", "tvchannels_uri": "/1.0/country/US/tvchannel/" }, { "towns_uri": "/1.0/town/GB/", "code": "GB", "name": "Great Britain", "resource_uri": "/1.0/country/GB/", "tvchannels_uri": "/1.0/country/GB/tvchannel/" } ] }
Each country object contains 'towns_uri' pointing to country town collection and 'tvchannels_uri' pointing to country tv channel collection.
Example of Town object, from towns_uri collection:
{
"cinema_uri": "/1.0/town/503/cinema/",
"showtimes_uri": "/1.0/town/503/showtimes/",
"cinema_showtimes_uri": "/1.0/town/503/cinema/showtimes/",
"name": "Warszawa",
"resource_uri": "/1.0/town/503/"
},
'cinema_uri' field points to collection of town cinemas
'showtimes_uri' returns showtimes for all town cinemas (by film)
'cinema_showtimes_uri' returns showtimes for all town cinemas (by cinema)
Managing User's TV Channel list.
'channels_uri' in user profile points to collection of user channels. This list contains both auto-selected cinemas and tv channels, you may filter particular type using 'type' request parameter as described above.
To add new channel to list, send object with channel_uri field using POST method, example:
curl http://FILMASTER_API_HOST/API_VERSION/user/alice/channels/ -d channel_uri=/1.0/channel/2697/ -X POST -u alice:pwd { "distance": null, "resource_uri": "/1.0/user/alice/channels/2697/", "channel": { "distance": null, "name": "Polsat", "longitude": null, "address": null, "latitude": null, "type": 2, "resource_uri": "/1.0/channel/2697/" }, "channel_uri": "/1.0/channel/2697/" }
To remove channel from list, send DELETE request to item's resource_uri:
curl http://FILMASTER_API_HOST/API_VERSION/user/alice/channels/2697/ -X DELETE -u alice:pwd
Showtimes resources.
User's showtimes resource URI is stored in 'showtimes_uri' field of user profile. This resource
returns list of available showtimes for upcoming days, grouped by film.
Films are sorted by user's guess rating, or average_score if guess_rating is not available. Additionally movies from user's wishlist are moved to begin, movies from shitlist are moved to end.
Example:
curl http://FILMASTER_API_HOST/API_VERSION/user/mrk/showtimes/ { "objects": [ { "date": "2011-01-10", "resource_uri": "/API_VERSION/user/mrk/showtimes/2011-01-10/" }, { "date": "2011-01-11", "resource_uri": "/API_VERSION/user/mrk/showtimes/2011-01-11/" }, { "date": "2011-01-12", "resource_uri": "/API_VERSION/user/mrk/showtimes/2011-01-12/" }, { "date": "2011-01-13", "resource_uri": "/API_VERSION/user/mrk/showtimes/2011-01-13/" } ] }
Fetching showtimes for particular day:
curl http://FILMASTER_API_HOST/API_VERSION/user/mrk/showtimes/2011-01-10/ { "paginator": { "prev_uri": null, "next_uri": "/API_VERSION/user/mrk/showtimes/2011-01-10/?page=2", "page": 1 }, "objects": [ { "channels": [ { "channel_uri": "/API_VERSION/channel/50/", "screenings": [ { "resource_uri": "/API_VERSION/screening/61342/", "time": "2011-01-10 18:30:00" } ] } ], "film_uri": "/API_VERSION/film/mary-and-max/", "film_title": "Mary and Max" }, { "channels": [ { "channel_uri": "/API_VERSION/channel/13/", "screenings": [ { "resource_uri": "/API_VERSION/screening/63483/", "time": "2011-01-10 20:30:00" } ] }, { "channel_uri": "/API_VERSION/channel/122/", "screenings": [ { "resource_uri": "/API_VERSION/screening/73888/", "time": "2011-01-10 17:00:00" } ] } ], "film_uri": "/API_VERSION/film/el-secreto-de-sus-ojos/", "film_title": "El secreto de sus ojos" }, { "channels": [ { "channel_uri": "/API_VERSION/channel/9/", "screenings": [ { "resource_uri": "/API_VERSION/screening/58065/", "time": "2011-01-10 19:00:00" } ] } ], "film_uri": "/API_VERSION/film/nie-lubie-poniedzialku/", "film_title": "Nie lubie poniedzialku" }, { "channels": [ { "channel_uri": "/API_VERSION/channel/13/", "screenings": [ { "resource_uri": "/API_VERSION/screening/63484/", "time": "2011-01-10 17:00:00" } ] } ], "film_uri": "/API_VERSION/film/rusalka/", "film_title": "Rusalka" }, .... ] }
Supported include parameters: film, channels.channel
Other request parameters:
- with_rated - result includes films rated by user (they are skipped by default)
- without_unmatched - filters out unmatched films (they are included by default)
- type - filtering screenings by channel type, as described above (1 - cinemas, 2 - tv channels, 3 - both)
- order - film ordering
- order=title - ascending sort by title,
- order=-title - descending sort by title
Showtimes resource URI with films sorted by cinema is pointed by 'channel_showtimes_uri' field of user's profile.
List of available showtimes, by cinema:
curl http://FILMASTER_API_HOST/API_VERSION/user/mrk/channel/showtimes/ { "objects": [ { "date": "2011-01-10", "resource_uri": "/API_VERSION/user/mrk/channel/showtimes/2011-01-10/" }, { "date": "2011-01-11", "resource_uri": "/API_VERSION/user/mrk/channel/showtimes/2011-01-11/" }, { "date": "2011-01-12", "resource_uri": "/API_VERSION/user/mrk/channel/showtimes/2011-01-12/" }, { "date": "2011-01-13", "resource_uri": "/API_VERSION/user/mrk/channel/showtimes/2011-01-13/" } ] }
For particular day:
curl http://FILMASTER_API_HOST/API_VERSION/user/mrk/channel/showtimes/2011-01-10/
List of user's nearest cinemas is available at following resource URI:
http://FILMASTER_API_HOST/API_VERSION/user/USERNAME/channel/
Film / Screening check-in API
Check-ins are reperesented by /API_VERSION/checkin/ resource. Each check-in may be associated with film only or film with screening on some channel.
Check-in authenticated user mrk on some film screening:
curl -X POST http://FILMASTER_API_HOST/API_VERSION/checkin/ -u mrk:pass -d screening_uri=/API_VERSION/screening/1234/ { "created_at": "2011-06-04 14:57:33", "resource_uri": "/API_VERSION/checkin/1/", "film_uri": "/API_VERSION/pulp-fiction/", "screening_uri":"/API_VERSION/screening/1234/", "user_uri": "/API_VERSION/user/mrk/", }
Check-in authenticated user mrk on "Pulp Fiction" film
curl -X POST http://FILMASTER_API_HOST/API_VERSION/checkin/ -u mrk:pass -d film_uri=/API_VERSION/film/pulp-fiction/ { "created_at": "2011-06-04 14:57:34", "resource_uri": "/API_VERSION/checkin/2/", "film_uri": "/API_VERSION/pulp-fiction/", "screening_uri": null "user_uri": "/API_VERSION/user/mrk/", "comments_uri": "/API_VERSION/checkin/2/comments/", }
Remove check-in:
curl -X DELETE http://FILMASTER_API_HOST/API_VERSION/checkin/2/ -u mrk:pass
There are also some resources for filtering checkins associated with particular film / screening / user:
/API_VERSION/screening/12345/checkin/ - check-ins associated with screening
/API_VERSION/film/pulp-fiction/checkin/ - check-ins associated with "Pulp Fiction" movie
/API_VERSION/user/bob/checkin/ - check-ins associated with user bob
Check-ins may be commented as described in "Comments API" section.
supported include parameters: user, film, screening