The Movie Database Support
Support → API Support
TV API Preview
posted by Travis BellSTAFFMOD on October 24, 2013 at 2:15 PM
Hey guys,
I know a lot of you have been waiting for this so here it is, the TV API.
We currently have 17 methods available:
GET '/3/tv/:id'
GET '/3/tv/:id/credits'
GET '/3/tv/:id/external_ids'
GET '/3/tv/:id/images'
GET '/3/tv/:id/translations'
GET '/3/tv/:id/season/:season_number'
GET '/3/tv/:id/season/:season_number/credits'
GET '/3/tv/:id/season/:season_number/external_ids'
GET '/3/tv/:id/season/:season_number/images'
GET '/3/tv/:id/season/:season_number/episode/:episode_number'
GET '/3/tv/:id/season/:season_number/episode/:episode_number/credits'
GET '/3/tv/:id/season/:season_number/episode/:episode_number/external_ids'
GET '/3/tv/:id/season/:season_number/episode/:episode_number/images'
GET '/3/tv/on_the_air'
GET '/3/tv/top_rated'
GET '/3/tv/popular'
GET '/3/search/tv'
GET '/3/discover/tv'
And 3 new person credit methods to support TV and external IDs:
GET '/3/person/:id/movie_credits'
GET '/3/person/:id/tv_credits'
GET '/3/person/:id/combined_credits'
GET '/3/person/:id/external_ids'
And also new credit, find and network namespace:
GET '/3/credit/:id'
GET '/3/find/:id'
GET '/3/network/:id'
Functionality wise, they work almost identical to movies or the way you expect things to work on v3. The most notable thing missing right now is getting to the TV credits from the person side of things. I'll be working on that this week.
Understandably, this is a preview release and should be considered a risk. Some data could change depending on the feedback I get and if you roll this out publicly you are assuming that risk. I don't expect it to be like this for long, maybe a few weeks. I'll let everyone know when the design is final.
Now go ahead everyone, test!
Open Tickets
- LH-298 - Create the method to list TV genres
Resolved Tickets
-
LH-296- Link up TV credits on people -
LH-292- Create a tv season credits method -
LH-300- Ensure 404 items get a proper not found response -
LH-302- Rename sort_order to order to match the movie credit order field -
LH-304- Rename the TV character_name field to character to keep it consistent with movies -
LH-309- Create the /tv/popular method -
LH-310- Create the /tv/top-rated method -
LH-294- Create the /discover/tv method -
LH-295- Create the /network/:id method -
LH-311- Create a /tv/:id/translations method -
LH-301- Search for TvSeries by an external id -
LH-312- Create the /tv/on_the_air method -
LH-313- Create the /tv/today method -
LH-297- Hook up the change methods to TV
Reply by Travis Bell
on November 5, 2013 at 9:40 AM
Indeed! Here's the tickets, LH-309 and LH-310.
That is correct.
Reply by Travis Bell
on November 5, 2013 at 7:15 PM
TV discover, top rated and popular methods are now live.
The discover method is pretty cool. Every wanted to see all of the HBO shows we have, ordered by highest rated?
Or how about what FX shows have premiered in since 2010?
Or what about the best comedies with a rating of 7.5 and higher ordered by popularity?
Cool.
Reply by javikr
on November 6, 2013 at 2:16 AM
Great @Travis!
I will try these new methods asap ;)
Thanks for your work!
Reply by Michael Welter
on November 6, 2013 at 11:45 AM
Nice. Just added support in Yammm. Thanks Travis
Reply by javikr
on November 6, 2013 at 12:08 PM
Hi again,
It would be fine also if exists any method for getting all the seasons and episodes for a tv show. Now you can obtain this data by calling 2 methods, it would be great if it you could obtain this info in only one api call ;)
Again, thank you very much for your work.
Best,
Reply by Travis Bell
on November 6, 2013 at 12:13 PM
I'm pretty sure sure that will ever exist. Some shows are just too big, like The Daily Show for example. You're talking about thousands of items in a single call. There is just no way to make that performant.
Reply by matbal
on November 7, 2013 at 5:27 AM
Hi guys,
thumbs up for the good work you do. Suggestion from my side would be to also provide /tv/latest endpoint. It would be really usefull for us.
Best, matej
Reply by javikr
on November 7, 2013 at 5:41 AM
Hello again,
Just two more suggestions:
Thanks again ;) Best,
Reply by Travis Bell
on November 7, 2013 at 8:44 AM
Yup, there will be a /latest method for sure. Here's the ticket.
Definitely possible but we rely on plot keywords for a lot of that. As soon as we have more data we can more seriously look at that.
We're only as good as the data that is entered. I don't see either a Spanish translation added nor an alternative title added for Spain. Feel free to add those and search will start working like you expect.
Reply by Zippie
on November 7, 2013 at 4:33 PM
Hey I've been implementing the API for a .NET wrapper I contribute on (https://github.com/LordMike/TMDbLib) and noticed a small discrepancy compared to previous search results. With other searches when you enter a page number that doesn't exist the total pages and total results columns are still populated, yet for the new tv show search that doesn't seem to be the case.
A side note, I find it quite strange that when for example you get a tv show by id it lists basic information about the related seasons. Yet it doesn't seem to populate the id for those objects. In most use cases this shouldn't be an issue since you just use the season number. But I do consider the id of an object to be basic information and expected it to be present.
Other than that great work! I'll let you know if I come across anything else while implementing the remaining new methods.
Reply by Travis Bell
on November 7, 2013 at 5:33 PM
I will look into this and see what the difference is.
There is no publicly queryable method to get a season or episode by an ID. It is assumed that the season and episode number pair is as unique as an id. Ie. Breaking Bad, season 1 episode 1 will always point to the correct object and is impossible to duplicate. Therefore, supplying a separate ID for this a waste.
Thanks!
Reply by Zippie
on November 8, 2013 at 6:42 AM
I completely agree but then why supply it in the details at all?
PS any plans to extend the new credit system over to movies? I realize this would be a breaking change but it would probably be helpful in the long run to have a consistent system
Reply by Travis Bell
on November 8, 2013 at 10:22 AM
Hi Zippie,
There are 2 main reasons that I provide it along side the episode and season responses:
With regards to the new credit system, yes there is plans and I should be able to roll it out without causing any breaking change HOWEVER, it requires a massive DB migration and this is not planned at this time. Meaning, it's on my list to do "one day" but not any time soon.
Thanks!
Reply by Zippie
on November 8, 2013 at 11:49 AM
Hio, thanks for the quick replies.
I did find another small bug, this time in the tv/top_rated returns. When you get page one it states that there are a total of 3 pages with a total of 54 entries. However when you retrieve page 2 it states that there are a total of 3 pages but 55 entries.
Again nothing major but just a bit strange :).
Reply by Travis Bell
on November 8, 2013 at 11:53 AM
That would be caused from different pages getting cached at different times. Since top rated only pulls TV shows with 2 or more votes right now this will be something that happens until we have a lot more ratings. It's the single biggest missing data right now and there's no way around it until we get more people using the TV data. And as we get more ratings I increase that limit so we get more accurate results. With so few ratings for TV shows right now it's set really low.