API v2 - update series

A place for developers to advertise their TheTVDB.com enabled app and get help from other developers with the API.
Posts: 2
Joined: Tue Jul 25, 2017 12:50 pm

API v2 - update series

Postby zomwarz » Mon Aug 21, 2017 2:51 pm

Hi all, do you know any way to know that has changed within a series?
I use the endpoint that returns the series that have been updated and the time in Unix format. But how can you know that you have changed from that series?

For example: I receive updates on the ID that corresponds to "General Hospital" I would not like to make a request for each episode (since I do not know which one has changed) since they are 10,000. I say it to make good use of TheTVDB. I would not mind doing it but I think it's wrong.

Taloth Saldono
Posts: 13
Joined: Sun Apr 17, 2016 2:25 am

Re: API v2 - update series

Postby Taloth Saldono » Sun Aug 27, 2017 10:08 am

The /series/{id}/episodes list (paged list of 100 items per page) has an lastUpdated field per episode which you can use to determine which episodes changed.

Posts: 197
Joined: Thu Jul 18, 2013 5:18 pm

Re: API v2 - update series

Postby wayned42 » Sun Sep 10, 2017 11:38 am

Yea, but this doesn't work well for larger series, since you have to re-fetch all the episodes for the whole series, page by page. For a long-running daily series that can be a hundred pages of basic episode info, most of which is already known and just wastes time and bandwidth. Then, after getting all that data, the app has to fetch the full-episode info for every episode that has an updated lastUpdated field. What would be nicer is for one ore more ways to streamline this:

(1) have a way to fetch full-episode info for changed episodes >= some {lastUpdated} time value. You could limit the number of episodes per page to something like 10 (since it is full-info, not basic info). Alternately, just having a lastUpdated filter for the current basic-info episode query and some way to fetch the missing extra info (see below) would also work well.

(2) have a way to fetch just a list of episode IDs and lastUpdated times for the whole show (maybe include seasonNumber and EpisodeNumber too, or have a separate option for that). One way would be to add an option to /series/{id}/epsidoes that restricts the returned data AND has a side-effect of increasing the number of episodes to several thousand ID-info-only-episdoes per page.

In addition to the above, there is an issue when someone is first loading a large show -- if an app wants full-episode info for the whole show, the developer has to page through a hundred pages or more of basic-episode info, and then fetch every single episode in the show (one at a time) for (what is often) several thousands of episode IDs. That's pretty horrible for both the site and the app. To fix this, the site should offer some sort of method to either kick-start the data, or a way to grab all the non-basic info in fewer api calls. For instance:

(1) and app could use method (1) above with an update time of "0" to fetch every episode for the show, but 10 at a time with full info means that the basic info isn't fetched twice and the number of api calls is 1/10 of the episode count.

(2) the site could offer a way to fetch all the missing extra (non-basic) info for the episodes. Rather than a page-through-all-the-extra-info-for-all episodes method it would probably be more useful to instead make the API have the caller specify up to 10 episode IDs per API call and get back just the non-basic info for every requested ID. This lets someone who has the newly-aquired basic info request all the missing info for the whole series AND lets someone who has a list of updated IDs get just that info (i.e. if the series filter had the lastUpdated filter for basic info).

(3) the site could offer a cached zip file of full-episode data that is only updated something like every 2 months or so. This allows an app to jump-start the data for a newly added show to get the vast majority of the data, at which point it could use one of the new update methods above to find all the episode IDs of newer/changed episodes and fetch just those (much smaller number of) individual episodes. Since the zipped data isn't updated very often (and doesn't need to be updated in a timely manner) the api users wouldn't be tempted to use it as a way to keep up-to-date on the latest data.


At the very least I'd like to see the /series/{id}/episode page get a lastUpdated filter and then add an api to fetch just non-basic episode info for up to 10 IDs at a time. That would be very simple to add and greatly help the API caller. Adding a cache for older (full-data) episodes would also be nice.

Return to “Developers”

Who is online

Users browsing this forum: No registered users and 1 guest