API Reference

Welcome to Watchmodes API! Watchmode is the most complete API for finding out what movies & shows are available on each streaming service, as well as many other useful features built for creating applications built around movies & shows. You can use this API to access all our API endpoints, such as the Title API to get details on a specific title, or the List Titles API to get a listing of movies & shows that match a certain criteria.

The API is organized around REST. All requests should be made over SSL. All request and response bodies, including errors, are encoded in JSON.

Watchmode title IDs and person IDs are universal and cannot collide. So you don't have to worry that the ID for an actor can collide with the ID for a movie, or that an ID for a TV show can collide with a movie ID.

Simply pass your apiKey as a GET or POST parameter to the API to authenticate. You can use the test key provided in the examples to test, however be advised the testing apiKey is limited to certain queries and will only return responses to the example requests shown below.

When you first integrate your application with the Watchmode API, you may want to get all of the Watchmode IDs for titles and people. To get a list of all Watchmode IDs, and their corresponding IMDB/TMDB ids, you can download the following files:

https://api.watchmode.com/datasets/title_id_map.csv

https://api.watchmode.com/datasets/person_id_map.csv

Errors

HTTP Status codes

Code Title Description
200 OK The request was successful.
400 Bad request Bad request
401 Unauthorized Your API key is invalid.
402 Over quota Over plan quota on this API Key.
404 Not found The resource does not exist.
429 Too Many Requests The rate limit was exceeded.
50X Internal Server Error An error occurred with our API.

Error Response

Example error response.

{"success":false,"statusCode":400,"statusMessage":"Please set a valid change type method."}
                    

All errors are returned in the form of JSON with a type and optional message.

Rate Limiting

Check to see how many requests you have left:

$ curl -i https://api.watchmode.com/v1/status/?apiKey={apiKey}

HTTP/1.1 200 OK
Date: Mon, 01 Jul 2014 21:20:00 GMT
Status: 200 OK
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 111
X-Account-Quota: 999999
X-Account-Quota-Used: 93
Retry-After: 19

You can make up to 120 requests per minute using your API key. How many requests you have remaining (X-RateLimit-Remaining), and how many seconds until your rate limit has reset (Retry-After) are returned in the HTTP headers.

Example rate limit error response.

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-Account-Quota: 999999
X-Account-Quota-Used: 93
Retry-After: 19

Content-Type: application/json
{
    "success": false,
    "statusCode": 429,
    "statusMessage": "The rate limit was exceeded."
}

Sources

Example Request

/v1/sources/

curl -i https://api.watchmode.com/v1/sources/?apiKey={apiKey}

Example response

[
    {
    "id": 203,
    "name": "Netflix",
    "type": "sub",
    "logo_100px": "https://cdn.watchmode.com/provider_logos/netflix_100px.png",
    "ios_appstore_url": "http://itunes.apple.com/app/netflix/id363590051",
    "android_playstore_url": "https://play.google.com/store/apps/details?id=com.netflix.mediaclient&hl=en",
    "android_scheme": "nflx",
    "ios_scheme": "nflx",
    "regions": ["US", "CA", "GB", "AU"]
  },
  {
    "id": 157,
    "name": "Hulu",
    "type": "sub",
    "logo_100px": "https://cdn.watchmode.com/provider_logos/hulu_100px.png",
    "ios_appstore_url": "http://itunes.apple.com/app/hulu-plus/id376510438",
    "android_playstore_url": "https://play.google.com/store/apps/details?id=com.hulu.plus",
    "android_scheme": "hulu",
    "ios_scheme": "hulu",
    "regions": ["US"]
  }
]

Return a listing of all streaming sources that Watchmode supports. Optionally filter by type of source (subscription, free, etc).

Parameter Required Description
types optional string Pass one of the following values, or multiple comma separated values to only return certain types:
sub, free, purchase, tve. "Sub" means the service is a subscription service, "tve" means the service is a TV channel app.
regions optional string Pass one of the region values (eg. US), or multiple regions comma delimited to only return sources active in those regions. Currently supported regions: US, GB, CA, AU

Regions

Example Request

/v1/regions/

curl -i https://api.watchmode.com/v1/regions/?apiKey={apiKey}

Example response

[
  {
    "country": "US",
    "name": "USA",
    "flag": "https://cdn.watchmode.com/misc_images/icons/usFlag2.png"
  },
  {
    "country": "CA",
    "name": "Canada",
    "flag": "https://cdn.watchmode.com/misc_images/icons/flagCA.png"
  },
  {
    "country": "GB",
    "name": "Great Britain",
    "flag": "https://cdn.watchmode.com/misc_images/icons/flagGB.png"
  },
  {
    "country": "AU",
    "name": "Australia",
    "flag": "https://cdn.watchmode.com/misc_images/icons/flagAU.png"
  }
]

Return a listing of all regions (countries) that Watchmode currently supports.

Networks

Example Request

/v1/networks/

curl -i https://api.watchmode.com/v1/networks/?apiKey={apiKey}

Example response

[
  { "id": 1, "name": "HBO", "origin_country": "US", "tmdb_id": 49 },
  { "id": 2, "name": "National Geographic", "origin_country": "US", "tmdb_id": 43 },
  { "id": 3, "name": "YouTube", "origin_country": null, "tmdb_id": 247 },
  { "id": 4, "name": "SBS", "origin_country": "KR", "tmdb_id": 156 },
  { "id": 5, "name": "DC Universe", "origin_country": "US", "tmdb_id": 2243 },
  { "id": 6, "name": "Viceland", "origin_country": "US", "tmdb_id": 1339 },
  { "id": 7, "name": "ABC", "origin_country": "US", "tmdb_id": 2 },
  { "id": 8, "name": "AMC", "origin_country": "US", "tmdb_id": 174 },
  { "id": 9, "name": "PBS", "origin_country": "US", "tmdb_id": 14 }
]

Return a listing of all TV networks that may be returned for a title in the /title endpoint.

Genres

Example Request

/v1/genres/

curl -i https://api.watchmode.com/v1/genres/?apiKey={apiKey}

Example response

[
  { "id": 4, "name": "Comedy", "tmdb_id": 35 },
  { "id": 6, "name": "Documentary", "tmdb_id": 99 },
  { "id": 33, "name": "Anime", "tmdb_id": null }
]

Return a mapping of genre names and IDs. Some genres have a tmdb_id, which is the corresponding genre ID on TheMovieDB.org API.

Search

Example Request

/v1/search/

curl -i https://api.watchmode.com/v1/search/?apiKey={apiKey}&search_field=name&search_value=Ed%20Wood

Example response

{
  "title_results": [
    {
      "id": 1114888,
      "name": "Ed Wood",
      "type": "movie",
      "year": 1994,
      "imdb_id": "tt0109707",
      "tmdb_id": 522,
      "tmdb_type": "movie"
    }
  ],
  "people_results": [
    {
      "id": 710125611,
      "name": "Ed Wood",
      "main_profession": "cinematographer",
      "imdb_id": "nm7903892",
      "tmdb_id": 2901757
    }
  ]
}

Search for titles or people using an external ID (IMDB, TheMovieDB.org), or by name. Returns an array of results objects, that can either be a title or a person. Useful for getting the Watchmode IDs for titles and people.

Parameter Required Description
search_field required string The field for us to search in, either a 3rd party ID or "name" which will search for a movie/show title or a person's name depending on the type(s) set. Must be one of the following options:
imdb_id, tmdb_person_id, tmdb_movie_id, tmdb_tv_id, name.
search_value required string The value we should search for. For example, if you set search_field to imdb_id, this would be the IMDB title/person ID, eg. tt0944947.
types optional string Pass one of the following values, or multiple comma separated values to only return certain types:
tv, movie, person.

Title Details API

Example Request

curl -i https://api.watchmode.com/v1/title/345534/details/?apiKey={apiKey}

Example response

{
  "id": 345534,
  "title": "Game of Thrones",
  "original_title": "Game of Thrones",
  "plot_overview": "Seven noble families fight for control of the mythical land of Westeros. Friction between the houses leads to full-scale war. All while a very ancient evil awakens in the farthest north. Amidst the war, a neglected military order of misfits, the Night's Watch, is all that stands between the realms of men and icy horrors beyond.",
  "type": "tv_series",
  "runtime_minutes": 60,
  "year": 2011,
  "end_year": 2019,
  "release_date": "2011-04-17",
  "imdb_id": "tt0944947",
  "tmdb_id": 1399,
  "tmdb_type": "tv",
  "genres": [40, 7, 39, 13, 41],
  "user_rating": 8.7,
  "critic_score": 85,
  "us_rating": "TV-MA",
  "original_language": "en",
  "similar_titles": [
    101216,
    92023,
    15551,
    6822,
    052048,
    135512,
    29319,
    110268,
    0520506,
    0515852,
    124749,
    129354,
    131293,
    17141,
    119816
  ],
  "networks":[1],
  "relevance_percentile": 98.91
}

/v1/title/{title_id}/details/

Get the details for a specific title, using the Watchmode universal ID. You can optionally append other title APIs to this response, using the append_to_response parameter.

Parameter Required Description
append_to_response optional string To add the results from one of the other /title/ endpoints to this request, pass one (or multiple comma separated) of the following values: sources, seasons, episodes, cast-crew. Each value you add will cost 1 additional credit.

Title Sources

Example Request

curl -i https://api.watchmode.com/v1/title/345534/sources/?apiKey={apiKey}

Example response

[
  {
    "source_id": 146,
    "type": "sub",
    "region": "US",
    "ios_url": "hbomax://urn:hbo:episode:GVU4NYgvPQlFvjSoJAbmL",
    "android_url": "https://play.hbonow.com/episode/urn:hbo:episode:GVU4NYgvPQlFvjSoJAbmL",
    "web_url": "https://play.hbonow.com/episode/urn:hbo:episode:GVU4NYgvPQlFvjSoJAbmL",
    "format": null,
    "price": null,
    "seasons": 8,
    "episodes": 73
  },
  {
    "source_id": 144,
    "type": "sub",
    "region": "US",
    "ios_url": "aiv://aiv/resume?_encoding=UTF8&asin=B007HJ84ZK&time=0",
    "android_url": "https://watch.amazon.com/detail?asin=B007HJ84ZK&&creativeASIN=B007HJ84ZK&ie=UTF8",
    "web_url": "intent://watch.amazon.com/watch?asin=B007HJ84ZK&contentType=episode&territory=US&ref_=atv_dp_pb_core#Intent;scheme=https;package=com.amazon.avod.thirdpartyclient;component=com.amazon.avod.thirdpartyclient/com.amazon.avod.thirdpartyclient.ThirdPartyPlaybackActivity;end",
    "format": null,
    "price": null,
    "seasons": 8,
    "episodes": 73
  },
  {
    "source_id": 387,
    "type": "sub",
    "region": "US",
    "ios_url": "hbomax://urn:hbo:episode:GVU4NYgvPQlFvjSoJAbmL",
    "android_url": "https://play.hbomax.com/episode/urn:hbo:episode:GVU4NYgvPQlFvjSoJAbmL",
    "web_url": "https://play.hbomax.com/episode/urn:hbo:episode:GVU4NYgvPQlFvjSoJAbmL",
    "format": null,
    "price": null,
    "seasons": 8,
    "episodes": 73
  },
  {
    "source_id": 442,
    "type": "sub",
    "region": "US",
    "ios_url": null,
    "android_url": "https://www.directv.com/tv/Game-of-Thrones-SHNpWmVyR21jeHM9/Winter-Is-Coming-d2N0d09mMXFtdVFLU2lheTMvWDhLQT09",
    "web_url": null,
    "format": null,
    "price": null,
    "seasons": 8,
    "episodes": 73
  }
]

/v1/title/{title_id}/sources/

Get all of the streaming sources this title is available on and direct links to watch the title (web, iOS deeplinks and Android deeplinks).

Parameter Required Description
regions optional string Pass one of the 2 character country codes from the /regions/ endpoint to filter the streaming source results to certain countries. By default the API will return all regions. Pass multiple countries by submitting them comma separated.

Title Seasons

Example Request

curl -i https://api.watchmode.com/v1/title/345534/seasons/?apiKey={apiKey}

Example response

[
  {
    "id": 40809,
    "poster_url": "https://cdn.watchmode.com/posters/0340809_season_poster_342.jpg",
    "name": "Season 8",
    "overview": "The Great War has come, the Wall has fallen and the Night King's army of the dead marches towards Westeros. The end is here, but who will take the Iron Throne?",
    "number": 8,
    "air_date": "2019-04-14",
    "episode_count": 6
  },
  {
    "id": 8,
    "poster_url": "https://cdn.watchmode.com/posters/038_season_poster_342.jpg",
    "name": "Season 7",
    "overview": "The long winter is here. And with it comes a convergence of armies and attitudes that have been brewing for years.",
    "number": 7,
    "air_date": "2017-07-16",
    "episode_count": 7
  },
  {
    "id": 7,
    "poster_url": "https://cdn.watchmode.com/posters/037_season_poster_342.jpg",
    "name": "Season 6",
    "overview": "Following the shocking developments at the conclusion of season five, survivors from all parts of Westeros and Essos regroup to press forward, inexorably, towards their uncertain individual fates. Familiar faces will forge new alliances to bolster their strategic chances at survival, while new characters will emerge to challenge the balance of power in the east, west, north and south.",
    "number": 6,
    "air_date": "2016-04-24",
    "episode_count": 10
  },
  {
    "id": 6,
    "poster_url": "https://cdn.watchmode.com/posters/036_season_poster_342.jpg",
    "name": "Season 5",
    "overview": "The War of the Five Kings, once thought to be drawing to a close, is instead entering a new and more chaotic phase. Westeros is on the brink of collapse, and many are seizing what they can while the realm implodes, like a corpse making a feast for crows.",
    "number": 5,
    "air_date": "2015-04-12",
    "episode_count": 10
  },
  {
    "id": 5,
    "poster_url": "https://cdn.watchmode.com/posters/035_season_poster_342.jpg",
    "name": "Season 4",
    "overview": "The War of the Five Kings is drawing to a close, but new intrigues and plots are in motion, and the surviving factions must contend with enemies not only outside their ranks, but within.",
    "number": 4,
    "air_date": "2014-04-06",
    "episode_count": 10
  },
  {
    "id": 4,
    "poster_url": "https://cdn.watchmode.com/posters/034_season_poster_342.jpg",
    "name": "Season 3",
    "overview": "Duplicity and treachery...nobility and honor...conquest and triumph...and, of course, dragons. In Season 3, family and loyalty are the overarching themes as many critical storylines from the first two seasons come to a brutal head. Meanwhile, the Lannisters maintain their hold on King's Landing, though stirrings in the North threaten to alter the balance of power; Robb Stark, King of the North, faces a major calamity as he tries to build on his victories; a massive army of wildlings led by Mance Rayder march for the Wall; and Daenerys Targaryen--reunited with her dragons--attempts to raise an army in her quest for the Iron Throne.",
    "number": 3,
    "air_date": "2013-03-31",
    "episode_count": 10
  },
  {
    "id": 3,
    "poster_url": "https://cdn.watchmode.com/posters/033_season_poster_342.jpg",
    "name": "Season 2",
    "overview": "The cold winds of winter are rising in Westeros...war is coming...and five kings continue their savage quest for control of the all-powerful Iron Throne. With winter fast approaching, the coveted Iron Throne is occupied by the cruel Joffrey, counseled by his conniving mother Cersei and uncle Tyrion. But the Lannister hold on the Throne is under assault on many fronts. Meanwhile, a new leader is rising among the wildings outside the Great Wall, adding new perils for Jon Snow and the order of the Night's Watch.",
    "number": 2,
    "air_date": "2012-04-01",
    "episode_count": 10
  },
  {
    "id": 2,
    "poster_url": "https://cdn.watchmode.com/posters/032_season_poster_342.jpg",
    "name": "Season 1",
    "overview": "Trouble is brewing in the Seven Kingdoms of Westeros. For the driven inhabitants of this visionary world, control of Westeros' Iron Throne holds the lure of great power. But in a land where the seasons can last a lifetime, winter is coming...and beyond the Great Wall that protects them, an ancient evil has returned. In Season One, the story centers on three primary areas: the Stark and the Lannister families, whose designs on controlling the throne threaten a tenuous peace; the dragon princess Daenerys, heir to the former dynasty, who waits just over the Narrow Sea with her malevolent brother Viserys; and the Great Wall--a massive barrier of ice where a forgotten danger is stirring.",
    "number": 1,
    "air_date": "2011-04-17",
    "episode_count": 10
  },
  {
    "id": 1,
    "poster_url": "https://cdn.watchmode.com/posters/031_season_poster_342.jpg",
    "name": "Specials",
    "overview": null,
    "number": null,
    "air_date": "2010-12-05",
    "episode_count": 65
  }
]

/v1/title/{title_id}/seasons/

Return all of the seasons for a TV show or mini-series.

Title Episodes

Example Request

curl -i https://api.watchmode.com/v1/title/345534/episodes/?apiKey={apiKey}

Example response

[
  {
    "id": 6088251,
    "name": "Winter Is Coming",
    "episode_number": 1,
    "season_number": 1,
    "season_id": 2,
    "tmdb_id": 63056,
    "imdb_id": "tt1480055",
    "thumbnail_url": "https://cdn.watchmode.com/episode_thumbnails/036088251_thumb_208.jpg",
    "release_date": "2011-04-17",
    "runtime_minutes": 62,
    "overview": "Jon Arryn, the Hand of the King, is dead. King Robert Baratheon plans to ask his oldest friend, Eddard Stark, to take Jon's place. Across the sea, Viserys Targaryen plans to wed his sister to a nomadic warlord in exchange for an army.",
    "sources": [
      {
        "source_id": 349,
        "type": "buy",
        "region": "US",
        "ios_url": "itms://itunes.apple.com/us/tv-season/winter-is-coming/id482730236?i=494877461&at=10laHb",
        "android_url": "https://itunes.apple.com/us/tv-season/winter-is-coming/id482730236?i=494877461&uo=4&at=1000l3V2",
        "web_url": "https://itunes.apple.com/us/tv-season/winter-is-coming/id482730236?i=494877461&uo=4&at=1000l3V2",
        "format": null,
        "price": null
      },
      {
        "source_id": 387,
        "type": "sub",
        "region": "US",
        "ios_url": "hbomax://urn:hbo:episode:GVU4NYgvPQlFvjSoJAbmL",
        "android_url": "https://play.hbomax.com/episode/urn:hbo:episode:GVU4NYgvPQlFvjSoJAbmL",
        "web_url": "https://play.hbomax.com/episode/urn:hbo:episode:GVU4NYgvPQlFvjSoJAbmL",
        "format": null,
        "price": null
      }
    ]
  },
  {
    "id": 6088252,
    "name": "The Kingsroad",
    "episode_number": 2,
    "season_number": 1,
    "season_id": 2,
    "tmdb_id": 63057,
    "imdb_id": "tt1668746",
    "thumbnail_url": "https://cdn.watchmode.com/episode_thumbnails/036088252_thumb_208.jpg",
    "release_date": "2011-04-24",
    "runtime_minutes": 56,
    "overview": "While Bran recovers from his fall, Ned takes only his daughters to Kings Landing. Jon Snow goes with his uncle Benjen to The Wall. Tyrion joins them.",
    "sources": [
      {
        "source_id": 24,
        "type": "buy",
        "region": "US",
        "ios_url": "aiv://aiv/resume?_encoding=UTF8&asin=B007HJ8RTI&time=0",
        "android_url": "https://watch.amazon.com/detail?asin=B007HJ8RTI&&creativeASIN=B007HJ8RTI&ie=UTF8&linkCode=xm2&",
        "web_url": "intent://watch.amazon.com/watch?asin=B007HJ8RTI&contentType=episode&territory=US&ref_=atv_dp_pb_core#Intent;scheme=https;package=com.amazon.avod.thirdpartyclient;component=com.amazon.avod.thirdpartyclient/com.amazon.avod.thirdpartyclient.ThirdPartyPlaybackActivity;end",
        "format": null,
        "price": null
      },
      {
        "source_id": 124,
        "type": "buy",
        "region": "US",
        "ios_url": "https://www.fandangonow.com/details/series/MSEC90BD6F0150572053E663B523341F75A1",
        "android_url": "https://www.fandangonow.com/details/series/MSEC90BD6F0150572053E663B523341F75A1",
        "web_url": "https://www.fandangonow.com/details/series/MSEC90BD6F0150572053E663B523341F75A1",
        "format": null,
        "price": null
      },
      {
        "source_id": 140,
        "type": "buy",
        "region": "US",
        "ios_url": null,
        "android_url": "https://play.google.com/store/tv/show?amp=&cdid=tvseason-0uaIRlgLkL4&gdid=tvepisode-h4WhiLYER4Y&gl=US&hl=en&id=71Edzxe9gmo",
        "web_url": "https://play.google.com/store/tv/show?id=71Edzxe9gmo&cdid=tvseason-0uaIRlgLkL4&gdid=tvepisode-h4WhiLYER4Y",
        "format": null,
        "price": null
      }
    ]
  }
]

/v1/title/{title_id}/episodes/

Return all of the episodes for a TV series or mini-series, as well as the streaming sources each episode is available on.

Title Cast & Crew

Example Request

curl -i https://api.watchmode.com/v1/title/345534/cast-crew/?apiKey={apiKey}

Example response

[
  {
    "person_id": 673767,
    "type": "Crew",
    "full_name": "Miguel Sapochnik",
    "headshot_url": "https://cdn.watchmode.com/profiles/07673767_profile_185.jpg",
    "role": "Executive Producer",
    "episode_count": 6,
    "order": null
  },
  {
    "person_id": 2528385,
    "type": "Cast",
    "full_name": "Kit Harington",
    "headshot_url": "https://cdn.watchmode.com/profiles/072528385_profile_185.jpg",
    "role": "Jon Snow",
    "episode_count": 73,
    "order": null
  }
]

/v1/title/{title_id}/cast-crew/

Return all people associated with the title, the "cast" (actors), and "crew" (directors, writers, cinematographers, etc). For more details on a person, pass the person-id to the /person/ endpoint

List Titles API

Example Request

curl -i https://api.watchmode.com/v1/list-titles/?apiKey={apiKey}&source_ids=203,57

Example response

{
  "titles": [
    {
      "id": 1337513,
      "title": "Secret in Their Eyes",
      "year": 2015,
      "imdb_id": "tt1741273",
      "tmdb_id": 290751,
      "tmdb_type": "movie",
      "type": "movie"
    },
    {
      "id": 1247225,
      "title": "Spy Cat",
      "year": 2018,
      "imdb_id": "tt5746054",
      "tmdb_id": 509733,
      "tmdb_type": "movie",
      "type": "movie"
    }
  ],
  "page": 1,
  "total_results": 4592,
  "total_pages": 19
}

/v1/list-titles/

Get a listing of titles that match certain parameters. Results are paginated, and return 250 pages per query by default. Useful for mapping all Watchmode title IDs in your app, and finding in bulk what titles are available in different countries, different sources or source types.

Parameter Required Description
types optional string Filter result to only include certain types of titles. Pass a single type or pass multiple types comma delimited. Possible values: movie, tv_series, tv_special, tv_miniseries, short_film
regions optional string Pass one of the region values (eg. US), or multiple regions comma delimited to only return sources active in those regions. Currently supported regions: US, GB, CA, AU
Note: If you populate the source_ids or source_types you can only set a single region, and if you set no region US will be set by default. Each additional region will cost 1 API credit.
source_types optional string Filter results to only include titles that are available on a specific type(s) of source (such a subscription, or TV Everywhere channel apps, etc). By default all are selected, pass one or multiple (comma delimited) of these values: sub, rent, buy, free, tve
Note: If you populate this you can only set a single region, and if you set no region US will be set by default.
source_ids optional string Pass an individual ID for a source (returned from the /sources/ endpoint) to filter the results to titles available on that source. Pass multiple values comma separated to return titles available on one of the sources you pass in.
Note: If you populate this you can only set a single region, and if you set no region US will be set by default.
genres optional string Filter results to only include certain genre(s). Pass in a single genre id (which you would get from the /v1/genres/ endpoint, or multiple comma separated.
page optional int Set the page of results you want to return, if this isn't set you will always get page 1 returned.
limit optional int Set how many titles to return per page, default and maximum is 250.

Person

Example Request

/v1/person/{person_id}

curl -i https://api.watchmode.com/v1/person/7110004?apiKey={apiKey}

Example response

{
  "id": 7110004,
  "full_name": "Brad Pitt",
  "first_name": "Brad",
  "last_name": "Pitt",
  "tmdb_id": 287,
  "imdb_id": "nm0000093",
  "main_profession": "actor",
  "secondary_profession": "producer",
  "tertiary_profession": "soundtrack",
  "date_of_birth": "1963-12-18",
  "date_of_death": null,
  "place_of_birth": "Shawnee, Oklahoma, USA",
  "gender": "m",
  "headshot_url": "https://cdn.watchmode.com/profiles/07110004_profile_185.jpg",
  "known_for": [1132806, 1336708, 1183315, 1387087],
  "relevance_percentile": 100
}

Return details on a specific person (actor, director, etc).

Changes API

/v1/changes/{method}/

The changes api allows you to get a list of title IDs or people IDs that have changed within a certain date range. Choose one of the methods listed below. The following parameters apply to each method listed below, but individual methods may have additional parameters.

Parameter Required Description
start_date optional int By default, the changes API will return changes since the beginning of yesterday. Populate this parameter to manually set a start date to include changes from a specific date range, format is YYYYMMDD (eg 20210101 for January 1st, 2021), or for more granular results down to the second YYYYMMDDHHMMSS (eg 20210101123459 for January 1st, 2021 12:24pm and 59 seconds). Hours are in 24 hour format and in Eastern Standard Time. Month, day, hour, minutes and seconds use leading zeros for single digit values.
end_date optional int By default, the changes API will return changes since the beginning of yesterday. Populate this parameter to manually set a end date to include changes from a specific date range, format is YYYYMMDD (eg 20210101 for January 1st, 2021), or for more granular results down to the second YYYYMMDDHHMMSS (eg 20210101123459 for January 1st, 2021 12:24pm and 59 seconds). Hours are in 24 hour format and in Eastern Standard Time. Month, day, hour, minutes and seconds use leading zeros for single digit values.
page optional int Set the page of results you want to return, if this isn't set you will always get page 1 returned.
limit optional int Set how many titles to return per page, default and maximum is 250.

New Titles

Example Request

curl -i https://api.watchmode.com/v1/changes/new_titles?apiKey={apiKey}&types=movie,tv_series

Example response

{
  "titles": [
    1138,
    1668,
    1867,
    11029,
    11045,
    11173,
    11394
  ],
  "page": 1,
  "total_results": 6513,
  "total_pages": 27
}

/v1/changes/new_titles/

Get a listing of the title IDs of new titles added to Watchmode within the date range.

Parameter Required Description
types optional string Filter result to only include certain types of titles. Pass a single type or pass multiple types comma delimited. Possible values: movie, tv_series, tv_special, tv_miniseries, short_film

New People

Example Request

curl -i https://api.watchmode.com/v1/changes/new_people/?apiKey={apiKey}

Example response

{
  "people": [
    710203130,
    73333445,
    710203131,
    710203132,
    710203133,
    710203134,
    710203135
  ],
  "page": 1,
  "total_results": 15113,
  "total_pages": 61
}

/v1/changes/new_people/

Get a listing of the ids of new people added to Watchmode within the date range.

Titles with Changed Sources

Example Request

curl -i https://api.watchmode.com/v1/changes/titles_sources_changed/?apiKey={apiKey}

Example response

{
  "titles": [
    12490,
    115801,
    144030,
    144341,
    160295,
    160558,
    163623,
    164792,
    193679
  ],
  "page": 1,
  "total_results": 488,
  "total_pages": 2
}

/v1/changes/titles_sources_changed/

Get a listing of titles that have changed to their streaming sources within the date range.

Parameter Required Description
types optional string Filter result to only include certain types of titles. Pass a single type or pass multiple types comma delimited. Possible values: movie, tv_series, tv_special, tv_miniseries, short_film
regions optional string Pass in the 2 character region code (eg US) for the country you want to get titles with changed sources from. There is a limit to 1 region on this endpoint, if you leave this field blank US changes will be returned only.

Titles with Changed Details

Example Request

curl -i https://api.watchmode.com/v1/changes/titles_details_changed/?apiKey={apiKey}

Example response

{
  "titles": [
    3171655,
    3127447,
    3146794,
    340763,
    361062,
    345333,
    3171642,
    3102697,
    3168127,
    3168998,
    536562
  ],
  "page": 1,
  "total_results": 14,
  "total_pages": 1
}

/v1/changes/titles_details_changed/

Get a listing of titles that have had a change to their basic details (overview, cast, genres, ratings, etc) within the date range.

Parameter Required Description
types optional string Filter result to only include certain types of titles. Pass a single type or pass multiple types comma delimited. Possible values: movie, tv_series, tv_special, tv_miniseries, short_film

Titles with Changed Episodes

Example Request

curl -i https://api.watchmode.com/v1/changes/titles_episodes_changed/?apiKey={apiKey}

Example response

{
  "titles": [
    3123402,
    3165766,
    3107530,
    3117639,
    329319,
    3124749,
    3145191,
    3163842,
    3165473,
    371881
  ],
  "page": 1,
  "total_results": 130,
  "total_pages": 1
}

/v1/changes/titles_episodes_changed/

Get a listing of titles that have changes to their episodes (new episodes, episode details changed, etc) within the date range.