swagger.yaml

swagger: "2.0"
info:
  version: 2.0.0
  title: google-movies-scraper
  description: A simple API to scrape [google.com/movies](http://google.com/movies).
    The API currently only accepts the `near` and `date` parameters that one would see
    from usage of google.com/movies.
    <br/><br/>
    The intended use of this service is to copy all
    of the URL proceeding `/movies` and paste it behind 
    [google-movies-scraper.herokuapp.com/v2/movies](http://google-movies-scraper.herokuapp.com/movies),
    and then lo-and-behold! A JSON reformatting of all the movies you could see from the
    google.com/movies call. E.g.
    
      > http://google-movies-scraper.herokuapp.com/v2/movies?near=Hinsdale%20Montana&date=2
    
    
    yields an array of JSON objects representing everything you'd see at
    
      
      > http://google.com/movies?near=Hinsdale%20Montana&date=2
    
    
    The way apiary.io processes SWAGGER definitions may make the response examples
    seem a bit confusing. Please see the JSON schema for parameter descriptions.
  contact:
    email: steven@gnobel.com
  license:
    name: MIT
    url: http://github.com/gruntjs/grunt/blob/master/LICENSE-MIT
host: google-movies-scraper.herokuapp.com
basePath: /
schemes:
  - http
produces:
  - application/json
definitions:
  Showtime:
    type: string
    description: time-stamp. Sometimes in 24-hour clock, sometimes in 12.
      It depends on the locale and whether `militaryTime` is true or false.
    example: '17:20'
  Movie:
    required:
      - name
      - times
      - warnings
      - runtime
      - info
      - url
    properties:
      name:
        type: string
        example: 'Kungfu Panda 3'
      mid:
        type: string
        description: google.com/movie's 'movie id' for a particular movie.
        example: 'f119bc480'
      info:
        type: string
        description: Anything that follows a second '-' `info` div of a movie.
          This is typically the movie genre, for North American releases.
        example: Comedy/Romance - Trailer - IMDb
      runtime:
        type: integer
        default: 0
        description: This is parsed value that sometimes isn't available.
          If it cannot be parsed, the value of 0 is returned.
        example: 110
      times:
        type: array
        items: 
          type: string
        default: []
        example: ['12:45', '13:30']
      url:
        type: string
        x-isnullable: true
        description: The url associated to a particular movie (and potentially theatre)
          returned from a particular crawl.
        example: '/movies?near=Hinsdale+MT&date=4&mid=e65f11b56eee1b30'
      warnings:
        type: array
        items: 
          type: string
        default: []
        example: ["couldn't extract hours from First Graders preceded by Two Solutions for One Problem and Solution No. 1's runtime"]
        description: any warnings thrown during the parsing of the movie
          are stored here.
  Theatre:
    required:
      - name
      - warnings
      - showtimes
      - url
      - tid
      - info
    properties:
      info:
        type: string
        example: '600 2nd Avenue South, Glasgow, MT, United States - (406) 228-9239'
        description: the contents of the `theatre.info` div in the google.com/movies html.
          This typically contains the address and phone number of the theatre.
      name:
        type: string
        example: Cineplex Odeon Latin Quarter Cinemas
      showtimes:
        type: array
        items:
          $ref: '#/definitions/Movie'
      tid:
        type: string
        x-isnullable: true
        example: '43b016ae8041178e'
        description: extracted from <a> surrounding theatre name. If only one theatre is
          returned from a query, this value will be null (since google won't wrap the theatre
          in an <a>)
      url:
        type: string
        x-isnullable: true
        description: extracted from <a> surrounding theatre name. If only one theatre is
          returned from a query, this value will be null (since google won't wrap the theatre
          in an <a>).
      warnings:
        type: array
        items: 
          type: string
        default: []
        example: ['could not scrape theatre url']
        description: any warnings thrown during the parsing of the theatre
          are stored here.
          
paths:
  /v2/movies:
    get:
      description: Return all theatres (and their showtimes) displayed in a call to
        google.com/movies. The structure of the return is meant to follow the classes found in
        the returned html of google.com/movies.
      parameters:
        - name: near
          in: query
          description: where are the movie theatres located?
          required: true
          type: string
        - name: date
          in: query
          description: how many days from now are the desired showtimes? If not specified, 0 is assumed.
          required: false
          type: integer
          format: int32
          default: 0
        - name: militaryTime
          in: query
          description: should timestamps be converted to military time
            (24-hour clock) or left as is?
          type: boolean
          default: false
          
      responses:
        400:
          description: Missing or Misspecified Parameter.
          
        500:
          description: Internal Error -- Something went wrong during the scrape.
            This is probably a consequence of the CSS selection rules. Either one of
            the pages google has formatted breaks pattern, or google has changed
            a general pattern.
        
        200:
          description: Success
          schema:
            type: array
            items:
              $ref: '#/definitions/Theatre'