Movieplayer.it REST API documentation (v1)

This document describes the REST API and resources provided by Movieplayer.it. This API is for developers who want to retrieve information on movies from the website movieplayer.it.
In order to use this API you have to request an api key. Please write an email to supporto@movieplayer.it specifying your movieplayer.it email.
If you're not yet a movieplayer.it registered user, please register first and then request your api key.

The Movieplayer.it REST API provides read-only access to resources (data entities) via URI paths using the standard HTTP GET method. To use a REST API, your application will make an HTTP request and parse the response.
Currently, the only supported response format is JSON.
See the changelog page for information on updates to the current release.


Terms of use

Movieplayer.it:

  • does not guarantee the service uptime
  • has the right to change the API implementation without previous notice
  • has the right to limit access to the service to certain users based on the number of requests per hour

Structure of the REST URIs

Sample call to the API:

  • using curl: curl -G -d api_key=APIKEY http://movieplayer.it/api/v1/movie/tt0499549/
  • or in a browser: http://movieplayer.it/api/v1/movie/tt0499549/?format=json&api_key=APIKEY

While accessing the API via browser, remember to pass the query parameter format=json in the URL.


Movies

/api/v1/movie/search/?q

Basic search in the movie database.

Request query parameters:

  • q: the italian or english movie title (full or partial)

Example:

  • /api/v1/movie/search/?q=the Grudge&api_key=APIKEY

/api/v1/movie/{id}/?type

Shows data for a specific movie.

Uri parameters:

  • id: the movie id from the website imdb.com

Request query parameters:

  • type: the image typology (optional). The values accepted are: still-frame, promo, wallpaper, event, poster.
    If you don't specify a value for this parameter, 4 images or less for each typology will be provided.

Examples:

  • /api/v1/movie/tt0499549/?api_key=APIKEY
  • /api/v1/movie/tt0499549/?api_key=APIKEY&type=still-frame

Output:

Each JSON object representing a movie has the following structure:

  • id: movieplayer.it id
  • imdbid: imdb.com id
  • name: title
  • original: original title
  • year: release year
  • duration: duration (in minutes)
  • genres: a list of genres
  • plot: plot
  • poster: a JSON object with the following name/value pairs:
    • url: absolute URL of the original poster
    • thumb: absolute URL of the thumbnail
  • absolute_url: absolute URL of the movie
  • moviescore: average rating (5/5) given by movieplayer.it staff members and users (empty string if not available)
  • review_url: absolute URL of the review
  • videoreview: a JSON object representing the movie video review:
    • url: absolute URL of the HTML page containing the video review
    • file_url: absolute URL of the video review
    • image_url: absolute URL of the video screenshot
  • trailer: a JSON object representing the movie trailer:
    • url: absolute URL of the HTML page containing the trailer
    • file_url: absolute URL of the trailer
    • image_url: absolute URL of the trailer screenshot
  • actors: a list of 10 most important actors (full name)
  • directors: a list of 3 most important directors (full name)
  • screenwriters: a list of 3 most important screenwriters (full name)
  • homevideos : a list of homevideo editions. Each homevideo is a JSON object with the following name/value pairs:
    • name: name, type and year
    • release_date: string representing the release date (approximate if necessary) in italian format (optional)
  • images: a JSON object with the following name/value pairs:
    • still-frame: a list of JSON objects:
      • url: absolute URL of the original image
      • thumb: absolute URL of the thumbnail
    • promo: a list of JSON objects:
      • url: absolute URL of the original image
      • thumb: absolute URL of the thumbnail
    • wallpaper: a list of JSON objects:
      • url: absolute URL of the original image
      • thumb: absolute URL of the thumbnail
    • event: a list of JSON objects:
      • url: absolute URL of the original image
      • thumb: absolute URL of the thumbnail
    • poster: a list of JSON objects:
      • url: absolute URL of the original image
      • thumb: absolute URL of the thumbnail

Example:

            {
                "id": "9803", 
                "imdbid": "tt0499549",
                "name": "Avatar", 
                "original": "Avatar", 
                "year": 2009,
                "duration": "162", 
                "genres": [
                    "Azione", 
                    "Fantascienza"
                ],
                "plot": "Jake Sully, un ex Marine costretto a vivere sulla sedia a rotelle, \u00e8, tutto sommato, ancora un combattente. 
                    E' stato reclutato per viaggiare anni luce sino all'avamposto umano su Pandora, dove alcune societ\u00e0 stanno estraendo un raro minerale 
                    che \u00e8 la chiave per risolvere la crisi energetica sulla Terra.[...]", 
                "poster": {
                    "thumb": "http://images.movieplayer.it/2011/05/30/locandina-ufficiale-italiana-di-avatar-204858_medium.jpg", 
                    "url": "http://images.movieplayer.it/2011/05/30/locandina-ufficiale-italiana-di-avatar-204858.jpg"
                }, 
                "absolute_url": "http://movieplayer.it/film/avatar_9803/", 
                "moviescore": "4.13852", 
                "review_url": "http://movieplayer.it/film/articoli/il-nuovo-mondo-su-pandora_6494/", 
                "trailer": {
                    "file_url": "http://video.movieplayer.it/trailer/2009/11/04/avatar-trailer-italiano-4736.flv", 
                    "image_url": "http://images.movieplayer.it/2009/11/04/avatar-trailer-italiano-4736.jpg", 
                    "url": "http://movieplayer.it/video/avatar-trailer-italiano_4736/"
                },
                "videoreview": {}, 
                "actors": [
                    "Sam Worthington", 
                    "Zoe Saldana", 
                    "Sigourney Weaver"
                ], 
                "directors": [
                    "James Cameron"
                ], 
                "screenwriters": [
                    "James Cameron"
                ], 
                "homevideos": [
                    {
                        "name": "Avatar Extended Collector's Edition - blu-ray (2010)", 
                        "release_date": "24 novembre 2010"
                    }, 
                    {
                        "name": "Avatar - blu-ray (2010)", 
                        "release_date": "maggio 2010"
                    }
                ], 
                "images": {
                    "event": [
                        {
                            "thumb": "http://images.movieplayer.it/2009/07/29/comic-con-di-san-diego-1009-james-cameron-durante-il-panel-di-presentazione-del-suo-film-avatar-125674_medium.jpg", 
                            "url": "http://images.movieplayer.it/2009/07/29/comic-con-di-san-diego-1009-james-cameron-durante-il-panel-di-presentazione-del-suo-film-avatar-125674.jpg"
                        }
                    ], 
                    "poster": [
                        {
                            "thumb": "http://images.movieplayer.it/2008/08/02/poster-del-film-84783_medium.jpg", 
                            "url": "http://images.movieplayer.it/2008/08/02/poster-del-film-84783.jpg"
                        }
                    ], 
                    "promo": [
                        {
                            "thumb": "http://images.movieplayer.it/2010/07/10/sam-worthington-zoe-saldana-e-sigourney-weaver-in-uno-scatto-promo-alla-premiere-francese-di-avatar-168179_medium.jpg", 
                            "url": "http://images.movieplayer.it/2010/07/10/sam-worthington-zoe-saldana-e-sigourney-weaver-in-uno-scatto-promo-alla-premiere-francese-di-avatar-168179.jpg"
                        }
                    ], 
                    "still-frame": [
                        {
                            "thumb": "http://images.movieplayer.it/2009/11/29/una-scena-del-film-avatar-con-l-attore-stephen-lang-che-interpreta-il-col-quaritch-140139_medium.jpg", 
                            "url": "http://images.movieplayer.it/2009/11/29/una-scena-del-film-avatar-con-l-attore-stephen-lang-che-interpreta-il-col-quaritch-140139.jpg"
                        }
                    ], 
                    "wallpaper": [
                        {
                            "thumb": "http://images.movieplayer.it/2010/02/02/un-wallpaper-ufficiale-con-sam-worthington-e-il-suo-avatar-nell-omonimo-film-145750_medium.jpg", 
                            "url": "http://images.movieplayer.it/2010/02/02/un-wallpaper-ufficiale-con-sam-worthington-e-il-suo-avatar-nell-omonimo-film-145750.jpg"
                        }
                    ]
                }
            }
            

TV Series

/api/v1/tvseries/search/?q

Basic search in the tv series database.

Request query parameters:

  • q: the italian or english tv series title (full or partial)

Example:

  • /api/v1/tvseries/search/?q=dr house&api_key=APIKEY

/api/v1/tvseries/{id}/?type

Shows data for a specific tv series.

Uri parameters:

  • id: the tv series id from the website imdb.com

Request query parameters:

  • type: the image typology (optional). The values accepted are: still-frame, promo, wallpaper, event, poster.
    If you don't specify a value for this parameter, 4 images or less for each typology will be provided.

Examples:

  • /api/v1/tvseries/tt0412142/?api_key=APIKEY
  • /api/v1/tvseries/tt0412142/?api_key=APIKEY&type=still-frame

Output:

Each JSON object representing a tv series has the following structure (for an example see above in the movie section):

  • id: movieplayer.it id
  • imdbid: imdb.com id
  • name: title
  • original: original title
  • year: release year
  • genres: a list of genres
  • plot: plot
  • poster: a JSON object with the following name/value pairs:
    • url: absolute URL of the original poster
    • thumb: absolute URL of the thumbnail
  • absolute_url: absolute URL of the tv serie
  • moviescore: average rating (5/5) given by movieplayer.it staff members and users (empty string if not available)
  • seasons_number: total number of seasons
  • trailer: a JSON object representing the tv serie trailer (or the last published video if not available):
    • url: absolute URL of the HTML page containing the trailer
    • file_url: absolute URL of the trailer
    • image_url: absolute URL of the trailer screenshot
  • actors: a list of 10 most important actors (full name)
  • creators: a list of 3 most important creators (full name)
  • homevideos : a list of homevideo editions. Each homevideo is a JSON object with the following name/value pairs:
    • name: name, type and year
    • release_date: string representing the release date (approximate if necessary) in italian format (optional)
  • images: a JSON object with the following name/value pairs:
    • still-frame: a list of JSON objects:
      • url: absolute URL of the original image
      • thumb: absolute URL of the thumbnail
    • promo: a list of JSON objects:
      • url: absolute URL of the original image
      • thumb: absolute URL of the thumbnail
    • wallpaper: a list of JSON objects:
      • url: absolute URL of the original image
      • thumb: absolute URL of the thumbnail
    • event: a list of JSON objects:
      • url: absolute URL of the original image
      • thumb: absolute URL of the thumbnail
    • poster: a list of JSON objects:
      • url: absolute URL of the original image
      • thumb: absolute URL of the thumbnail