JustWatch API endpoint
Lists the episodes of a JustWatch season given as `season_id` (`tss` followed by digits), with `country` defaulting to `US` and `language` to `en`. Each episode has its number, title, description and streaming offers with provider, price and currency. Path, URL and poster appear only when JustWatch has them for that episode. An unknown season returns `404`.
/justwatch/season/episodesseason_id required string. Raw JustWatch season id matching tss[0-9]+, for example tss297253.country optional string. Two-letter country code. Defaults to US.language optional string. Two-letter language code. Defaults to en.season_id, country, or language values return 400.node: null returns 404.503.| Field | Filled in, of 10 checked | Values in the sample |
|---|---|---|
| id | 10 | |
| object_id | 10 | |
| object_type | 10 | SHOW_EPISODE in all 10 |
| title | 10 | “Long Day's Journey Into Night” and 9 other values |
| year | 10 | 2,022 |
| episode_number | 10 | 1 to 10, median 5 |
| description | 10 | median 234 characters |
| offers | 10 | median 19 entries |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| season_id | string | Yes | Raw JustWatch season id matching tss[0-9]+ | tss297253 | |
| country | string | No | Two-letter country code | US | |
| language | string | No | Two-letter language code | en | |
| x-api-key (header) | string | Yes | API key required |
curl -X GET "https://api.crawlora.net/api/v1/justwatch/season/episodes?season_id=tss297253&country=us&language=en" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"country": "US",
"language": "en",
"season": {
"id": "tss297253",
"title": "Season 1",
"season_number": 1
},
"episodes": [
{
"id": "tse5550494",
"object_type": "SHOW_EPISODE",
"title": "Long Day's Journey Into Night",
"episode_number": 1,
"offers": [
{
"provider": "Amazon Video",
"monetization_type": "BUY",
"presentation_type": "HD",
"price": 1.99,
"currency": "USD"
}
]
}
]
}
}Request schema
No body schema
Response schema
#/definitions/justwatch.seasonEpisodesResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | justwatch.SeasonEpisodesResponse | No | ||||
| data.country | string | No | US | Two-letter ISO country code the results are for. | ||
| data.episodes | array | No | Episodes of the season, in order. | |||
| data.episodes[].description | string | No | Short synopsis of the episode. | |||
| data.episodes[].episode_number | integer | No | 1 | Number of the episode within its season. | ||
| data.episodes[].id | string | No | tse5550494 | JustWatch episode id, for example `tse5550494`. | ||
| data.episodes[].object_id | integer | No | 5550494 | Numeric JustWatch id of the episode. | ||
| data.episodes[].object_type | string | No | SHOW_EPISODE | JustWatch object type, `SHOW_EPISODE` for episodes. | ||
| data.episodes[].offers | array | No | Offers for the episode, when requested. | |||
| data.episodes[].offers[].availability | string | No | https://schema.org/InStock | Availability of the offer as a schema.org URL, for example `https://schema.org/InStock`. | ||
| data.episodes[].offers[].category | string | No | Blu-Ray | Format label shown for the offer, for example `Blu-Ray`. | ||
| data.episodes[].offers[].currency | string | No | USD | Currency of `price`, as an ISO 4217 code such as `USD`. | ||
| data.episodes[].offers[].monetization_type | string | No | RENT | How the title is offered: `FLATRATE`, `FREE`, `ADS`, `RENT` or `BUY`. | ||
| data.episodes[].offers[].presentation_type | string | No | 4K | Picture format of the offer, for example `HD` or `4K`. | ||
| data.episodes[].offers[].price | number | No | 4.99 | Price of the offer in `currency`. Omitted for free and subscription offers without a price. | ||
| data.episodes[].offers[].provider | string | No | Amazon Video | Name of the provider offering the title, for example `Amazon Video`. | ||
| data.episodes[].offers[].provider_id | integer | No | 10 | JustWatch id of the provider. | ||
| data.episodes[].offers[].provider_short | string | No | amz | Short provider code, for example `amz`. | ||
| data.episodes[].offers[].provider_technical | string | No | amazon | Technical provider name used by JustWatch, for example `amazon`. | ||
| data.episodes[].offers[].url | string | No | Link to watch or buy the title at the provider. | |||
| data.episodes[].path | string | No | JustWatch page path of the episode. | |||
| data.episodes[].poster_url | string | No | URL of the still or poster image for the episode. | |||
| data.episodes[].title | string | No | Long Day's Journey Into Night | Episode title in the requested language. | ||
| data.episodes[].url | string | No | Full JustWatch page URL of the episode. | |||
| data.episodes[].year | integer | No | 2022 | Release year of the episode. | ||
| data.language | string | No | en | Two-letter language code used for titles and descriptions. | ||
| data.season | object | No | Season the episodes belong to. | |||
| data.season.description | string | No | Short synopsis of the season. | |||
| data.season.id | string | No | tss297253 | JustWatch season id, for example `tss297253`. | ||
| data.season.object_id | integer | No | 297253 | Numeric JustWatch id of the season. | ||
| data.season.object_type | string | No | SHOW_SEASON | JustWatch object type, `SHOW_SEASON` for seasons. | ||
| data.season.path | string | No | /us/tv-show/from/season-1 | JustWatch page path of the season. | ||
| data.season.poster_url | string | No | https://images.justwatch.com/poster/320190730/s718/season-1.jpg | URL of the poster image for the season. | ||
| data.season.season_number | integer | No | 1 | Number of the season within the show. | ||
| data.season.title | string | No | Season 1 | Season title, for example `Season 1`. | ||
| data.season.url | string | No | https://www.justwatch.com/us/tv-show/from/season-1 | Full JustWatch page URL of the season. | ||
| data.season.year | integer | No | 2022 | Release year of the season. | ||
| msg | string | No | OK |
| Status | Description | Schema |
|---|---|---|
| 400 | Bad Request | #/definitions/app.Response |
| 404 | Not Found | #/definitions/app.Response |
| 429 | Too Many Requests | #/definitions/app.Response |
| 503 | Service Unavailable | #/definitions/app.Response |
Use environment variables for secrets and keep Crawlora API keys server-side.
curl -X GET "https://api.crawlora.net/api/v1/justwatch/season/episodes?season_id=tss297253&country=us&language=en" \
-H "x-api-key: $CRAWLORA_API_KEY"