Querying single episodes & seasons

hecks wrote:
Apologies if I've missed it in the API docs, but how might we retrieve info for a single episode, along the lines of the old TVRage QuickInfo API:
services.tvrage.com/tools/quickinfo.php?sid=1&ep=1x01
services.tvrage.com/tools/quickinfo.php?show=Foo&ep=1x01&exact=1

Otherwise as far as I can see, currently we can only retrieve the full episode list for all seasons of an entire series, and with all of the cruft this can get quite hefty. I don't always need full episode summaries, for instance, so it might save us both bandwidth if there was an option to return results without them. The same goes for seasons - I might only want eps for the most recent one, or only the second, etc.

TIA

It's not on the documentation page yet i think, but what i did find was: http://api.tvmaze.com/episodes/{id}. The id is the id of the episode.

I can't find any link directly to a season, maybe David or Jan can tell us :)

atticweb wrote:
It's not on the documentation page yet i think, but what i did find was: http://api.tvmaze.com/episodes/{id}. The id is the id of the episode.
I can't find any link directly to a season, maybe David or Jan can tell us :)

Sure, that's the endpoint returned in e.g. _links from other queries, but what I was looking for was a way of querying a single episode when you don't know the episode ID but just the show name/ID & season number & episode number. Or getting all eps in a season.

I think it's rather a common case that you will have stored show information locally, but will only want to add episode information as it becomes available or as you build your library either by individual eps or by season. Or if you want to do a quick direct search say for IRC. For this it's somewhat inconvenient to keep downloading the entire episode list and updating local caches. This is one of the reasons that TVRage's QuickInfo API was more popular than TheTVDB's.

Although the latter does have one very useful feature that might be implemented here: finding an episode by airdate, especially handy for daily shows with ginormous season & ep lists and when you don't know the season/ep numbers:

/api/GetEpisodeByAirDate.php?seriesid=1000&airdate=2015-09-24

Thanks.

I'm not convinced yet about the usecases for such an endpoint, but I'll keep listening :-)

In the most common scenarios - a show's previous and next episode - you can retrieve those episode's details together with the show information in a single request. For example: http://api.tvmaze.com/shows/1?embed=previousepisod...

If you're building a local cache of a given show's episode list, updating it by only requesting a single episode's data would be a bad practice. Episodes are shuffled around by their networks quite frequently, and when that happens it usually affects more than just a single episode, so you should just request the entire episode list again and compare/overwrite what you have locally.

The only valid reason would be if you're really only interested in the details for one specific individual episode. I'm not sure how common this would be, can you give some examples of when this would be useful?

The TVRage QuickInfo API (and the related.../episodeinfo.php?sid=1&ep=1x01) was the most commonly queried one, so that should give you some idea of its usefulness to users and why it was favoured over the otherwise superior TheTVDB ;) Network reshuffling isn't really at issue, embedding previous/next (as TVRage also did) is handy but not always flexible enough. I'm not sure how to explain the use cases more on an open forum like this, are you anywhere on IRC perhaps?

I believe you if you say it was very popular, but I'd like to understand the use cases first so I can decide whether it is also the best possible solution. :)

I prefer an open discussion for other people's references, but if you'd like to share something in private, you can email me at $nickname at tvmaze dot com.

I have to agree with David on this one, I can't think of a great use-case where I wouldn't want to store locally and update everything periodically. That's exactly what I do, I store my show data in an SQL database and once a day I get new info for everything, updating names/dates etc. if they are different. That way, for the rest of the day when my program is using the data I'm not actually calling the TV Maze API anymore, just querying my my SQL database.

Even in the case that you do REALLY just want information for one specific episode, the overhead from grabbing all episodes and parsing to the one you want is very small, and can be done with just a few lines of code. I would also be curious to know how people would use this proposed endpoint.

Heh, I don't think I'm very good at explaining these things, but I'll try.

I currently have about 12,000 series tracked, and was using TVRage for most of the last 7 years. I already know each season & ep number, and all I really need extra is the ep title and airdate, and only when each ep presents itself to be added to local info (in not completely predictable fashion). This is most often on the day of broadcast, but also often not. For many series, i'll only need partial season info. I'm not really inclined to keep 12,000 full series caches with complete episode info updated, and it's not really necessary to do so. So with TVRage it was pretty straightforward to build caches from country schedules a couple of times a day and use those as much as possible (as you can with TVMaze). The ratio of cache hits to misses was surprisingly consistent over the long term: 1:2. Many of the misses can be made up from previously stored info, but many cannot. Quickinfo helped to fill the gaps in an efficient way without hitting the server too hard, but even previous ep info doesn't always help (with daily shows in particular if it's a while later). For the remainder, direct season/ep lookup solved most problems.

Another small example, for a different context: One Piece currently has 17 seasons, 710 eps and continuing. I want to write an efficient script for IRC to, say, look up the episode title for episode 665 on TVMaze. Currently my only option is to download the whole lot each time, and parse the results for the ep I need. This is heavier than it needs to be. Do I then cache for possible future searches, and keep that cache updated? I'd really rather not for throwaway searches. Or Letterman had 22 seasons and 6,028 eps. I want to know what the full title of his show on 2015-05-04 was. Currently I can get that info easily from TheTVDB using its GetEpisodeByAirDate endpoint.

This is a nice site, and I'm sure will appeal to many looking for an alternative to Trakt or TV.com for personal tracking & social stuff, and TVRage former editors who want to continue their work here. But if the API doesn't offer any more functionality than TheTVDB already does, then it would probably make more sense for me to just use their API and track their db updates in the more laborious TVDB way through their ../api/Updates.php?type=all&time=<previoustime> endpoint, since its catalog is more complete than this one.

But I'm sure I've bored you all enough with this by now, and if others don't chip in wanting this then of course there's little point wasting your time. Thanks for reading!

Hmm, obviously I have different needs than what you described but I still can't quite understand the IRC example. If I don't know the title (since that's what you want to find out), how would I possibly know the episode number?

I'm starting to see your point with the first example though. I suppose the question is how tough would this be to implement for David and the team :)

@hecks Your explanation was pretty good and not too boring ;-)

FYI, we definitely don't mean to only cater to clients that keep a local cache. Hitting our API on-demand is fine, if you've decided that it's more efficient to you than caching our data.

On the other hand, I want to encourage clients to consume as much information as they need in one single call. But I understand that fetching an episode list that's potentially thousands of episodes large isn't very efficient if you only care about a single episode.

Allow me to think about this for a little bit longer.

I would like to add an example of where the single episode search could useful as that is what I was using with tvrage. I wrote an app that helps to manage video files for TV series. Basically, given a video file that contains the series name, season number and episode number, it can lookup the episode name, format the file name in a tidy, consistent way, then move it to a folder for organization. The source could be a DVR file or a Downloaded torrent or whatever. Since I primarily use the app for organizing the video files as the episodes air, I rarely need to get the episode titles for a whole season at a time, only for a specific episode. This makes downloading the whole season, or in this case the whole series, somewhat inefficient.

That being said, I've already updated my app to download and cache the series, then search through the cache before looking online again. Since this API is MUCH faster than the tvrage API, I'd say that overall it's quite an improvement.

For the curious, TheTVDB's new beta API v2 (RESTful & json this time!) does it like so:

.../series/290853/episodes/query?airedSeason=1&airedEpisode=2

.../series/81797/episodes/query?absoluteNumber=665

Browse the beta API here: https://api-beta.thetvdb.com/swagger

I've been thinking about this, and if I add this call I want to place it under the show ID, not under a text-search-based endpoint. Happy to see that you all seem to agree there.

The only reason I'm still hestitant is the numbering. If your source uses a different numbering scheme than TVmaze and you only request a single episode's details, you'll quietly get the wrong information; while the episode list forces you to look at it in a broader context. But on the other hand if you're aware of this (in 99% of the shows everything probably aligns properly) and fine with it, I'd rather create this endpoint than have you download a complete episode list and throw nearly all of the response away.

Indeed, there are always some problematic series where the various interested parties disagree on correct season/ep numbering and start religious wars, and there are proxies and the like for handling the translation depending on use cases. I think it's always best for each site to make its own decisions based on its own well-defined, transparent rules and - crucially! - apply those consistently. Then we at least know where the pain points are likely to be and can work around them.

Single episode lookup by airdate alone (as TheTVDB allows) can also solve many problems.

+1 on the need for querying a single episode via API call.

from rage this was previously done like this > $this->xmlEpisodeInfoUrl."&sid=".$rageid."&ep=".$series."x".$episode;

currently having to download 5000+ elements of Eastenders episode information to loop through only to find a single element. Its painfully slow.

Don't care if its via the Maze ID, or tvdb/something else.

Well all right then.

Consider these calls beta for the next couple of days - I reserve the right to change them or delete them entirely :-)

http://api.tvmaze.com/shows/45/numberedepisode?season=2&number=1

This either returns an episode's details, or a HTTP 404.

http://api.tvmaze.com/shows/243/datedepisodes?date=2015-09-29

http://api.tvmaze.com/shows/109/datedepisodes?date=2015-09-27

This either returns an array of 1 or more episodes, or a HTTP 404.

Please check it out and send your feedback!

That looks great at first glance, thanks, I'll have a go at implementing it this week if I can and give you feedback.

It would also be handy if &season=1 without &ep= could return a whole season listing, currently it errors without the required second parameter.

One thing to consider for the future: you may (or may not!) want at some stage to distinguish between aired & DVD & absolute number ordering like TheTVDB does, but I guess an extra parameter for that endpoint could handle that should the need ever arise.

thanks.

is it always the plan that the summary field includes html markup? wouldn't it be better that the data contains no presentation? we are currently having to strip out tags.

"summary":"<p>After a military convoy is bombed on a New Orleans bridge, Pride and the team plan a dangerous undercover operation to retrieve a stolen missile and prevent an attack on a U.S. Naval ship.</p>"

hecks wrote:
That looks great at first glance, thanks, I'll have a go at implementing it this week if I can and give you feedback.
It would also be handy if &season=1 without &ep= could return a whole season listing, currently it errors without the required second parameter.

One thing to consider for the future: you may (or may not!) want at some stage to distinguish between aired & DVD & absolute number ordering like TheTVDB does, but I guess an extra parameter for that endpoint could handle that should the need ever arise.

Thanks! I think requesting the episode list for one season would belong in a different endpoint entirely.

Different numbering schemes - like DVD order - are definitely on our radar. If we'll add it, it'll be added to the API as well.

newznab wrote:
thanks.
is it always the plan that the summary field includes html markup? wouldn't it be better that the data contains no presentation? we are currently having to strip out tags.
"summary":"<p>After a military convoy is bombed on a New Orleans bridge, Pride and the team plan a dangerous undercover operation to retrieve a stolen missile and prevent an attack on a U.S. Naval ship.</p>"

I've heard mixed responses on the summaries containing HTML. Removing them would break BC though, and including both a HTML and a non-HTML version would be a huge waste. So it'll be like this for the forseeable future; at least until we feel the need to start a new API version.