This morning, we woke up to an unusually high amount of questions in our inbox and social media channels. Apparently TheTVDB, another TV API provider, has been offline for the past day and people are looking for a backup plan.
Fortunately we can help. The TVmaze API has support for thetvdb ID's, which means you can use it without having to map your existing show database from scratch. Our API is public and doesn't require any registration or API keys which means you can start implementing it right away. We implement all modern standards like HTTPS and CORS so you can integrate it into any application.
Here are a few examples to help you get started. Imagine your app normally uses TheTVDB but you want to implement TVmaze as a fallback in case there are problems on their end. The recommended flow would be as follows:
1. Call the http://api.tvmaze.com/lookup/shows?thetvdb=81189 endpoint supplied with a show's thetvdb ID. In the response, you'll find all basic information about that show and most importantly its tvmaze ID in the property id.
2. While not absolutely required, we recommend saving the show's tvmaze ID locally so step #1 can be skipped in any subsequent updates.
3. Use the tvmaze ID to retrieve any additional information about the show. For example, hit http://api.tvmaze.com/shows/169/episodes to retrieve the show's complete episode list in a single request. Or use http://api.tvmaze.com/shows/169/cast for the show's cast list, complete with actor and character images.
4. Store the current timestamp locally in your application, so you can always look up when the data for that show has last been refreshed.
5. At some point in the future you'll want to refresh the data that you've stored locally. If you want to avoid wasting resources, start with fetching the http://api.tvmaze.com/updates/shows endpoint. In there, you'll find a dictionary that specifies for each show when it has last been updated on TVmaze's end. For the shows you want to refresh, compare your local timestamp (from step #4) with the timestamp on our end. If the TVmaze timestamp is larger than yours there's fresh data to retrieve, and you should repeat step #2 through #4.
Of course this is only a small subset of the features in the TVmaze API. We also offer searching for shows by their name, retrieving the full TV schedule for any country at any point in history of the future, looking up episodes for a given show by airdate or number, and much more. Read all about it here: http://www.tvmaze.com/api. If you do end up using us, the only thing we ask for is properly being credited according to our CC BY-SA license.
If you have any questions after reading this, please feel free to ask away in this blog or even better, in the API forums: http://www.tvmaze.com/forums/4/api. Our community will gladly help you out!
Written by david at Mar 10, 2017