/LRTVDBAPIClient

Objective-C wrapper for TheTVDB

Primary LanguageObjective-CMIT LicenseMIT

LRTVDBAPIClient

LRTVDBAPIClient is a simple and efficient Objective-C wrapper for TheTVDB.

It supports:

  • Search for shows based on a specified query.
  • Retrieve a list shows for the given TVDB shows IDs.
  • Retrieve a list episodes for the given TVDB episodes IDs.
  • Get the correct episode for the specified season and number.
  • Get all the TV Show artwork information.
  • Get all the TV Show actors information.
  • Update a lists of shows.
  • Persist/retrieve a list of shows to/from disk.
  • Support for every TVDB language.

Install

  1. Using CocoaPods

Add LRTVDBAPIClient to your Podfile:

platform :ios, "5.1"
pod 'LRTVDBAPIClient'

Run the following command:

pod install

Finally, import SystemConfiguration and MobileCoreServices frameworks to avoid AFNetworking warnings.

  1. Manually

Clone the project or add it as a submodule (use --recursive option so associated submodules are updated).

git clone --recursive git://github.com/luisrecuenco/LRTVDBAPIClient.git

Drag LRTVDBAPIClient folder to your project and add AFNetworking, TBXML and zipzap projects (available in Vendor folder). You can see instructions on how to add them in their github pages (see credits section below).

Configuration

You may specify your TVDB API key in the property apiKey in TVDBAPIClient class.

You may also set the desired language to use (via language property in TVDBAPIClient). If no language is provided, the default device one will be used (or English if the latter is not supported by TheTVDB).

Usage

The code is divided in four main categories:

  • Model: LRTVDBShow, LRTVDBEpisode, LRTVDBImage and LRTVDBActor.
  • Persistence Manager: LRTVDBPersistenceManager.
  • Parser: LRTVDBAPIParser.
  • API Client: LRTVDBAPIClient.

The main class that has all the important methods to retrieve the information from TheTVDB is LRTVDBAPIClient. Let's explain further what you can do with it.

Search for shows based on a specified query

- (void)showsWithName:(NSString *)showName 
      completionBlock:(void (^)(NSArray *shows, NSError *error))completionBlock;

The result of the method is an array of LRTVDBShow objects with some basic information provided by TheTVDB (name, ID, overview, IMDB ID, bannerURL…). In order to retrieve more detailed information, such as episodes, artwork or actors, you can use the following method.

Retrieve a list shows for the given TVDB shows IDs

- (void)showsWithIDs:(NSArray *)showsIDs 
     includeEpisodes:(BOOL)includeEpisodes 
       includeImages:(BOOL)includeImages 
       includeActors:(BOOL)includeActors 
     completionBlock:(void (^)(NSArray *shows, NSDictionary *errorsDictionary))completionBlock;

shows: array of LRTVDBShow objects. errorsDictionary: @{showID : NSError}.

Retrieve a list episodes for the given TVDB episodes IDs

- (void)episodesWithIDs:(NSArray *)episodesIDs 
        completionBlock:(void (^)(NSArray *episodes, NSDictionary *errorsDictionary))completionBlock;

episodes: array of LRTVDBEpisode objects. errorsDictionary: @{episodeID : NSError}.

Get the correct episode for the specified season and number

- (void)episodeWithSeasonNumber:(NSNumber *)seasonNumber 
                  episodeNumber:(NSNumber *)episodeNumber 
                  forShowWithID:(NSString *)showID 
                completionBlock:(void (^)(LRTVDBEpisode *episode, NSError *error))completionBlock;

Get all the TV Show artwork information

- (void)imagesForShowWithID:(NSString *)showID 
            completionBlock:(void (^)(NSArray *images, NSError *error))completionBlock;

images is an array of LRTVDBImage objects.

Get all the TV Show actors information

- (void)actorsForShowWithID:(NSString *)showID 
            completionBlock:(void (^)(NSArray *actors, NSError *error))completionBlock;

actors is an array of LRTVDBActor objects.

Update a lists of shows

- (void)updateShows:(NSArray *)showsToUpdate 
      checkIfNeeded:(BOOL)checkIfNeeded 
     updateEpisodes:(BOOL)updateEpisodes 
       updateImages:(BOOL)updateImages 
       updateActors:(BOOL)updateActors 
    completionBlock:(void (^)(BOOL finished))completionBlock;

showsToUpdate will be updated with the latest information of the shows. When all the shows have been updated, the block will be called with a boolean indicating the success of the operation. The best way to update a show without having to wait for the block to execute (i.e., waiting for every show update to finish) is to watch the desired properties via KVO.

checkIfNeeded is used to force the update when the show doesn't need to get updated (see method documentation for further explanation).

Persist/retrieve a list of shows to/from disk.

- (void)saveShowsInPersistenceStorage:(NSArray *)shows;
- (NSArray *)showsFromPersistenceStorage;

Example

The project contains a complete example of a TV Show Tracker App. You can search for shows, add them to your library, see the episodes, mark them as seen, share on Twitter and Facebook... everything you would expect from an app of this kind. The example uses CocoaPods, so you only have to do pod install in the Example folder and open the workspace.

Requirements

LRTVDBAPIClient requires both iOS 5.1 and ARC.

You can still use LRTVDBAPIClient in your non-arc project. Just set -fobjc-arc compiler flag in every source file.

Credits

LRTVDBAPIClient uses the following third party libraries:

Contact

LRTVDBAPIClient was created by Luis Recuenco: @luisrecuenco.

Contributing

If you want to contribute to the project just follow this steps:

  1. Fork the repository.
  2. Clone your fork to your local machine.
  3. Create your feature branch.
  4. Commit your changes, push to your fork and submit a pull request.

License

LRTVDBAPIClient is available under the MIT license. See the LICENSE file for more info.