Changes
A change object represents a future or past change in a streaming catalog.
It contains the details such as the type of the change
(could be past change such as like new
, updated
, removed
;
or a future change such as expiring
, upcoming
),
the affected item type (show
, season
or episode
), timestamp of the change and more.
Via change endpoints, you can get the most recent updates in the streaming catalogs.
On top of the changes, you can also get the details of the affected shows. Every change object
has a showId
field.
You can find the list of shows affected by the changes in the shows
field of the response, and match
the show ids with the showId
field of the change objects.
Endpoints
The Changes object
Properties
- Name
changeType
- Type
- string enum
- Description
Type of the change.
- Enum values
- Name
itemType
- Type
- string enum
- Description
Type of the item affected from the change.
- Enum values
- Name
showId
- Type
- string
- Description
Id of the show affected from the change.
- Name
showType
- Type
- string enum
- Description
Type of the show affected from the change.
- Enum values
- Name
season
- Type
- nullable integer
- Description
Number of the season affected from the change. Omitted if
item_type
is notseason
orepisode
.
- Name
episode
- Type
- nullable integer
- Description
Number of the episode affected from the change. Omitted if
item_type
is notepisode
.
- Name
service
- Type
- object
- Description
Service affected from the change.
- Child properties
- Name
streamingOptionType
- Type
- string enum
- Description
Type of the streaming option.
- Enum values
- Name
addon
- Type
- nullable object
- Description
Addon info, if the
streamingOptionType
isaddon
. Otherwise omitted.- Child properties
- Name
timestamp
- Type
- nullable integer
- Description
Unix Time Stamp of the change. Past changes (
new
,updated
,removed
) will always have a timestamp. Future changes (expiring
,upcoming
) will have a timestamp if the exact date is known. If not, timestamp will be omitted, e.g. a show is known to be expiring soon, but the exact date is not known.
- Name
link
- Type
- nullable string
- Description
Deep link to the affected streaming option's page in the web app of the streaming service. This field is guaranteed to be populated when
changeType
isnew
,updated
,expiring
orremoved
. WhenchangeType
isupcoming
, this field might be populated or null depending on if the link of the future streaming option is known.
Examples
- "new"
- "show"
- "11274"
- "movie"
- {} 5 keys▶
- "subscription"
- 1726792673
- "https://www.peacocktv.com/watch/asset/movies/pulse/13c8232e-ca6b-3785-b776-a114849fcef0"
Get Changes
Query the new, removed, updated, expiring or upcoming movies/series/seasons/episodes in a given list of streaming services.
Results are ordered by the date of the changes.
Changes listed per page is 25
.
Changes are listed under changes
field, and shows affected by these changes are listed under shows
field.
Note that upcoming
changes are only supported for Apple TV, Disney+, Max, Netflix and Prime Video.
For other services, upcoming
changes will return an empty list.
Required parameters
- Name
country
- Type
- string
- Description
ISO 3166-1 alpha-2 code of the target country. See
/countries
endpoint to get the list of supported countries.- Example values
- Name
change_type
- Type
- string enum
- Description
Type of changes to query.
- Enum values
- Name
item_type
- Type
- string enum
- Description
Type of items to search in. If
item_type
isshow
, you can useshow_type
parameter to only search for movies or series.- Enum values
Optional parameters
- Name
catalogs
- Type
- array of strings
- Description
A comma separated list of up to 32 catalogs to search in. See
/countries
endpoint to get the supported services in each country and their ids.When multiple catalogs are passed as a comma separated list, any show that is in at least one of the catalogs will be included in the result.
If no catalogs are passed, the endpoint will search in all the available catalogs in the country.
Syntax of the catalogs supplied in the list can be as the followings:
-
<sevice_id>
: Searches in the entire catalog of that service, including (if applicable) rentable, buyable shows or shows available through addons e.g.netflix
,prime
,apple
-
<sevice_id>.<streaming_option_type>
: Only returns the shows that are available in that service with the given streaming option type. Valid streaming option types aresubscription
,free
,rent
,buy
andaddon
e.g.peacock.free
only returns the shows on Peacock that are free to watch,prime.subscription
only returns the shows on Prime Video that are available to watch with a Prime subscription.hulu.addon
only returns the shows on Hulu that are available via an addon,prime.rent
only returns the shows on Prime Video that are rentable. -
<sevice_id>.addon.<addon_id>
: Only returns the shows that are available in that service with the given addon. Check/countries
endpoint to fetch the available addons for a service in each country. Some sample values are:hulu.addon.hbo
,prime.addon.hbomaxus
.
-
- Example values
- Name
show_type
- Type
- string enum
- Description
Type of shows to search in. If not supplied, both movies and series will be included in the search results.
- Enum values
- Name
from
- Type
- integer
- Description
Unix Time Stamp to only query the changes happened/happening after this date (inclusive). For
past
changes such asnew
,removed
orupdated
, the timestamp must be between today and31
days ago. Forfuture
changes such asexpiring
orupcoming
, the timestamp must be between today and31
days from now in the future.If not supplied, the default value for
past
changes is31
days ago, and forfuture
changes is today.- Example values
- Name
to
- Type
- integer
- Description
Unix Time Stamp to only query the changes happened/happening before this date (inclusive). For
past
changes such asnew
,removed
orupdated
, the timestamp must be between today and31
days ago. Forfuture
changes such asexpiring
orupcoming
, the timestamp must be between today and31
days from now in the future.If not supplied, the default value for
past
changes is today, and forfuture
changes is31
days from now.- Example values
- Name
include_unknown_dates
- Type
- boolean
- Description
Whether to include the changes with unknown dates.
past
changes such asnew
,removed
orupdated
will always have a timestamp thus this parameter does not affect them.future
changes such asexpiring
orupcoming
may not have a timestamp if the exact date is not known (e.g. some services do not explicitly state the exact date of some of the upcoming/expiring shows). If set astrue
, the changes with unknown dates will be included in the response. If set asfalse
, the changes with unknown dates will be excluded from the response.When ordering, the changes with unknown dates will be treated as if their timestamp is 0. Thus, they will appear first in the ascending order and last in the descending order.
- Default value:
false
- Name
cursor
- Type
- string
- Description
Cursor is used for pagination. After each request, the response includes a
hasMore
boolean field to tell if there are more results that did not fit into the returned list. If it is set astrue
, to get the rest of the result set, send a new request (with the same parameters for other fields), and set thecursor
parameter as thenextCursor
value of the response of the previous request. Do not forget to escape thecursor
value before putting it into a query as it might contain characters such as?
and&
.The first request naturally does not require a
cursor
parameter.
- Name
order_direction
- Type
- string enum
- Description
Determines whether to order the results in ascending or descending order.
- Enum values
- Name
output_language
- Type
- string enum
- Description
ISO 639-1 code of the output language. Determines in which language the output will be in.
- Default value:
en
- Enum values
Request
curl -G https://streaming-availability.p.rapidapi.com/changes \ -H "X-RapidAPI-Key: {YOUR_API_KEY}" \ --data-urlencode country="us" \ --data-urlencode catalogs="netflix" \ --data-urlencode change_type="new" \ --data-urlencode item_type="show" \ --data-urlencode show_type="movie"
Response
200
- [] 25 items▶
- {} 25 keys▶
- true
- "1727054449:171709245"