Table of Contents

    API

    Mock Server

    Use this URL to access a mockup of the API server. Your traffic will be recorded and compared to the documentation. You'll find your traffic analysis in the inspector or directly here in the documentation, right next to each resource.

GoWatchIt Developers API v2

The API provides access to the GoWatchIt database of movies and information about movie availabilities. Availibility information is available for formats such as DVD rentals, online streaming, theaters, and outdoor screenings. This API also provides links to watch, rent, or purchase movies online through GoWatchIt's partners.

This API is new and currently supports the following features:

  • Authenticate users

  • Create Quick Alerts

  • Add movies to users' queues.

  • Retreiving Availability Information. Availabilities are data sets describing which providers (e.g. Netflix) currently offer the movie, and in what formats (SD, HD, etc.). They also give a URL to each provider's version of the movie)

For access to this API, you'll need an API key, available from mailto:info@gowatchit.com.

All requests against the API must include an API key. You may include it either as a URL param, or in a request header as:

X-api-key

All results are returned in JSON format.

All Requests should be in the format /api/v2/ENDPOINT?api_key=bla&otherparams=BLA

GWI Movie IDs.

Almost every endpoint will require a GoWatchIt (GWI) movie id. For limited use, the IDs can be given to you by GWI. If you require wide spread usage, you can use the ranked search endpoint.

Ranked Search

You use this endpoint to search for a GoWatchIt movie_id. This endpoint is resource intensive, and is not meant to be connected to an end-user interface. Once you discover a GWI movie_id, those id's should be cached. This endpoing requires special permission from GWI.

/api/v2/search/ranked/:TITLE[?other­queries]

GET

/api/v2/search/ranked/:title

Get a list of title and their ids, with a match confidence score. If there are multiple matches, pick the one with the highest score. Note that a full title match happens (with some normalization for things like Part II vs. Part 2), so do not submit partial title strings.

Required Parameters:

  • TITLE is the title of a movie to match

You can also supply an OPTIONAL query­string with additional metadata to match against, if known. This is used to disambiguate movies which may have the same title, but are infact different movies. The optional parameters are “year”, “director”, and “cast”. Cast members should be joined as a comma­seperated list (Where the field title is required, and year, director, and cast are optional.)

Here is an example: /api/v2/search/ranked/downfall?year=2004&director=Oli ver Hirschbiegel&cast=Bruno Ganz,Alexandra Maria Lara

Response

200 (OK)
Content-Type: application/json
[
    {
        "id": 41219,
        "mrqe_id": "m100087691",
        "title": "Downfall",
        "year": 2004,
        "confidence": 6
    }
]

Movies

The following resource deals with movie meta data and availability. The general usage is as follows:

/api/v2/movie/action/:optional-id.json

GET

/api/v2/movies/categories

Get a list of featured content arranged by categories. The response movie data will reflect queue states for a logged in user.

Response

200 (OK)
Content-Type: application/json
{
    "categories": [
        {
          "title": "Currently Popular",
          "movies": [
              {
                "id": 266448,
                "synopsis": "This second gathering of childhood friends finds Lenny (Adam Sandler) moving his family back to the same small town where he grew up. Now, the grown ups (Sandler, Kevin James, Chris Rock, and David Spade) are the ones learning from their kids as the last day of school and its antics and surprises take center stage. Dennis Dugan returns to direct.",
                "title": "Grown Ups 2",
                "poster_url": "http://cdn.staging-gowatchit.com/posters/thumb/Grown-Ups-2-poster.jpg",
                "year": 2013,
                "genre": "Comedy",
                "duration": 0,
                "rate": "PG-13",
                "queue_count": 3445,
                "url": "/movies/grown-ups-2-266448",
                "provider_ids": [],
                "in_queue": false,
                "in_watched": false,
                "rating": 0,
                "review": ""
              },
              .... more movies 
          ]
        }    
    ]
}      

GET

/api/v2/movies/:id/availabilities

Get availabilities for a movie.

Response

200 (OK)
Content-Type: application/json
{
    "presale": null,
    "theaters": null,
    "onlines": [
        {
            "name": "iTunes",
            "logo": "http://s3.amazonaws.com/gowatchit-dev/providers/original/3_logo.png",
            "logos": {
                "light": "http://s3.amazonaws.com/gowatchit-dev/providers/original/3_logo.png",
                "dark": "http://s3.amazonaws.com/gowatchit-dev/providers/original/3_dark_logo.jpg"
            },
            "link": "http://itunes.apple.com/video/stonehenge-apocalypse/id405438653?uo=5&at=11l3Kx&ct=23",
            "watch_now": "/widget/movies/stonehenge-apocalypse-1/watch_now?availability=1542493&provider=3&provider_format=3",
            "format_line": "SD / LC",
            "buy_line": "Buy from $9.99",
            "rent_line": "Rent from $2.99",
            "provider_format_id": 3
        },
        ... more online availabilities
    ],
    "dvds": [
        {
            "name": "Netflix",
            "logo": "http://s3.amazonaws.com/gowatchit-dev/providers/original/1_logo.png",
            "logos": {
                "light": "http://s3.amazonaws.com/gowatchit-dev/providers/original/1_logo.png",
                "dark": "http://s3.amazonaws.com/gowatchit-dev/providers/original/1_dark_logo.png"
            },
            "link": "http://www.netflix.com/Movie/Stonehenge_Apocalypse/70153650",
            "watch_now": "/widget/movies/stonehenge-apocalypse-1/watch_now?availability=1127555&provider=1&provider_format=2",
            "format_line": "",
            "buy_line": "Free for Subscribers<br /><!--[if !IE]>--><span class=\"redLink\"><a href='https://www.netflix.com/Default?loms=abcd&fcld=true' class='redLink'>Join Now »</a></span><!--<![endif]-->",
            "rent_line": null,
            "provider_format_id": 2
        },
        ...more dvd availabilities
    ]
}

Response

200 (OK)
{
    "repsonse_type": "success",
    "status_code": 200,
    "message": "Movie has no availabilities"
}

Response

404 (Not Found)
Content-Type: application/json
{
    "repsonse_type": "error",
    "status_code": 404,
    "message": "Movie ID not recognized"
}

Authentication

Authentication is handled by passing a token (or HTTP session cookie) back and forth. A token is returned in the response of either of the session create endpoints below. You must pass that token with the email address back for all auth required resoureces and endpoints. The token must be passed to server calls as an SH1 hash digest of the returned auth token.

It generally looks like this:

/api/v2/something?authentication_token={SH1_HASHED_AUTH_TOKEN}&email={email_address}

POST

/api/v2/session/with_password

Sign-in using traditional username and password.

Required parameters:

  • email
  • password

Response

200 (OK)
Content-Type: application/json
{
    "display_name": "thisguy@gmail.com",
    "id": 70,
    "email": "thisguy@gmail.com",
    "avatar": null,
    "service_options": {
        "in_theaters": {
            "caption": "In Theaters",
            "provider_formats": [
                {
                    "id": 4,
                    "display_name": "Fandango",
                    "logo_url": "http://s3.amazonaws.com/gowatchit-dev/providers/original/4_logo.png"
                }
            ]
        },
        "dvd_bluray": {
            "caption": "DVD & Blu-ray",
            "provider_formats": [
                {
                    "id": 2,
                    "display_name": "Netflix",
                    "logo_url": "http://s3.amazonaws.com/gowatchit-dev/providers/original/1_logo.png"
                },
                {
                    "id": 9,
                    "display_name": "Redbox",
                    "logo_url": "http://s3.amazonaws.com/gowatchit-dev/providers/original/8_logo.png"
                }
            ]
        },
        "instant_providers": {
            "caption": "Online & On Demand",
            "provider_formats": [
                {
                    "id": 1,
                    "display_name": "Netflix",
                    "logo_url": "http://s3.amazonaws.com/gowatchit-dev/providers/original/1_logo.png"
                },
                {
                    "id": 3,
                    "display_name": "iTunes",
                    "logo_url": "http://s3.amazonaws.com/gowatchit-dev/providers/original/3_logo.png"
                },
                {
                    "id": 5,
                    "display_name": "VUDU",
                    "logo_url": "http://s3.amazonaws.com/gowatchit-dev/providers/original/7_logo.png"
                },
                {
                    "id": 7,
                    "display_name": "Amazon",
                    "logo_url": "http://s3.amazonaws.com/gowatchit-dev/providers/original/11_logo.png"
                },
                {
                    "id": 10,
                    "display_name": "Movies on Demand",
                    "logo_url": "http://s3.amazonaws.com/gowatchit-dev/providers/original/5_logo.png"
                },
                {
                    "id": 11,
                    "display_name": "SnagFilms",
                    "logo_url": "http://s3.amazonaws.com/gowatchit-dev/providers/original/12_logo.png"
                },
                {
                    "id": 12,
                    "display_name": "YouTube",
                    "logo_url": "http://s3.amazonaws.com/gowatchit-dev/providers/original/13_logo.png"
                },
                {
                    "id": 13,
                    "display_name": "Sundance Now",
                    "logo_url": "http://s3.amazonaws.com/gowatchit-dev/providers/original/14_logo.png"
                },
                {
                    "id": 14,
                    "display_name": "Hulu",
                    "logo_url": "http://s3.amazonaws.com/gowatchit-dev/providers/original/15_logo.png"
                },
                {
                    "id": 16,
                    "display_name": "Amazon",
                    "logo_url": "http://s3.amazonaws.com/gowatchit-dev/providers/original/pf_16_logo.png"
                }
            ]
        }
    },
    "full_name": "",
    "friends_count": "0",
    "authentication_token": "2zWgzpQFgpQQupsVSBjj",
    "has_facebook": false,
    "fb_post_preference": "ask",
    "fb_token": null
}

Response

422
Content-Type: application/json
{
    "repsonse_type": "error",
    "status_code": 422,
    "message": "Wrong username or password"
}

POST

/api/v2/session/with_fb

Sign-in using Facebook.

Required parameters:

  • access_token - Facebook access token. It is assumed this is gotten from the client side SDK, using the GWI facebook app id.

Response

200 (OK)
Content-Type: application/json
{
    "display_name": "thisguy@gmail.com",
    "id": 70,
    "email": "thisguy@gmail.com",
    "avatar": null,
    "service_options": {
        "in_theaters": {
            "caption": "In Theaters",
            "provider_formats": [
                {
                    "id": 4,
                    "display_name": "Fandango",
                    "logo_url": "http://s3.amazonaws.com/gowatchit-dev/providers/original/4_logo.png"
                }
            ]
        },
        "dvd_bluray": {
            "caption": "DVD & Blu-ray",
            "provider_formats": [
                {
                    "id": 2,
                    "display_name": "Netflix",
                    "logo_url": "http://s3.amazonaws.com/gowatchit-dev/providers/original/1_logo.png"
                },
                {
                    "id": 9,
                    "display_name": "Redbox",
                    "logo_url": "http://s3.amazonaws.com/gowatchit-dev/providers/original/8_logo.png"
                }
            ]
        },
        "instant_providers": {
            "caption": "Online & On Demand",
            "provider_formats": [
                {
                    "id": 1,
                    "display_name": "Netflix",
                    "logo_url": "http://s3.amazonaws.com/gowatchit-dev/providers/original/1_logo.png"
                },
                {
                    "id": 3,
                    "display_name": "iTunes",
                    "logo_url": "http://s3.amazonaws.com/gowatchit-dev/providers/original/3_logo.png"
                },
                {
                    "id": 5,
                    "display_name": "VUDU",
                    "logo_url": "http://s3.amazonaws.com/gowatchit-dev/providers/original/7_logo.png"
                },
                {
                    "id": 7,
                    "display_name": "Amazon",
                    "logo_url": "http://s3.amazonaws.com/gowatchit-dev/providers/original/11_logo.png"
                },
                {
                    "id": 10,
                    "display_name": "Movies on Demand",
                    "logo_url": "http://s3.amazonaws.com/gowatchit-dev/providers/original/5_logo.png"
                },
                {
                    "id": 11,
                    "display_name": "SnagFilms",
                    "logo_url": "http://s3.amazonaws.com/gowatchit-dev/providers/original/12_logo.png"
                },
                {
                    "id": 12,
                    "display_name": "YouTube",
                    "logo_url": "http://s3.amazonaws.com/gowatchit-dev/providers/original/13_logo.png"
                },
                {
                    "id": 13,
                    "display_name": "Sundance Now",
                    "logo_url": "http://s3.amazonaws.com/gowatchit-dev/providers/original/14_logo.png"
                },
                {
                    "id": 14,
                    "display_name": "Hulu",
                    "logo_url": "http://s3.amazonaws.com/gowatchit-dev/providers/original/15_logo.png"
                },
                {
                    "id": 16,
                    "display_name": "Amazon",
                    "logo_url": "http://s3.amazonaws.com/gowatchit-dev/providers/original/pf_16_logo.png"
                }
            ]
        }
    },
    "full_name": "",
    "friends_count": "0",
    "authentication_token": "2zWgzpQFgpQQupsVSBjj",
    "has_facebook": false,
    "fb_post_preference": "ask",
    "fb_token": null
}

Response

422
{
    "repsonse_type": "error",
    "status_code": 422,
    "message": "Wrong username or password"
}

Users

The following resource deals with retrieving and updating user data. The general usage is as follows:

/api/v2/movie/user/ENDPOINT.json

POST

/api/v2/user/forgot_password

Request a 'forgot password' email.

Required parameters:

  • email - user's email

Response

200 (OK)
Content-Type: application/json
{
    "repsonse_type": "success",
    "status_code": 200,
    "message": "Password instructions successfully sent"
}

Response

422
Content-Type: application/json
{   
    "response_type": "error",
    "status_code": 422,
    "message": "Email address not recognized"
}

GET

/api/v2/user/queue

Get movies in user's queue. Requires login. The response is paginated to inlcude 20 movies per page. The response can also be optionally filtered to include movies that are available instantly and in the specified provider-formats.

Pagination parameters:

  • offset - offset from the beginning of the queue
  • page - page number counting from the offset

Filter parameters (optional):

  • provider_format_ids - a comma-separated list of provider-format IDs (from the GoWatchIt database)
  • instatntly_available - when enabled (true), the response will only include titles that are available for instant streaming

Response

200 (OK)
Content-Type: application/json
{
    "movies": [
        {
            "id": 12910,
            "synopsis": "A group of former government assassins fights back against the CIA after they're targeted for knowing too much in this adaptation of Warren Ellis' acclaimed DC Comics graphic novels. Frank Moses (Bruce Willis) used to be a hired gun for the CIA. Along with Joe (Morgan Freeman), Marvin (John Malkovich), and Victoria (Helen Mirren), Frank's specialty was carrying out contracts that the government didn't want the public to know about. These days, Frank and his old gang are all retired, but the powers that be are still concerned that they know too much, and dispatch a team of top assassins to ensure their silence. Now, Frank and his former team members realize that their only hope for survival is to break into CIA headquarters and expose the truth. But once they're in, the group uncovers evidence of a massive cover-up that promises to rock the very foundation of our government. Karl Urban, Brian Cox, Richard Dreyfuss, and Ernest Borgnine co-star.",
            "title": "Red",
            "poster_url": "http://cdn.staging-gowatchit.com/posters/thumb/movie_12910.jpg",
            "year": 2010,
            "genre": "Action/Adventure",
            "duration": 111,
            "rate": "PG-13",
            "queue_count": 192,
            "url": "/movies/red-12910",
            "provider_ids": [
                1,
                3,
                7,
                11,
                17
            ],
            "in_queue": true,
            "in_watched": false,
            "rating": 4,
            "review": "not bad at all"
        },
        ... more movies
    ],
    "total_by_filter": 103,
    "total_queued": 103,
    "paging": {
        "current_offset": 33,
        "per_page": 20,
        "next_page": "/api/v2/user/queue?offset=53"
    }
}

Response

401 (Unauthorized)
Content-Type: application/json
{
    "repsonse_type": "error",
    "status_code": 401,
    "message": "Login required"
}

POST

/api/v2/user/queue

Add a movie to a user's queue. Requires login.

Required parameters:

  • movie_id - the GoWatchIt movie id

Response

200 (OK)
Content-Type: application/json
{
    "response_type": "success",
    "status_code": 200,
    "message": "Stonehenge Apocalypse successfully queued"
}

Response

401 (Unauthorized)
Content-Type: application/json
{
    "repsonse_type": "error",
    "status_code": 404,
    "message": "Movie ID not recognized"
}

DELETE

/api/v2/user/queue

Delete a movie from user's queue. Required login.

Required parameters:

  • movie_id - the GoWatchIt movie id

Response

200 (OK)
Content-Type: application/json
{
    "response_type": "success",
    "status_code": 200,
    "message": "Stonehenge Apocalypse deleted from queue"
}

Response

401 (Unauthorized)
Content-Type: application/json
{
    "repsonse_type": "error",
    "status_code": 404,
    "message": "Movie is not in user's queue"
}

Quick Alerts

The following resource allows a user to get a quick alert for a specific movie with only an email address.

An account is not required. If a user does have an account the system will elegantly handle by adding to the move to that user's queue:

/api/v2/quick_alert.json

POST

/api/v2/quick_alert

Create a quick alert.

Required parameters:

  • email - user's email
  • movieId the GoWatchIt movieId that the user wants to use.

A user will be sent a confirmation email. The response will include an upgrade URL, which can be displayed to the user if relevant.

Response

200 (OK)
Content-Type: application/json
{
    "upgrade_path": "http://gowatchit.com/quick_alerts/upgrade/blablabla"
}

Response

422
Content-Type: application/json
{   
    "message": "Email address not valid"
}

Tracking

The following resource is used to track renderings/serves of API assets, so that the system can determine conversion ratios for various user interactions.

/api/v2/tracking/asset_serve?movie_id=:id

POST

/api/v2/asset_serve

Track an asset serve.

Required parameters: * movie_id the GoWatchIt movieId of the asset being served.

Response

200 (OK)
Content-Type: application/json
{
    "success": {
        "message": "Asset serve recorded"
    }
}