NAV Navbar
shell ruby
  • Introduction
  • Authentication
  • Quotes
  • Filters
  • Filtering examples
  • Rate Limiting
  • Errors
  • Introduction

    Welcome to the MovieQuotes API! You can use this API to access well known quotes from more than 500 movies.

    Search through movie quotes by actors, characters, movies, genres, years and even pieces of quotes.

    There are language bindings in Shell & Ruby! You can view code examples in the dark area to the right and switch the programming language of the examples with the tabs in the top right.

    Authentication

    Setup the API Key

    # With shell, you can just pass the correct header with each request
    curl "http://movie-quotes-app.herokuapp.com/api/v1/quotes"
      -H "Authorization: Token token=abcd1234"
    
    MovieQuotes.configure do |config|
      config.api_key = "abcd1234"
    end
    
    # Then create a new filter instance like this:
    require 'movie_quotes'
    
    filter = MovieQuotes.new
    

    Make sure to replace abcd1234 with your API key

    MovieQuotes uses an API key to allow access to the API. Before anything you should get an API Key (free).

    Please send an email to [email protected]

    MovieQuotes expects for the API key to be included in all API requests in a header that looks like this:

    Authorization: Token token=abcd1234

    Ruby SDK

    Big ruby fan? We've got your back. There's an awesome ruby gem available to play with MovieQuote's API.

    Check it out on Github: MovieQuotes

    Quotes

    All

    require 'movie_quotes'
    
    filter = MovieQuotes.new
    
    # Make API call
    filter.results
    
    curl "http://movie-quotes-app.herokuapp.com/api/v1/quotes"
      -H "Authorization: Token token=abcd1234"
    

    The above command returns JSON structured like this:

    [
      {
        "content": "Oh, no, it wasn't the airplanes. It was Beauty killed the Beast.",
        "year": 1933,
        "categories": ["Drama", "Action", "Adventure"],
        "image_large_url": "https://s-media-cache-ak0.pinimg.com/736x/56/9c/f2/569cf2832aaabbcaa3487f22d335b4d7.jpg",
        "image_thumb_url":"https://encrypted-tbn1.gstatic.com/images?q=tbn:ANd9GcSI54WEStqtfEBeocTd1umDmBV4T2-u8D4NB_EJ13PUTUdMBuwfJde4sb4",
        "rating": 8,
        "movie": {
          "title": "King Kong",
          "slug": "king-kong"
        },
        "character": {
          "name": "Carl Denham",
          "slug": "carl-denham"
        },
        "actor":{
          "name": "Robert Armstrong",
          "slug": "robert-armstrong"
        }
      },
      ...
    ]
    

    This endpoint retrieves all quotes.

    HTTP Request

    GET http://movie-quotes-app.herokuapp.com/api/v1/quotes

    Pagination

    MovieQuotes API enables pagination via page query parameter on GET requests.

    Every API call retrieves 20 quotes at a time (per page).

    require 'movie_quotes'
    
    filter = MovieQuotes.new
    
    filter.by_page(1)
    # or
    filter.by_page("1")
    
    # Make API call
    filter.results
    
    curl "http://movie-quotes-app.herokuapp.com/api/v1/quotes?page=1"
      -H "Authorization: Token token=abcd1234"
    

    The above command returns JSON structured like this:

    [
      {
        "content": "Oh, no, it wasn't the airplanes. It was Beauty killed the Beast.",
        "year": 1933,
        "categories": ["Drama", "Action", "Adventure"],
        "image_large_url": "https://s-media-cache-ak0.pinimg.com/736x/56/9c/f2/569cf2832aaabbcaa3487f22d335b4d7.jpg",
        "image_thumb_url":"https://encrypted-tbn1.gstatic.com/images?q=tbn:ANd9GcSI54WEStqtfEBeocTd1umDmBV4T2-u8D4NB_EJ13PUTUdMBuwfJde4sb4",
        "rating": 8,
        "movie": {
          "title": "King Kong",
          "slug": "king-kong"
        },
        "character": {
          "name": "Carl Denham",
          "slug": "carl-denham"
        },
        "actor":{
          "name": "Robert Armstrong",
          "slug": "robert-armstrong"
        }
      },
      ...
    ]
    

    HTTP Request

    GET http://movie-quotes-app.herokuapp.com/api/v1/quotes?page=1

    Query Parameters

    Parameter Default Description
    page 1 Used to retrieve 20 quotes top on each request.

    Filters

    All API methods are chainable, they can be applied one after another to conform the desired request.

    By Actor

    # apply "slug" format to search terms, results will be more accurate
    filter.by_actor("keanu-reeves")
    
    # Make API call
    filter.results
    
    # apply "slug" format to search terms, results will be more accurate
    curl "http://movie-quotes-app.herokuapp.com/api/v1/quotes?actor=keanu-reeves"
      -H "Authorization: Token token=abcd1234"
    

    HTTP Request

    GET http://movie-quotes-app.herokuapp.com/api/v1/quotes?actor=keanu-reeves

    Query Parameters

    Parameter Description
    actor Used to retrieve quotes said by an actor.

    By Category (movie genre)

    Categories available to query and find amazing quotes:

    action adventure animation biography comedy crime documentary
    drama family fantasy film-noir history horror music
    musical mystery romance sci-fi short sport thriller
    war western
    filter.by_category("action")
    
    # "OR" behavior when multiple categories are applied
    filter.by_category(["action", "crime", "drama"])
    
    # Make API call
    filter.results
    
    # Single category applied
    curl "http://movie-quotes-app.herokuapp.com/api/v1/quotes?category=action"
      -H "Authorization: Token token=abcd1234"
    
    # Multiples categories applied
    curl "http://movie-quotes-app.herokuapp.com/api/v1/quotes?categories[]=sci-fi,action"
      -H "Authorization: Token token=abcd1234"
    

    HTTP Request

    GET http://movie-quotes-app.herokuapp.com/api/v1/quotes?category=action

    Query Parameters

    Parameter Description
    category Used to retrieve quotes said in movies from 1 or N categories.

    By Character

    filter.by_character("morpheus")
    
    # Make API call
    filter.results
    
    curl "http://movie-quotes-app.herokuapp.com/api/v1/quotes?character=morpheus"
      -H "Authorization: Token token=abcd1234"
    

    HTTP Request

    GET http://movie-quotes-app.herokuapp.com/api/v1/quotes?character=morpheus

    Query Parameters

    Parameter Description
    character Used to retrieve quotes said by a character.

    By Content

    filter.by_content("spoon")
    
    # Make API call
    filter.results
    
    curl "http://movie-quotes-app.herokuapp.com/api/v1/quotes?content=spoon"
      -H "Authorization: Token token=abcd1234"
    

    HTTP Request

    GET http://movie-quotes-app.herokuapp.com/api/v1/quotes?content=spoon

    Query Parameters

    Parameter Description
    content Used to retrieve quotes containing a word or pieces of quotes.

    By Movie

    # apply "slug" format to search terms, results will be more accurate
    filter.by_movie("the-matrix")
    
    # Make API call
    filter.results
    
    # apply "slug" format to search terms, results will be more accurate
    curl "http://movie-quotes-app.herokuapp.com/api/v1/quotes?movie=the-matrix"
      -H "Authorization: Token token=abcd1234"
    

    HTTP Request

    GET http://movie-quotes-app.herokuapp.com/api/v1/quotes?movie=the-matrix

    Query Parameters

    Parameter Description
    movie Used to retrieve quotes said in a movie.

    By Multiple

    Allows to query by several filters at once (movie, actor, character, quote's content and categories) providing only a string.

    Search results are gathered following an OR behavior.

    filter.by_multiple("matrix")
    
    # Make API call
    filter.results
    
    curl "http://movie-quotes-app.herokuapp.com/api/v1/quotes?multiple=matrix"
      -H "Authorization: Token token=abcd1234"
    

    HTTP Request

    GET http://movie-quotes-app.herokuapp.com/api/v1/quotes?multiple=matrix

    Query Parameters

    Parameter Description
    multiple Used to retrieve quotes containing a word or pieces of quotes OR quotes said in a movie OR by an actor OR by a character.

    By Rating

    Quotes filtered by rating from 1(worst) to 10(best).

    filter.by_rating(10)
    # or
    filter.by_rating("10")
    
    # Make API call
    filter.results
    
    curl "http://movie-quotes-app.herokuapp.com/api/v1/quotes?rating=10"
      -H "Authorization: Token token=abcd1234"
    

    HTTP Request

    GET http://movie-quotes-app.herokuapp.com/api/v1/quotes?rating=10

    Query Parameters

    Parameter Description
    rating Used to retrieve quotes with a certain rating.

    By Year

    filter.by_year(1999)
    
    # "OR" behavior when multiple years are applied
    filter.by_year([1999, 2005])
    
    # "OR" behavior when multiple years are applied
    filter.by_year(["1999", "2005"])
    
    # Make API call
    filter.results
    
    # Single year applied
    curl "http://movie-quotes-app.herokuapp.com/api/v1/quotes?years=1999"
      -H "Authorization: Token token=abcd1234"
    
    # Multiples years applied
    curl "http://movie-quotes-app.herokuapp.com/api/v1/quotes?years[]=1999,2005"
      -H "Authorization: Token token=abcd1234"
    

    HTTP Request

    GET http://movie-quotes-app.herokuapp.com/api/v1/quotes?years=1999

    Query Parameters

    Parameter Description
    years Used to retrieve quotes said in movies from an specific year.

    Randomly

    One or many quotes can be picked randomly and returned to the client.

    # A single quote is picked randomly and returned to client.
    filter.by_random
    
    # or 
    # A single quote is picked randomly and returned to client.
    filter.by_random(1)
    filter.by_random("1")
    
    # or
    # Four quotes are picked randomly and returned to client.
    filter.by_random(4)
    filter.by_random("4")
    
    # Make API call
    filter.results
    
    # A single quote is picked randomly and returned to client.
    curl "http://movie-quotes-app.herokuapp.com/api/v1/quotes?random=1"
      -H "Authorization: Token token=abcd1234"
    
    # Four quotes are picked randomly and returned to client.
    curl "http://movie-quotes-app.herokuapp.com/api/v1/quotes?random=4"
      -H "Authorization: Token token=abcd1234"
    

    HTTP Request

    GET http://movie-quotes-app.herokuapp.com/api/v1/quotes?random=4

    Query Parameters

    Parameter Description
    random Used to retrieve 1 or N quotes randomly.

    Filtering examples

    Example 1

    Filtering well known quotes by movies like The Matrix

    # apply "slug" format to search terms, results will be more accurate
    filter.by_movie("the-matrix")
    
    # Make API call
    filter.results
    
    curl "http://movie-quotes-app.herokuapp.com/api/v1/quotes?movie=the-matrix"
      -H "Authorization: Token token=abcd1234"
    

    The above command returns JSON structured like this:

    [
      {
        "content": "Never send a human to do a machine's job.",
        "year": 1999,
        "categories": [
          "Action",
          "Adventure",
          "Sci-Fi"
        ],
        "image_large_url": "https://i.ytimg.com/vi/xq7x1KQMjqw/maxresdefault.jpg",
        "image_thumb_url": "https://encrypted-tbn3.gstatic.com/images?q=tbn:ANd9GcTXQQ00AD5fSgEjG-0UP6Gj7KwZhF7_ENlaJXqM98-7gLZo_cKRSanbwyk",
        "rating": 10,
        "movie": {
          "title": "The Matrix",
          "slug": "the-matrix"
        },
        "character": {
          "name": "Agent Smith",
          "slug": "agent-smith"
        },
        "actor": {
          "name": "Hugo Weaving",
          "slug": "hugo-weaving"
        }
      },
      {
        "content": "The Matrix is the world that has been pulled over your eyes to blind you from the truth.",
        "year": 1999,
        "categories": [
          "Action",
          "Adventure",
          "Sci-Fi"
        ],
        "image_large_url": "https://i.ytimg.com/vi/O4zICmyuNvs/hqdefault.jpg",
        "image_thumb_url": "https://encrypted-tbn1.gstatic.com/images?q=tbn:ANd9GcTm1nJGU1MR5iWW001gqBVBPzLHpGX_rT3ioECTM3m-PPHJUntH5Xbu1OI",
        "rating": 10,
        "movie": {
          "title": "The Matrix",
          "slug": "the-matrix"
        },
        "character": {
          "name": "Morpheus",
          "slug": "morpheus"
        },
        "actor": {
          "name": "Laurence Fishburne",
          "slug": "laurence-fishburne"
        }
      },
      {
        "content": "There is no spoon.",
        "year": 1999,
        "categories": [
          "Action",
          "Adventure",
          "Sci-Fi"
        ],
        "image_large_url": "https://i.ytimg.com/vi/XO0pcWxcROI/maxresdefault.jpg",
        "image_thumb_url": "https://encrypted-tbn1.gstatic.com/images?q=tbn:ANd9GcRMamYtDE9kTXvKdA308D-HkaOFRZi17jxupMuL950MRLIJWGg23NFk0JUk",
        "rating": 10,
        "movie": {
          "title": "The Matrix",
          "slug": "the-matrix"
        },
        "character": {
          "name": "Spoon Boy",
          "slug": "spoon-boy"
        },
        "actor": {
          "name": "Spoon Boy",
          "slug": "spoon-boy"
        }
      },
      {
        "content": "Then you'll see, that it is not the spoon that bends, it is only yourself.",
        "year": 1999,
        "categories": [
          "Action",
          "Adventure",
          "Sci-Fi"
        ],
        "image_large_url": "https://i.ytimg.com/vi/uAXtO5dMqEI/hqdefault.jpg",
        "image_thumb_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcSp8hmUNY_YCq0imcusA5-PDQo7-Y4a5JVpB4VIG6y9dugMYZhspZIoiGM",
        "rating": 10,
        "movie": {
          "title": "The Matrix",
          "slug": "the-matrix"
        },
        "character": {
          "name": "Spoon Boy",
          "slug": "spoon-boy"
        },
        "actor": {
          "name": "Spoon Boy",
          "slug": "spoon-boy"
        }
      },
      {
        "content": "Mr. Anderson. Surprised to see me?",
        "year": 2003,
        "categories": [
          "Action",
          "Sci-Fi"
        ],
        "image_large_url": "https://i.ytimg.com/vi/hUAie-X3u8I/hqdefault.jpg",
        "image_thumb_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQN5-L0hcFyndEfAq-hU4ewoAfKMszC0Vpp357PiDHiKsDz0sB7Pz-0CkbB",
        "rating": 7,
        "movie": {
          "title": "The Matrix Reloaded ",
          "slug": "the-matrix-reloaded"
        },
        "character": {
          "name": "Agent Smith",
          "slug": "agent-smith"
        },
        "actor": {
          "name": "Hugo Weaving",
          "slug": "hugo-weaving"
        }
      }
    ]
    

    Example 2

    Filtering well known quotes by actors like Al Pacino

    # apply "slug" format to search terms, results will be more accurate
    filter.by_actor("al-pacino")
    
    # Make API call
    filter.results
    
    curl "http://movie-quotes-app.herokuapp.com/api/v1/quotes?actor=al-pacino"
      -H "Authorization: Token token=abcd1234"
    

    The above command returns JSON structured like this:

    [
      {
        "content":"Keep your friends close, but your enemies closer.",
        "rating": 5,
        "year":1974,
        "categories":[
          "Crime",
          "Drama"
        ],
        "image_large_url":"https://i.ytimg.com/vi/DfHJDLoGInM/hqdefault.jpg",
        "image_thumb_url":"https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQHyFYb7t8Qoniyea8IlFDvte0hvB8wzPBQWenC8hV_oMUudfiWlAzDEXgW",
        "movie":{
          "title":"The Godfather Part Ii",
          "slug":"the-godfather-part-ii"
        },
        "character":{
          "name":"Michael Corleone",
          "slug":"michael-corleone"
        },
        "actor":{
          "name":"Al Pacino",
          "slug":"al-pacino"
        }
      },
      {
        "content":"Say 'hello' to my little friend!",
        "rating": 5,
        "year":1983,
        "categories":[
          "Crime",
          "Drama"
        ],
        "image_large_url":"https://i.ytimg.com/vi/a_z4IuxAqpE/maxresdefault.jpg",
        "image_thumb_url":"https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcRiQEnHHPSvib02Te1fLCBaEyzMlkpK1Fomc7wFwu0lt6FZxv-gUavr6XeA",
        "movie":{
          "title":"Scarface",
          "slug":"scarface"
        },
        "character":{
          "name":"Tony Montana",
          "slug":"tony-montana"
        },
        "actor":{
          "name":"Al Pacino",
          "slug":"al-pacino"
        }
      },
      ...
    ]
    

    Example 3

    Filtering well known quotes by movie categories like crime & drama and years 1976 & 1991

    filter.by_category(["crime", "drama"]).by_year([1976, 1991])
    
    # Make API call
    filter.results
    
    curl "http://movie-quotes-app.herokuapp.com/api/v1/quotes?categories[]=crime,drama&years[]=1976,1991"
      -H "Authorization: Token token=abcd1234"
    

    The above command returns JSON structured like this:

    [
      {
        "content":"You talkin' to me?",
        "rating": 5,
        "year":1976,
        "categories":[
          "Crime",
          "Drama"
        ],
        "image_large_url":"https://i.ytimg.com/vi/-QWL-FwX4t4/maxresdefault.jpg",
        "image_thumb_url":"https://encrypted-tbn1.gstatic.com/images?q=tbn:ANd9GcQsrFYpPUa_qLZqvjL53JrBsWSLlfYBaC5qiXdNhDSTZZysA2U_IaK03HG3",
        "movie":{
          "title":"Taxi Driver",
          "slug":"taxi-driver"
        },
        "character":{
          "name":"Travis Bickle",
          "slug":"travis-bickle"
        },
        "actor":{
          "name":"Robert De Niro",
          "slug":"robert-de-niro"
        }
      },
      {
        "content":"A census taker once tried to test me. I ate his liver with some fava beans and a nice Chianti.",
        "rating": 5,
        "year":1991,
        "categories":[
          "Thriller",
          "Crime",
          "Drama"
        ],
        "image_large_url":"https://i.ytimg.com/vi/M1b2v_Lls3A/maxresdefault.jpg",
        "image_thumb_url":"https://encrypted-tbn1.gstatic.com/images?q=tbn:ANd9GcQO6iO860KO8e6Qmuv_ogCKdHXdo5CgWpPioU6CF9g5FSoqbQNoXPccQJo",
        "movie":{
          "title":"The Silence Of The Lambs",
          "slug":"the-silence-of-the-lambs"
        },
        "character":{
          "name":"Dr. Hannibal Lecter",
          "slug":"dr-hannibal-lecter"
        },
        "actor":{
          "name":"Anthony Hopkins",
          "slug":"anthony-hopkins"
        }
      },
      {
        "content":"I do wish we could chat longer, but I'm having an old friend for dinner.",
        "rating": 5,
        "year":1991,
        "categories":[
          "Thriller",
          "Crime",
          "Drama"
        ],
        "image_large_url":"https://i.ytimg.com/vi/sbJ89LFheTs/maxresdefault.jpg",
        "image_thumb_url":"https://encrypted-tbn2.gstatic.com/images?q=tbn:ANd9GcRnGtsUwpoCc-5nw_zznRS2615ZafAiESSebcMbC9NoT83Mh5XvnEI0ohg",
        "movie":{
          "title":"The Silence Of The Lambs",
          "slug":"the-silence-of-the-lambs"
        },
        "character":{
          "name":"Dr. Hannibal Lecter",
          "slug":"dr-hannibal-lecter"
        },
        "actor":{
          "name":"Anthony Hopkins",
          "slug":"anthony-hopkins"
        }
      },
      {
        "content":"I'm as mad as hell, and I'm not going to take this anymore!",
        "rating": 5,
        "year":1976,
        "categories":[
          "Biography",
          "Drama"
        ],
        "image_large_url":"https://i.ytimg.com/vi/ZwMVMbmQBug/maxresdefault.jpg",
        "image_thumb_url":"https://encrypted-tbn1.gstatic.com/images?q=tbn:ANd9GcTsFCb5V4pS0taLWJwiZTDhZXD_qzzVgtmALirHoHLbicudOGFuZew-ujhH",
        "movie":{
          "title":"Network",
          "slug":"network"
        },
        "character":{
          "name":"Howard Beale",
          "slug":"howard-beale"
        },
        "actor":{
          "name":"Peter Finch",
          "slug":"peter-finch"
        }
      },
      {
        "content":"Yo, Adrian!",
        "rating": 5,
        "year":1976,
        "categories":[
          "Sport",
          "Drama"
        ],
        "image_large_url":"https://i.ytimg.com/vi/WgScBiXkO9Y/hqdefault.jpg",
        "image_thumb_url":"https://encrypted-tbn1.gstatic.com/images?q=tbn:ANd9GcQF_Rd6Z3208kVy83_1LvvJsXUme4XMVQkejNadWsF4DzbIbgcyL-Z0rP4",
        "movie":{
          "title":"Rocky",
          "slug":"rocky"
        },
        "character":{
          "name":"Rocky Balboa",
          "slug":"rocky-balboa"
        },
        "actor":{
          "name":"Sylvester Stallone",
          "slug":"sylvester-stallone"
        }
      },
      ...
    ]
    

    Example 4

    Filtering well known quotes by characters like Harry Callahan

    # apply "slug" format to search terms, results will be more accurate
    filter.by_character("harry-callahan")
    
    # Make API call
    filter.results
    
    curl "http://movie-quotes-app.herokuapp.com/api/v1/quotes?character=harry-callahan"
      -H "Authorization: Token token=abcd1234"
    

    The above command returns JSON structured like this:

    [
      {
        "content":"Go ahead, make my day.",
        "rating": 5,
        "year":1983,
        "categories":[
          "Thriller",
          "Action"
        ],
        "image_large_url":"https://i.ytimg.com/vi/n_SU-cJFRjs/hqdefault.jpg",
        "image_thumb_url":"https://encrypted-tbn1.gstatic.com/images?q=tbn:ANd9GcQn33w-E743mL3L-ar6uI9vzE9Nu8wRE_d8UkQsDcT5vCpjWUH5TfP6szOA",
        "movie":{
          "title":"Sudden Impact",
          "slug":"sudden-impact"
        },
        "character":{
          "name":"Harry Callahan",
          "slug":"harry-callahan"
        },
        "actor":{
          "name":"Clint Eastwood",
          "slug":"clint-eastwood"
        }
      },
      {
        "content":"You've got to ask yourself one question: 'Do I feel lucky?' Well, do ya, punk?",
        "rating": 5,
        "year":1971,
        "categories":[
          "Thriller",
          "Crime",
          "Action"
        ],
        "image_large_url":"https://i.ytimg.com/vi/8Xjr2hnOHiM/maxresdefault.jpg",
        "image_thumb_url":"https://encrypted-tbn3.gstatic.com/images?q=tbn:ANd9GcTgtJip8s8q3PZ2O9mxmpVwMBsndKmFKAVJ--Oca1b6WlznU8BpTUD-Xg4",
        "movie":{
          "title":"Dirty Harry",
          "slug":"dirty-harry"
        },
        "character":{
          "name":"Harry Callahan",
          "slug":"harry-callahan"
        },
        "actor":{
          "name":"Clint Eastwood",
          "slug":"clint-eastwood"
        }
      }
    ]
    

    Rate Limiting

    MovieQuotes API provides a rate limit of 5 requests per 5 seconds.

    If you go over this limit the API will return a response with a status code of 429 until the reset time.

    Errors

    The MovieQuotes API uses the following error codes:

    Error Code Meaning
    401 Unauthorized -- Bad credentials.
    418 I'm a teapot.
    429 Throttle limit reached. Retry later
    500 Internal Server Error -- We had a problem with our server. Try again later.
    503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.